Developing WW Ajax Widgets

This page is intended for WW developer not for WW users. If your a user of WW hopefully you dont need to know these details, but certainly more knowledge is better, so if your hungry eat up!

The WW ajax/dhtml components use the DOJO Toolkit for both javascript event handling and AJAX calls.

To understand the widget framework this page is a must read:
http://dojotoolkit.org/docs/fast_widget_authoring.html

To understand the dojo event framework which is used extensively by the widget framework read this:
http://dojotoolkit.org/docs/dojo_event_system.html

OK Great so your smart on DOJO Widgets and DOJO Events lets see how WW uses these.

WW Tag Code

Lets start with looking at what a user of WW would include in their page, a JSP in this case:

<ww:a
        id="link1"
        theme="ajax"
        href="/AjaxRemoteLink.action"
        showErrorTransportText="true"
        errorText="An Error ocurred">Update</ww:a>

This is just a standard WW component. All the attributes defined here must map to a component class thats defined in the taglib.tld. Were not going to go into how the WW componets work in this discussion, just be assured that nothing different happens here.

WW Component Template Code

WW via the component system will read in the ajax/a.ftl file to determine how to generate the following html file. Again this is standard WW Component processing so well breeze over this.

WW Generated Code

Now lets look at what this snippet of code would generate for us in html:

<a dojoType="BindAnchor" evalResult="true" id="link1" href="/ajax/AjaxRemoteLink.action" errorHtml="An Error ocurred" showTransportError="true">Update</a>

Lets review this file. The dojoType type tells the dojo parser what to do with this tag. This is going to need to correspont to a call in our widge file like:
dojo.widget.tags.addParseTreeHandler("dojo:BindAnchor");
All the other attributes are basically passthrough from our component code to our widget code. No real magic happening w/ them.

Dojo Widget File

Next up lets look at some snippets of the widget file:

webwork.widgets.HTMLBindAnchor = function() {
//lots removed for clarity
	this.widgetType = "BindAnchor";
	this.templatePath = dojo.uri.dojoUri("webwork/widgets/BindAnchor.html");
//lots removed
		self.anchor.href = "javascript:{}";

		dojo.event.kwConnect({
			srcObj: self.anchor,
			srcFunc: "onclick",
			adviceObj: self,
			adviceFunc: "bind",
			adviceType: 'before'
		});
		
//snippet removed		
    }

}


// make it a tag
dojo.widget.tags.addParseTreeHandler("dojo:BindAnchor");

There are three aspects in this code snippet that are worth review. The declaration of the templatePath. This defines to DOJO where the prototype for its component lives. DOJO is going to read this component to determine what event binding needs to happen (TODO: a better description here). Were going to look at this template file in a moment, this file is where the real magic happens. The second aspect of this file is the kwConnect call... this is the ajax call to the remote source. I removed the snippet that happens afterwards but its not important here. And the final aspect worth understanding now is the last line. This tells dojo that this widget is registered as the name BindAchor... recall the dojoType="BindAnchor" in the above HTML snippet.

Dojo Template File

Now lets review the template file... BindAnchor.html... Understanding the template files were the big realization moment for me.