DWR: Frequently Asked Questions

What is the best way to learn about DWR?

DWR is a Java library that enables Java on the server and JavaScript in a browser to interact and call each other as simply as possible. You can find more information at Direct Web Remoting portal (http://directwebremoting.org/dwr/documentation/). You can start with the following:

• DWR: Easy AJAX for JAVA at http://directwebremoting.org/dwr/introduction/index.html
• Getting Started with DWR at http://directwebremoting.org/dwr/introduction/getting-started.html
• Official Examples - dwr.war at http://directwebremoting.org/dwr/introduction/tutorials.html

How are Spring and DWR connected?

Jive SBS configures DWR with Spring. You can fin the configurations in spring-dwrContext.xml. For more information, see DWR and Spring at http://directwebremoting.org/dwr/documentation/server/integration/spring.html.

Here is an example Spring config:

    <bean id="remoteCommunityUtils" class="com.jivesoftware.community.dwr.RemoteCommunityUtils" parent="remoteSupport">
        <dwr:remote javascript="CommunityUtils">
            <dwr:include method="setUserCommunityListProperty"/>
            <dwr:include method="closeCustomizeWidgetMessageProperty"/>
            <dwr:include method="setUserDefaultTab"/>
        </dwr:remote>
    </bean>

In the above example, the element <dwr:remote javascript="CommunityUtils" defines the name of the Javascript file or object you refer to in your theme code.

To make use of this, you'd put this in your file:

<@resource.dwr file="CommunityUtils"/>

And you'd make a call like this:

<@resource.javascript>CommunityUtils.setUserDefaultTab("Overview")</@resource.javascript>

What are some DWR best practices?

You should always explicitly include what methods you want to expose through your javascript using the <dwr:include> element.  Otherwise the default is to expose all the methods, which can present huge security risks.  Even if things are alright now, any methods people add in the future will be exposed, so it's safest to be explicit.

How do you make use of DWR in your theme template?

Here is an example of what you need to do to use the Watches remote object in your template:

<@resource.dwr utils="true" file="Watches"/>

How do I get access to common methods or objects from the DWR context?

In your Spring configuration extend the Spring Bean remoteSupport. Here is the remoteSupport definition and what's available there:

    <bean id="remoteSupport" class="com.jivesoftware.community.dwr.RemoteSupport" abstract="true">
        <property name="authenticationProvider" ref="authenticationProvider"/>
        <property name="userManager" ref="userManager"/>
        <property name="localeManager" ref="localeManager"/>
    </bean>

And here is an example definition extending it (parent attribute):

    <bean id="remoteCommunityUtils" class="com.jivesoftware.community.dwr.RemoteCommunityUtils" parent="remoteSupport">
        <dwr:remote javascript="CommunityUtils">
            <dwr:include method="setUserCommunityListProperty"/>
            <dwr:include method="closeCustomizeWidgetMessageProperty"/>
            <dwr:include method="setUserDefaultTab"/>
        </dwr:remote>
    </bean>

Think of this as the DWR context equivalent of extending JiveActionSupport for your Action classes.

How do I get i18n text into the DWR context?

RemoteSupport has methods for getting i18n text in the dwr context (since you don't have a struts action like usual).

How do I use callbacks with DWR?

Here's an example:

OpenSearchQuery.getSearchResultsByEngineID(${engine.ID?c}, osSearchTerm, {
                   callback:function(data) {
                       writeOSResults(data, ${engine.ID?c});
                    },
                    errorHandler:function(errorString, exception) {
                        $("jive-search-opensearch-${engine.ID?c}").innerHTML = "<span style=\"color:red\"><@s.text name="search.results.os.error.label" /></span>";
                     }});

If a DWR method is returning something, then that javascript method call accepts a callback closure as the final argument. The example above shows an example with the callback function, and an explicit errorHandler function. The default behavior if you don't specify an errorHandler is to throw up a javascript alert, so while optional, the errorHandler can improve your user experience.