DojoFaces tag documentation DojoFaces tag documentation

DojoFaces

DojoFaces aims

Dojo provides cool cross browser javascript widgets that enable full featured GUI clients running on javascript in a browser. JSF developers who want to use dojo need to find a way to connect the dojo widgets with their backing beans. With Facelets we can build templates that connect dojo widgets with standard JSF tags. These templates are packaged as tags in a jar. Using templates with standard JSF tags we achieve portability from JSF 1.1 up to JSF 2.0. Furthermore you can easily take a template out of the jar, modify it and use it separately. DojoFaces is released under the Apache License to give you all legal right to do so.

All tags have full AJAX support. With Dojo it's good practice to reduce roundtrips and use AJAX whereever possible to avoid time consuming page startups. Here's the link to our examples page to demonstrate the features. The examples are available as war file for download.

Community support is available on dojofaces-users@lists.sourceforge.net, please subscribe before posting. For commercial support please specify your needs on support@dojofaces.com and we will send an offer. Commercial support includes fixed response times, training and project startup support in english or german language.

The DojoFaces download does NOT include a wrapped Dojo version. Download and install Dojo separately from the Dojo site. The DojoFaces tags rely on a ready installed Dojo release, render standard HTML via standard JSF tags and dojofy them programmatically via Javascript.

DojoFaces is a JSF tag library but not a component library. Using component libraries can lead to problems with JSF upgrades, platform changes (like appserver change or portlet usage) or implementation bugs. DojoFaces provides implementation patterns to connect Dojo and JSF and wraps the more sophisticated ones in template tags. With this template based tag library approach you get well tested Dojo JavaScript together with highly stable standard JSF components to bring you cross JSF version, cross browser, cross Dojo version, cross AJAX library compatible patterns and tags.

DojoFaces prerequisites

DojoFaces requires working Facelets and Dojo installations. All popular versions are supportet:

  • JSF spec 1.1 or 1.2 in conjunction with Facelets 1.1.14 as well as JSF 2.0 (Facelets included)
  • Dojo >= 1.2.3
  • JDK >= 1.5

DojoFaces usage

Integrate dojo with your XHTML page as described in the dojo docs. Basically you add dojo styles and dojo scripts to the HEAD section of your document. You can download Dojo from http://dojotoolkit.org/. Get help with your first Dojo page at http://dojotoolkit.org/reference-guide/quickstart/.

Now download the release and put the contained jar on your classpath.

Refer to the taglib with: xmlns:dojo="http://j4fry.org/dojo"

Dojo JavaScript can be added either with declarative or with programmatic syntax. HTML tags with dojoType="..." attribute form the declarative dojo usage and require parseOnLoad:true in djConfig. Programmatic syntax constructs Dojo widgets in script sections through JavaScript constructors. DojoFaces tags generate programmatic Dojo code, so parseOnLoad:false is sufficient for DojoFaces if your application doesn't use Dojo declaratively.

When should you use declarative Dojo tags, when to use Dojo programmatically and which are the proper places to put DojoFaces tags? There are two reasons to use a DojoFaces tag: If you have a form value to submit to your server model, DojoFaces connects the Dojo widget to a JSF component and this way sends user input to the server model. And if you want to use a Dojo widget that connects to a dojo.data.Store then dojo:store will retrieve server data for you, provide them to the Dojo widget and even post eventual changes back to the server model.

OTOH if you don't have a value to post back and no store to connect to then a simple declarative dojo tag is sufficient. E.g. you might want to add a declarative dojoType="dijit.form.HorizontalRule" to a dojo:horizontalSlider to provide a ruler to a slider. To be able to combine both successfully you need to understand the order of Javascript calls when the page is built. While loading the page the browser executes any contained scripts. Next the dojo parser starts and converts declarative dojo tags into dojo widgets. Last all functions registered via dojo.addOnLoad are executed. This last step is where DojoFaces tags transform the JSF generated tags into Dojo widgets. Now, to add the HorizontalRule with id="hrule" to the dojo:horizontalSlider with id="hslider" you'd have to wait for both widgets to be generated and put a dojo.addOnLoad script *after* the hslider to perform: 

dijit.byId('#{dojoHelper.clientId['hslider']}').addChild(dijit.byId('hrule'));

Now let's say you want to replace a section of your XHTML page via AJAX. When the AJAX call returns, JSF AJAX implementations will implicitly run any script sections contained within the replaced section. This implies that Dojo widgets that are built programmatically are rebuilt by AJAX. Declarative Dojo widgets are built by the Dojo parser that only runs when the page loads. Thus if you want to replace a Dojo widget by AJAX you need to use the programmatic Dojo style.

DojoFaces tags that submit numbers (dojo:currencyTextBox, dojo:horizontalSlider, dojo:numberSpinner, dojo:numberTextBox, dojo:rating and dojo:verticalSlider) require locale 'en-us' for transport. Add it as an extraLocale to djConfig:

<style type="text/css">
    @import "resources/dojo/dijit/themes/tundra/tundra.css"
    @import "resources/dojo/dojo/resources/dojo.css"
</style>

<script type="text/javascript" src="resources/dojo/dojo/dojo.js"
    djConfig="isDebug: false, parseOnLoad: true, extraLocale: ['en-us']>
</script>

dojo.require is issued by the templates, so you don't need to supply it.

If you are using JSF 2.0, your application uses AJAX to rerender DojoFaces Tags and it is supposed to work on Safari you need to tweak the Content-Type your application works on. Add the phase listener listed below to your faces-config.xml to use the SetContentTypeListener contained within DojoFaces:

<lifecycle>
    <phase-listener>
        org.j4fry.dojo.listener.SetContentTypeListener
    </phase-listener>		
</lifecycle>

DojoFaces features

These are the attributes that are shared among all DojoFaces tags:

  • id: The id must be supplied by the developer and it must be unique within the page. If you use the tag within a template and you want to use the template multiple times within a page you must supply a different name param to each occurence of the template and include #{name} with the tags id (e.g. id="#{name}_myId", this is a required attribute).
  • attr: A list of attributes that is passed through to the dojo widget. Name and value of each attribute are colon separated, attributes are comma separated. If you want to set width and datePattern for a dojo:dateTimeBox, you do attr="style: 'width: 50px', constraints: {datePattern: 'yyyy/dd/mm'}". Just check out the correct dojo syntax in the dojo docs and put it into the attr attribute. To add autoHeight, width and rowSelector to a dojo:dataGrid you do attr="autoHeight: 5, style: 'width: 500px', rowSelector: '20px'". Facelets attributes are inherited by nested Facelets, so attr of a container (tabContainer or titlePane) is inherited by nested tags. To reset attr in a nested tag, do attr="".
  • rendered: true or false (optional, defaults to true)

Here is a comprehensive list of the components supportet by DojoFaces along with the supportet attributes.

These tags are available up to now:

dojo:accordionContainer ^

This tag renders dijit.layout.AccordionContainer backed by a JSF inputHidden that holds the id of the selected fold.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. Refer to the hidden input that holds the containers state with #{dojoHelper.clientId['myIdHidden']} for an accordionContainer with id 'myId'. Nest each fold inside a dijit.layout.AccordionPane with the title attribute set to the folds label. Example:

<div id="myFold1" dojoType="dijit.layout.AccordionPane" title="fold 1"/>
	This is my folds content
</div>
  • value: A value binding for the selected fold.

dojo:button ^

This tag renders dijit.form.Button backed by a JSF commandButton.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax or aj4:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

For a dojo submit button set attr="type: 'submit'". For a button that triggers an AJAX request don't set type: 'submit'. For an example of an AJAX button see dojo:editor.

  • action: an escaped method expression (with \#{} around it) or a constant String
  • button (template param, use <ui:define name="button">): nest your own jsf buttons to support seam, tomahawk or other buttons (defaults to a standard JSF button). If you override the default, the dojo widget gets the same id as your nested jsf button. If you want to access the widget to add event handlers or make modifications you need to add a binding to your button that enables you to access it's id, e.g. binding="#{dojoHelper.binding[id]}".
  • label: a constant or value expression
  • accesskey: pass through attribute for HTML accesskey
  • onclick: a javascript to execute onclick
  • disabled: true or false (defaults to false)

dojo:checkBox ^

This tag renders dijit.form.CheckBox backed by a JSF selectBooleanCheckbox.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myCheck']}') to add event handlers (replace 'myCheck' with the id of your checkBox). To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • value: a value binding for the components value
  • onchange: a javascript to execute onchange
  • onclick: a javascript to execute onclick
  • disabled: true or false (defaults to false)

dojo:checkedMenuItem ^

This tag renders dijit.CheckedMenuItem backed by a JSF selectBooleanCheckbox combined with a JSF commandButton.

Access the dojo widget with dijit.byId(#{dojoHelper.clientId['myItem']}) to add event handlers (replace 'myItem' with the id of your menuItem). To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • action: an escaped method expression (with \#{} around it) or a constant String
  • label: a constant or value expression
  • checked: a value binding for the items 'tick'
  • onclick: a javascript to execute onclick
  • disabled: true or false (defaults to false)

dojo:colorPalette ^

This tag renders dijit.ColorPalette backed by a JSF inputHidden that holds the selected color.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • value: A value binding for the components value (required)
  • onchange: a javascript to execute onchange
  • disabled: true or false (defaults to false)

dojo:comboBox ^

This tag renders dijit.form.ComboBox backed by a JSF inputHidden that holds the store containing the items and a JSF inputText for the selected value.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myCombo']}') to add event handlers (replace 'myCombo' with the id of your comboBox). It is backed by a ItemFileReadStore with the id myCombo_store where you can add, modify or remove items. The store is initialized from a hidden field. If you wish to update the stores items from the server model with AJAX use dijit.byId('#{dojoHelper.clientId['myCombo']}').domNode.nextSibling to access the stores hidden field and dijit.byId('#{dojoHelper.clientId['myCombo']}').domNode.nextSibling.id to access its id. To reinitialize the store from the updated hidden field the tag provides the javascript function #{dojoHelper.jsId['myCombo']}_refreshStore(). To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • value: A value binding for the components value (required)
  • items: a value binding for a list of objects
  • var: referenced by key, designates an item of the list (defaults to 'item'). The value binding expression represented by var is set to each item of the list in turn before key is evaluated to determine the displayed list item. Attribute var is a String without #{}.
  • key: a value binding expression preceeded by a backslash that is applied on each list item to determine the displayed value. Example: \#{item.value}. Interacts with attribute var (optional, defaults to whatever var is set to, default is useful for lists composed of Strings).
  • onchange: a javascript to execute onchange
  • onclick: a javascript to execute onclick
  • onkeyup: a javascript to execute onkeyup
  • disabled: true or false (defaults to false)

dojo:comboButton ^

This tag renders dijit.form.ComboButton backed by a JSF commandButton.

Access the dojo widget with dijit.byId(#{dojoHelper.clientId['myId']}) to add event handlers or make modifications. To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax or aj4:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

Attach the menu 'testMenu' with attr="dropDown: testMenu". For a dojo submit button set attr="type: 'submit'". For a button that triggers an AJAX request don't set type: 'submit' (There's currently a dojo issue with this functionality). Here's an example for a submit button with a menu:

<dojo:comboButton label="test" id="myTest" attr="type: 'submit', dropDown: testMenu" />
<div dojoType="dijit.Menu" id="testMenu">
    ... some dojo menu nested here ...
</div>
  • action: an escaped method expression (with \#{} around it) or a constant String
  • label: a constant or value expression
  • onclick: a javascript to execute onclick
  • disabled: true or false (defaults to false)
  • template param menu: nest a dojo:menu to show when the arrow is clicked

dojo:currencyTextBox ^

This tag renders dijit.form.CurrencyTextBox backed by a JSF inputText. It tag requires extraLocale: ['en-us'] in djConfig for server communication (see installation).

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • value: A value binding for the components value (required).
  • onchange: a javascript to execute onchange
  • onclick: a javascript to execute onclick
  • onkeyup: a javascript to execute onkeyup
  • required: optional, defaults to false
  • disabled: true or false (defaults to false)

dojo:dataGrid ^

This tag renders dojox.grid.DataGrid backed by a JSF inputHidden that holds the store.

As this is a widget from dojox the styles aren't included with dojo.css. Add these styles to the HEAD section of your page (use claro/tundra/nihilo/soria according to your needs):

@import "../../resources/dojo/dojox/grid/resources/Grid.css"
@import "../../resources/dojo/dojox/grid/resources/claroGrid.css"
.dojoxGrid table {
    margin: 0;
}

Grid rendering takes time (approx. 30 ms per grid column). To allow refreshing the grid data quickly without rerendering the entire grid the tag supports exchanging the store: Use an AJAX call to fetch new data from the server and rerender the hidden field that contains the grids data. dojo:dataGrid is backed by dojo:store, the store's id appends '_store' to the grid's id. To determine the HTML id of the hidden field containing the store for a dataGrid named 'myGrid' use #{dojoHelper.clientId['myGrid_store']} in conjunction with AJAX tags that require a HTML id (like JSF 2.0 AJAX). The JSF component id of the hidden fields again appends '_store', so for usage with AJAX tags that require the component id of the hidden field use 'myGrid_store_store'. After updating the store'S hidden field use the grid's #{dojoHelper.jsId['myGrid']}_refreshStore() function to update the grid with the new store content. All functionality defined in dojo:store is available, see there for documentation. dojo:dataGrid passes all tag attributes on to the store, so they aren't documented here again.

For a grid with id 'myGrid' access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to attach events.

  • enhanced: if set to true an dojox.grid.EnhancedGrid is rendered instead of a dojox.grid.DataGrid. Plugins would then be defined with attr="plugins:{nestedSorting:true, ...}" (optional, defaults to false)
  • content: provides backward compatibility for older dataGrid versions, maps directly to dojo:store's structure attribute.
  • layout (template param, use <ui:define name="layout">): Supplies dojo dataGrid's layout param. The layout of a dojo dataGrid is defined as a JSON array with one JSON object per column. Please refer to the dojo documentation for a detailed description of the possible layout parameters. These are some of the possible attributes:
    • field: References a field from the store. The fields are defined in the tags content attribute.
    • name: The column label
    • width: The column width in px, e.g. '100px'
    • styles: CSS styles to be applied to the header as well as for the cells
    • headerStyles: CSS styles for the header
    • cellStyles: CSS styles for the columns
    • editable: true/false, defaults to false
    • type: Changes the display style and the editor of the cells. Can be e.g. dojox.grid.cells.Bool or dojox.grid.cells.Select.
  • query: A filter that reduces the displayed rows. Defaults to #{key}: '*'
  • onStyleRow: Javascript function for row styles based on data. Example:
    function onStyleGridRow(row) {
    var grid = dijit.byId("carGrid");
        var item = grid.getItem(row.index);
        if (item) {
            var name = carGrid_store.getValue(item, "name", null);
            if (name == "Audi") {
                row.customStyles += "color:red;"
            }
        }
        grid.focus.styleRow(row);
        grid.edit.styleRow(row);
    }
  • onRowClick: Javascript function called when grid row is clicked
  • onRowDblClick: Javascript function called when grid row is double clicked

dojo:dateTextBox ^

This tag renders dijit.form.DateTextBox backed by a JSF inputText.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • value: A value binding for the components value (required).
  • timezone: The date that is entered must be interpreted for a timezone: 01/01/2000 00:00 am in Germany is 21/31/1999 05:00 pm in California. The transport happens in ISO Format yyyy-MM-dd. On the server side this is converted into a java.util.Date so a POSIX time must be obtained by converting the ISO Format date string using the timezone argument. Before the java.util.Date is transported back to the client it is converted back from POSIX time to ISO Format and again the timezone argument is used. Timezone is optional and defaults to 'GMT'.
  • onchange: a javascript to execute onchange
  • onclick: a javascript to execute onclick
  • onkeyup: a javascript to execute onkeyup
  • disabled: true or false (defaults to false)

dojo:dialog ^

This tag renders dijit.Dialog programmatically. It is used instead of a declarative dijit.Dialog to nest other DojoFaces tags whereever nested content needs to rendered before the Dialog. dojo:dialog itself doesn't write any values back to the server, so no JSF value connection is provided.

Access the dojo widget 'myId' with dojo.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications.

dojo:dnd ^

This tag defines a dojo.dnd.Source or a dojo.dnd.Target div containing a list of items. dojo:dnd is backed by a dojo:store - see there for the store specific attributes. The store's label will be displayed - if properly escaped you can define an image or a handle in the structure and make it the label (example: label="label" plus structure="{id:'\#{item}', label:'&lt;img src=&quot;${request.contextPath}/resources/images/\#{item}&quot; /&gt;'}"). For dojo:dnd the attr attribute is extremely useful, because it allows you to specify the your dnd.Source's behaviour (like accept, handle or checkAcceptance).

When you drag an item in your browser in drop it in another list, the store structure will be used to create a complete new object. This solution not only allows you to drag around Strings. In the server model entire objects are being moved.

  • type: whether the container is origin or destination of the movements (required, either 'source' or 'target')
  • nodeType: The type of this lists nodes. The source's nodeType can be used in attr="accept:['nodeType']" of the target list.
  • style: CSS style for the parent node
  • styleClass: CSS class for the parent node

dojo:dropDownButton ^

This tag renders dijit.form.DropDownButton. It has a similar function to the declarative form of dijit.form.DropDownButton, but renders the programmatic form, so that dojo:menu can be nested. Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications.

dojo:dropDownSelect ^

This tag renders dijit.form.DropDownSelect backed by a JSF selectOneMenu.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • value: A value binding for the components value (required).
  • map: A value binding for a java.util.Map<String, String> to back the list box. Like h:selectOneMenu the maps keys are displayed and the value of the selected key is submitted. Either this or list are required.
  • list: if map is null this attribute can contain a java.util.List that is transformed to a Map using the attributes var, mapKey and mapValue. Either this or map is required.
  • var: The value binding to contain each item of the list in turn before mapKey and mapValue expressions are applied - a String without #{}.
  • mapKey: A value binding to determine the map key for a given list item that is bound to the var binding. An EL expression with preceeding \ (e.g. \#{item.key})
  • mapValue: A value binding to determine the map value for a given list item that is bound to the var binding. An EL expression with preceeding \ (e.g. \#{item.value})
  • onchange: a javascript to execute onchange
  • onclick: a javascript to execute onclick
  • disabled: true or false (defaults to false)

dojo:editor ^

This tag renders dijit.Editor backed by a JSF inputHidden that holds the text.

Access a dojo editor with id 'myEditor' by using dijit.byId('#{dojoHelper.clientId['myEditor']}') to add event handlers or make modifications. The dojo widget is backed by a JSF hiddenInput to supply server communication. The tag supports javascript functions #{dojoHelper.jsId['myEditor']}_save() to write the current editor's content to the hidden field and #{dojoHelper.jsId['myEditor']}_refresh() to refresh the editor with the hidden field's current content (replace 'myEditor with the id of your editor). A button that saves the editor's content with AJAX and displays the result in 'myAJAXUpdatedComponent' could look like this:

<dojo:button label="save" id="save_editor" onclick="#{dojoHelper.jsId['myEditor']}_save()" attr="">
	<f:ajax execute="myEditor" render="myAJAXUpdatedComponent"/>
</dojo:button>

The JSF hidden field can be addressed with dojoHelper.clientId['myEditorHidden']. Use this expression to update the hidden field by AJAX and call #{dojoHelper.jsId['myEditor']}_refresh() afterwards to push the new content into the editor.

  • value: A value binding for the components value (required).

dojo:filteringSelect ^

This tag renders dijit.form.FilteringSelect backed by a JSF selectOneMenu.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • value: A value binding for the components value (required).
  • map: A value binding for a java.util.Map<String, String> to back the list box. Like h:selectOneMenu the maps keys are displayed and the value of the selected key is submitted. Either this or list are required.
  • list: if map is null this attribute can contain a java.util.List that is transformed to a Map using the attributes var, mapKey and mapValue. Either this or map is required.
  • var: The value binding to contain each item of the list in turn before mapKey and mapValue expressions are applied - a String without #{}.
  • mapKey: A value binding to determine the map key for a given list item that is bound to the var binding. An EL expression with preceeding \ (e.g. \#{item.key})
  • mapValue: A value binding to determine the map value for a given list item that is bound to the var binding. An EL expression with preceeding \ (e.g. \#{item.value})
  • readOnly: true/false - if true the input field of the FilteringSelect cannot be edited but the list can still pop up thus making a normal select box with dojo styles out of it. Defaults to false.
  • onchange: a javascript to execute onchange
  • onclick: a javascript to execute onclick
  • onkeyup: a javascript to execute onkeyup
  • disabled: true or false (defaults to false)

dojo:horizontalSlider ^

This tag renders dijit.form.HorizontalSlider backed by a JSF inputText. It requires extraLocale: ['en-us'] in djConfig for server communication (see installation).

Access the dojo widget with id dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. Rules may be added with added with addChild in a dojo.addOnLoad block. To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • value: A value binding for the components value (required).
  • onchange: a javascript to execute onchange
  • onclick: a javascript to execute onclick
  • required: optional, defaults to false
  • disabled: true or false (defaults to false)

dojo:form ^

This tag renders dijit.form.Form backed by a JSF form.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. Nest form content as you would do with h:form.

dojo:gridEvent ^

This tag is an extension for dojo:dataGrid to enable form and AJAX submits based on grid cell clicks

  • action: an escaped method expression (with \#{} around it) or a constant String denoting an action that is invoked on the server when the event was triggered, optional, defaults to none.
  • key: A value binding that is filled with the id of the clicked row when the event was triggered, optional, defaults to none.
  • value: A value binding that is filled with the item of the clicked row when the event was triggered, optional, defaults to none.
  • for: The id of the associated grid, required.
  • event: The grid cell event that triggers the action - any of the onCell* events defined in the dojo API, optional, defaults to onCellClick.
  • field: the field as specified in the grid layout that triggers the event, required.

dojo:gridSort ^

This tag is an extension for dojo:dataGrid to enable server side sorting on grid header clicks. The properties sort and asc are read, when rendering the grid. They are used to set the grid's sorting arrows and are written when a grid header is clicked.

  • action: an escaped method expression (with \#{} around it) or a constant String denoting an action that is invoked on the server when sorting was triggered, optional, defaults to none.
  • for: The id of the associated grid, required.
  • sort: a value binding refering the sorted column by it's field property in the grid layout, required.
  • asc: a value binding refering the sort direction of the sorted column, required.

dojo:inlineEditBox ^

This tag renders dijit.InlineEditBox backed by a JSF inputHidden that holds the text.

Access a dojo inlineEditBox with id 'myEditBox' by using dijit.byId('dojoHelper.clientId['myEditBox']') to add event handlers or make modifications. The dojo widget is backed by a JSF hiddenInput to supply server communication. The tag supports javascript functions #{dojoHelper.jsId['myEditBox']}_save() to write the current inlineEditBox content to the hidden field and #{dojoHelper.jsId['myEditBox']}_refresh() to refresh the inlineEditBox with the hidden field's current content (replace 'myEditBox' with the id of your inlineEditBox). A button that saves the inlineEditBox's content with AJAX and displays the result in 'myAJAXUpdatedComponent' could look like this:

<dojo:button label="save" id="save_editBox" onclick="#{dojoHelper.jsId['myEditBox']}_save()" attr="">
	<f:ajax execute="myEditBox" render="myAJAXUpdatedComponent"/>
</dojo:button>

The JSF hidden field can be addressed with dojo.byId('#{dojoHelper.clientId['myEditBoxHidden']}'). Use this expression to update the hidden field by AJAX and call #{dojoHelper.jsId['myEditBox']}_refresh() afterwards to push the new content into the editor.

  • value: A value binding for the components value (required).

dojo:menu ^

This tag renders dijit.Menu. It has a similar function to the declarative form of dijit.Menu, but renders the programmatic form, so that dojo:menuItem and dojo:checkedMenuItem can be nested.

Access the dojo widget with dijit.byId(#{dojoHelper.clientId['myMenu']}) to add event handlers.

dojo:menuBar ^

This tag renders dijit.MenuBar. It has a similar function to the declarative form of dijit.MenuBar, but renders the programmatic form, so that dojo:popupMenuBarItem can be nested. Access the dijit widget with dijit.byId('#{dojoHelper.clientId[id]}') to add evetn handlers.

dojo:menuItem ^

This tag renders dijit.MenuItem backed by a JSF commandButton.

Access the dojo widget with dijit.byId(#{dojoHelper.clientId['myItem']}) to add event handlers (replace 'myItem' with the id of your menuItem). To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • action: an escaped method expression (with \#{} around it) or a constant String
  • label: a constant or value expression
  • onclick: a javascript to execute onclick
  • disabled: true or false (defaults to false)

dojo:move ^

This tag renders a dojo.dnd.Moveable, a dojo.dnd.TimedMoveable, a dojo.dnd.move.parentConstrainedMoveable, or a dojo.dnd.move.boxConstrainedMoveable depending on the constraint attribute. The moveable DOM node is a SPAN with absolute positioning, two hidden inputs connect it's top and left attributes to JSF EL expressions.

Access the widget with #{dojoHelper.jsId['myId']} to add event handlers like 'onMoveStop' via dojo.connect. The widget gives you access to it'S DOM node via it's #{dojoHelper.jsId['myId']}.node property.

  • constraint: "timed" | "parent" | "box" | ""
  • top: a constant or value expression
  • left: a constant or value expression

dojo:multiSelect ^

This tag renders dijit.form.MultiSelect backed by a JSF selectManyMenu.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • value: A value binding for the java.util.List of selected keys (Strings).
  • map: A value binding for a java.util.Map<String, String> to back the list box. Like h:selectOneMenu the maps keys are displayed and the value of the selected key is submitted. Either this or list are required.
  • list: if map is null this attribute can contain a java.util.List that is transformed to a Map using the attributes var, mapKey and mapValue. Either this or map is required.
  • var: The value binding to contain each item of the list in turn before mapKey and mapValue expressions are applied - a String without #{}.
  • mapKey: A value binding to determine the map key for a given list item that is bound to the var binding. An EL expression with preceeding \ (e.g. \#{item.key})
  • mapValue: A value binding to determine the map value for a given list item that is bound to the var binding. An EL expression with preceeding \ (e.g. \#{item.value})
  • onchange: a javascript to execute onchange
  • onclick: a javascript to execute onclick
  • disabled: true or false (defaults to false)

dojo:numberSpinner ^

This tag renders dijit.form.NumberSpinner backed by a JSF inputText. It requires extraLocale: ['en-us'] in djConfig for server communication (see installation).

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • value: A value binding for the components value (required).
  • onchange: a javascript to execute onchange
  • onclick: a javascript to execute onclick
  • onkeyup: a javascript to execute onkeyup
  • required: optional, defaults to false
  • disabled: true or false (defaults to false)

dojo:numberTextBox ^

This tag renders dijit.form.NumberTextBox backed by a JSF inputText. It tag requires extraLocale: ['en-us'] in djConfig for server communication (see installation).

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • value: A value binding for the components value (required).
  • pattern: The number pattern as used in java.text.DecimalFormat (optional, defaults to #,##0.00)
  • onchange: a javascript to execute onchange
  • onclick: a javascript to execute onclick
  • onkeyup: a javascript to execute onkeyup
  • disabled: true or false (optional, defaults to false)

dojo:popupMenuBarItem ^

This tag renders dijit.PopupMenuBarItem. It has a similar function to the declarative form of dijit.PopupMenuBarItem, but renders the programmatic form, so that dojo:menu can be nested.

Access the dojo widget with dijit.byId(#{dojoHelper.clientId['myItem']}) to add event handlers.

dojo:radioButton ^

This tag renders dijit.form.RadioButton. Multiple instances of this tags form a radio group. Define the radio group with tag dojo:radioGroup prior to (within the XHTML page before) adding radio buttons to the group.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. Add AJAX or other nested tags to dojo:radioGroup that establishes the JSF connection.

  • value: The value that the corresponding dojo:radioGroup is set to if this radio button is selected (required).
  • group: The id of the dojo:radioGroup this radio button belongs to (required).
  • disabled: true or false (optional, defaults to false)

dojo:radioGroup ^

Defines a radio group that instances of dojo:radioButton can be added to. Don't nest the radio buttons inside the group, define the group prior to the buttons in your XHTML page.

This tag renders no dojo widget, it's the JSF link for a group of radio buttons. To trigger AJAX from the adjoined radio buttons nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0 inside this tag. As radioGroup has no dojo widget no attr attribute can be passed anywhere, so the general attribute attr does not exist here.

  • value: A value binding for the radio groups value.
  • onchange: a javascript to execute onchange of the Radio Buttons
  • onclick: a javascript to execute onclick of a Radio Button
  • disabled: true or false (optional, defaults to false)

dojo:rating ^

This tag renders dojox.form.Rating backed by a JSF inputText. It requires extraLocale: ['en-us'] in djConfig for server communication (see installation).

As this is a widget from dojox the styles aren't included with dojo.css. Add the styles to the HEAD section of your page:

@import "../../resources/dojo/dojox/form/resources/Rating.css"

Access the dojo widget with id dijit.byId('#{dojoHelper.clientId[id]}') to add event handlers or make modifications. To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • value: A value binding for the components value (required).
  • onchange: a javascript to execute onchange
  • onclick: a javascript to execute onclick
  • required: optional, defaults to false
  • disabled: true or false (defaults to false)

dojo:simpleTextarea ^

This tag renders dijit.form.SimpleTextarea backed by a JSF inputTextarea.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • value: A value binding for the components value (required).
  • onchange: a javascript to execute onchange
  • onclick: a javascript to execute onclick
  • onkeyup: a javascript to execute onkeyup
  • disabled: true or false (defaults to false)

dojo:store ^

This tag renders a dojo.data.ItemFileWriteStore and fills it with a list of objects from the server model. Supports writing changes back to the model, JSF converters and validators, tree structures and numeric and date properties.

Reference the store from declarative or programmatic Dojo tags via #{dojoHelper.jsId['myStore']} where myStore is the store's id. To connect events to the store (onSet, onDelete, ...) or to modify the content (addItem, ...) the store is globally accessible in Javascript with #{dojoHelper.jsId['myStore']}. The store is initialized from a hidden field, updates to the store reside in a second hidden field. If you wish to update the stores items from the server model with AJAX you can access the HTML id of hidden update field with #{dojoHelper.clientId['myStore_update']} (for a store with id="myStore") to send updates to the server. Get new store content into the second hidden field #{dojoHelper.clientId['myStore']} that contains the store data. The store exposes the Javascript method #{dojoHelper.jsId['myStore']}_createStore() to initialize the store from the hidden field after AJAX requests and #{dojoHelper.jsId['myStore']}_flushUpdates() to flush the hidden updates field after it has been pushed to the server (all this with id="myStore").

  • items: a value binding for a list of objects. (required)
  • structure: JSON String defining JSF connectors (value binding, converter and validators) on each column of the store. The children property indicates an entry point to descend into a tree structure. If children=true is set on a column the referenced model attribute must contain either a java.util.List or null. The numeric property indicates that a numeric model attribute should be exposed as a number object in Javascript to enable dojox.charting to interprete the value. If numeric=true is set on a column the referenced model attribute must contain either a java.lang.Number and the type of the resulting Javascript object will be 'number'. A unique key column is required for the store. A default structure is supplies that works for simple String lists. (optional, defaults to {id:'\#{item}'})
    Structure syntax is given in BNF (constant expressions bolt, so [] defines a JSON Array, but [] is an optional BNF expression, // separates comments):

    structure :: {columnDefinition [, columnDefinition]*}
    columnDefinition :: simpleColumnDefinition || complexColumnDefinition
    simpleColumnDefinition :: columnName: valueBinding
    complexColumnDefinition :: columnName: {el: valueBinding [, converterDefinition] [, validatorDefinitions] [, children=true] [, numeric=true]}
    columnName :: String //equals the field attribute of param layout
    valueBinding :: '\#{String}' || &quot;\#{String}&quot; //a JSF EL expression - the second form allows single qoutes inside el
    converterDefinition :: converter: converterExpression
    converterExpression :: simpleConverterExpression || complexConverterExpression
    simpleConverterExpression :: 'converterId' //Id of JSF Standard Converter Implementation or custom converter
    complexConverterExpression :: {id: simpleConverterExpression [,param]*} //params lang and country are passed to converter.setLocale(new Locale(lang, country)), param timeZone is passed to converter.setTimeZone(TimeZone.getInstance(timeZone))
    validatorDefinitions :: validators: validatorExpression
    validatorExpression :: singleValidatorExpression || multipleValidatorExpression
    singleValidatorExpression :: simpleValidatorExpression || complexValidatorDefinition
    simpleValidatorExpression :: 'validatorId' //Id of Standard Validator Implementation or custom validator
    complexValidatorDefinition :: {id: simpleValidatorExpression [,param]*}
    multipleValidatorDefinition :: [singleValidatorExpression [, singleValidatorExpression]*]
    param :: paramName: paramValue paramName :: String //JavaBean property name paramValue :: stringParam || numberParam || booleanParam
    stringParam :: 'String'
    numberParam :: String //parseable as a Number
    booleanParam :: true || false

    example: 
    
structure="{
	a: {el: '\#{x}',
		converter: {id: 'javax.faces.Number', pattern: '#,##0.00'},
		validators: [{id: 'javax.faces.Required'},
					 {id:'javax.faces.DoubleRange', minimum:0, maximum:100}]}
	b: {el: '\#{y}',
		converter: {id: 'javax.faces.DateTime', pattern: 'MM/dd/yy'}}
}"
  • var: referenced by structure, designates an item of the list. The value binding expression represented by var is set to each item of the list in turn before structure is evaluated to determine the displayed list item. Attribute var is a string without #{}. (optional, defaults to 'item')
  • key: The name of the unique key column of the store. Must be one of the fields defined in structure. (optional, defaults to 'id')
  • label: The name of label column of the store. Must be one of the fields defined in structure. (optional, defaults to whatever is defined by key)
  • modelClass: The java classname of objects to be inserted. If this option is set new rows will automatically be added to the list (optional, defaults to the first element of items).
  • onInsert: A method binding (without #{} around it) that defines a callback that is called when the form is submitted once for each row that was added to the grid. The callback method must have a org.j4fry.json.JSONObject parameter and when it is triggered it will receive all the attributes of the new row in a HashMap within this parameter. If modelClass is set this method can be used for validation (throw an Exception for invalid rows). If modelClass is not set you can put your own list insert code here (optional, no default).
  • autoUpdate: true/false, if set to true, updates will automatically passed to the model (optional, defaults to true).
  • onUpdate: A method binding (without #{} around it) that defines a callback that is called when the form is submitted once for each row that was updated. The callback method must have a java.lang.Object and a org.j4fry.json.JSONObject parameter and when it is triggered it will receive the old list item as well as all the updated attributes in the JSONObject. If autoUpdate is not set (or set to true) this method can be used for validation (throw an Exception for invalid rows). If autoUpdate is set to false you can put your own update code here (optional, no default).
  • autoDelete: true/false, if set to true, deletes will automatically passed to the model (optional, defaults to true).
  • onDelete: A method binding (without #{} around it) that defines a callback that is called when the form is submitted once for each row that was deleted from the grid. The callback method must have a java.lang.Object parameter and when it is triggered it will receive the deleted row within this parameter. If autoDelete is not set (or set to true) this method can be used for validation (throw an Exception for invalid deletes). If autoDelete is set to false you can put your own list item remove code here (optional, no default).

dojo:tabContainer ^

This tag renders dijit.layout.TabContainer backed by a JSF inputHidden that holds the selected tab.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myTabContainer']}') to add event handlers or make modifications. Refer to the hidden input that holds the containers state with #{dojoHelper.clientId['myTabContainerHidden']} for an accordionContainer with id 'myTabContainer'. Nest tab content as you would do with h:panelGroup. Nest each tab inside a dijit.layout.ContentPane with the title attribute set to the tabs label. Example:

<div id="myTab1" dojoType="dijit.layout.ContentPane" title="tab 1"/>
	This is my tabs content
</div>
  • value: A value binding for the selected tab.

dojo:textarea ^

This tag renders dijit.form.Textarea backed by a JSF inputTextarea.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • value: A value binding for the components value (required).
  • onchange: a javascript to execute onchange
  • onclick: a javascript to execute onclick
  • onkeyup: a javascript to execute onkeyup
  • disabled: true or false (defaults to false)

dojo:textBox ^

This tag renders dijit.form.TextBox backed by a JSF inputText.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • value: A value binding for the components value (required).
  • onchange: a javascript to execute onchange
  • onclick: a javascript to execute onclick
  • onkeyup: a javascript to execute onkeyup
  • disabled: true or false (defaults to false)

dojo:timeTextBox ^

This tag renders dijit.form.TimeTextBox backed by a JSF inputText.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • value: A value binding for the components value (required).
  • timezone: The time that is entered must be interpreted for a timezone: 00:00 am in Germany is 05:00 pm in California. The transport happens in a dojo specific format ('T'HH:mm:ss). On the server side this is converted into a java.util.Date so a POSIX time must be obtained by converting the ISO Format date string using the timezone argument. Before the java.util.Date is transported back to the client it is converted back from POSIX time to ISO Format and again the timezone argument is used. Timezone is optional and defaults to 'GMT'.
  • timezone: The timezone that is used to convert the java.util.Date on the server side to a date string that is passed to dojo and to convert the date String that passed from dojo to a java.util.Date on the server side (optional, defaults to 'GMT').
  • onchange: a javascript to execute onchange
  • onclick: a javascript to execute onclick
  • onkeyup: a javascript to execute onkeyup
  • disabled: true or false (defaults to false)

dojo:titlePane ^

This tag renders dijit.TitlePane backed by a JSF inputHidden that holds the toggle state.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. Nest pane content as you would do with h:panelGroup.

This tag attaches to the onShow/onHide events of the dijit widget. TitlePanes in dojo versions prior to 1.4 didn't emit onShow. DojoFaces versions 1.2_00 and before fixed the bug of the dojo TitlePane for dojo < 1.4. DojoFaces 1.2_01 and higher rely on the fixed behaviour in dojo >= 1.4.

  • state: 'OPEN' or 'CLOSE', must be a value binding, will be written back to the server model. (required, use dijit.TitlePane if you require no server model connectivity)

dojo:toggleButton ^

This tag renders dijit.form.ToggleButton backed by a JSF selectBooleanCheckBox and a JSF commendButton.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myToggle']}') to add event handlers (replace 'myToggle' with the id of your toggle button). To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • action: an escaped method expression (with \#{} around it) or a constant String
  • label: a constant or value expression
  • checked: a value binding for the items 'tick'
  • onchange: a javascript to execute onchange
  • onclick: a javascript to execute onclick
  • disabled: true or false (defaults to false)

dojo:tree ^

This tag renders a dijit.Tree based on nested java.util.Lists. Tree DnD can be enabled by setting attr="dndController: 'dijit._tree.dndSource'", changes will be written back to the java model.

Read and write the Cookie 'myIdSaveStateCookie' (replace myId with the id of your tree) to determine and set the toggle state of your tree. The Cookie contains a %2C separated list of node ids that are toggled open, all others are toggled close.

Access the dojo widget with dijit.byId('myId') to add event handlers or make modifications.

  • items: The root list of the tree
  • var: The value binding to contain each node in turn - a String without #{}
  • nodeId: A value binding expression preceeded by \ (e.g. \#{item.id}) designating the nodes id
  • nodeValue: A value binding expression preceeded by \ (e.g. \#{item.value}) designating the nodes display value
  • nodeChildren: A value binding expression preceeded by \ (e.g. \#{item.children}) designating the nodes children

dojo:validationTextBox ^

This tag renders dijit.form.ValidationTextBox backed by a JSF inputText.

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • value: A value binding for the components value (required).
  • onchange: a javascript to execute onchange
  • onclick: a javascript to execute onclick
  • onkeyup: a javascript to execute onkeyup
  • disabled: true or false (defaults to false)

dojo:verticalSlider ^

This tag renders dijit.form.VerticalSlider backed by a JSF inputText. It requires extraLocale: ['en-us'] in djConfig for server communication (see installation).

Access the dojo widget with dijit.byId('#{dojoHelper.clientId['myId']}') to add event handlers or make modifications. Rules may be added with added with addChild in a dojo.addOnLoad block. To trigger AJAX from this tag nest standard compatible Ajax tags like fry:ajax for jsf 1.1/1.2 and f:ajax for jsf 2.0.

  • value: A value binding for the components value (required).
  • onchange: a javascript to execute onchange
  • onclick: a javascript to execute onclick
  • required: optional, defaults to false
  • disabled: true or false (defaults to false)
Print