Page History

Warning

title	Dojo plugin is deprecated

The Dojo plugin will be deprecated on Struts 2.1

Note

title	Struts 2.0 versus Struts 2.1 and the Dojo tags

The easiest way to get documentation for Struts 2.0 Dojo tag usage is to look at older Struts 2 documentation, like the Struts 2.0.11 Ajax tags wiki documentation.

Please check that documentation and the Dojo tag examples in the showcase app of the appropriate Struts 2 version before asking questions on the struts-user mailing list!

THE WIKI IS NOT VERSIONABLE (in a practical way).

The documentation here is for the most current Struts 2, not necessarily the most current release. We try to add version-specific documentation notes but have undoubtedly missed some locations.

Description

To use the AJAX tags from 2.1 on you must:

Include the Dojo Plugin distributed with Struts 2 in your /WEB-INF/lib folder.
Add <%@ taglib prefix="sx" uri="/struts-dojo-tags" %> to your page.
Include the head tag on the page, which can be configured for performance or debugging purposes.

Handling AJAX Responses

The following attributes affect the handling of all ajax responses.

Attribute	Default Value	Description
parseContent	true	When true, Dojo will parse the response into an XHTML Document Object and traverse the nodes searching for Dojo Widget markup. The parse and traversal is performed prior to inserting the nodes into the DOM. This attribute must be enabled to nest Dojo widgets (dojo tags) within responses. There's significant processing involved to create and parse the document so switch this feature off when not required. Note also that the response must be valid XHTML for cross-browser support and widgets must have unique IDs.
separateScripts	true	When true, Dojo will extract the <script> tags from the response, concatenate the extracted code into one block, create a new Function whose body is the extracted code and immediately invoke the function. The invocation is performed after the DOM has been updated with the XHTML. The function is executed within the scope of the widget (that is, the this variable points to the widget instance). When false, Dojo will extract the <script> tags from the response, concatenate the extracted code into one block and: in IE: invoke window.execScript() on the code in other browsers: create a <script> node containing the code and insert that node into the DOM This invocation occurs after the DOM has been updated with the XHTML. Note that scripts may not be executed if it is not valid to create a <script> node in the DOM at the destination.
executeScripts	false	When true, Dojo will extract code from the <script> tags from the response and execute it based on the separateScripts value. When false, the XHTML response is inserted into the DOM and <script> nodes are ignored.

Note
It's possible that the updated DOM will not include <script> nodes even though the inline code has been executed.

Tip
Ensure the response is XHTML-compliant (including, for example, thead and tbody tags in tables). If you intend to run inline javascript: Ensure the javascript can be concatenated and executed in one block, set executeScripts=true, *set separateScripts=true (the reliable option)

Topics

Most of the AJAX tags use Dojo topics for event notification and communication between them, to learn about topics visit Dojo's documentation

Examples

Examples can be found on the documentation for each tag in the UI Tag Reference page, for additional examples see Ajax and JavaScript Recipes and the Showcase application distributed with Struts 2.

Tags

Code Block



A submit button can be used to submit a form, even if it is outside the form, using "formId" and "formFilter" and "href". Note that in this case "href" is required.

{code:HTML}
<s:form id="form1">
  <input type="textbox" name="data">	
</s:form>

<s:url id="ajaxTest" value="/AjaxTest.action" />

<s:submit type="submit" theme="ajax" href="%{ajaxTest}" formId="form1"/>

See the Div tag for examples on how to use "handler", "beforeLoading", "afterLoading", "loadingText" and "errorText"

Attribute	Description	Type
targets	Comma delimited list of ids of the elements whose content will be updated	String
handler	Javascript function name that will make the request	String
formId	Form id whose fields will be serialized and passed as parameters	String
formFilter	Function name used to filter the fields of the form	String
loadingText	The text to display in the "targets" while content is loaded	String
errorText	The text to display in the "targets" when there is an error	String
refreshListenTopic	Topic name that will cause the "targets" content to be reloaded	String
executeScripts	Any Javascript code in the loaded content will be executed	Boolean
src	Supply an image src for "image" type submit button. Will have no effect for types "input" and "button"	String

Anchor

The anchor tag, like the submit tag, can be used to update the content of its "targets" attribute with text returned from the asynchronous request. "targets" is a comma-delimited list of element ids.

This anchor will update the content of div1 and div2 with text returned form "/AjaxTest.action"

...


<div id="div1">Div 1</div>
<div id="div2">Div 2</div>

<s:url id="ajaxTest" value="/AjaxTest.action" />

<s:a theme="ajax" href="%{ajaxTest}" targets="dev1,dev2">Update divs</s:a>

See the Div tag for examples on how to use "handler", "beforeLoading", "afterLoading", "loadingText" and "errorText"

Attribute	Description	Type
targets	Comma delimited list of ids of the elements whose content will be updated	String
handler	Javascript function name that will make the request	String
formId	Form id whose fields will be serialized and passed as parameters	String
formFilter	Function name used to filter the fields of the form	String
loadingText	The text to display in the "targets" while content is loaded	String
errorText	The text to display in the "targets" when there is an error	String
refreshListenTopic	Topic name that will cause the "targets" content to be reloaded	String
executeScripts	Any Javascript code in the loaded content will be executed	Boolean

Tabbed Panel

The tabbedPanel tag can host static and dynamic(asynchronously loaded) tabs. Every div tag inside the tabbedPanel will be rendered as a tab. The "label" attribute is required for each tab, and will be used as caption. For more details on the dynamic tabs, see the "div" tag section. The tabbedPanel tag is in the "simple" theme bacause it does not contains any ajax functionality itself.

Note

title	Themes

Do not set the "theme" attribute to "ajax" for tabbedPanel.
Remember to set the "theme" attribute to "ajax", and provide a valid "href" attribute for each dynamic tab (div).

This tabbedPanel has one static, and one dynamic tab:

...


<s:url id="ajaxTest" value="/AjaxTest.action" />

<s:tabbedPanel>
    <s:div label="static">
        This is an static content tab.
    </s:div>
    <s:div href="%{ajaxTest}" theme="ajax" label="dynamic">
        This is a dynamic content tab. 
        The content of this div will be replaced with the text returned from "/AjaxTest.action"
    </s:div>
</s:tabbedPanel>

Use the "labelposition" attribute to specify the side where the tab labels must be placed, possible values are "top" (default), "right", "bottom" and "left". Tabs can have a "close button" which will remove the tab from its tabbedPanel parent. The "close button" is hidden by default, to make it visible set the "closeButton" attribute to either "panel" (it will be placed on the tabbedPanel), or "tab" (it will be placed on each tab). By default the first tab will be selected, using the "selectedTab" attribute, you can specify the id of the tab to be selected when the page loads.

This tabbedPanel will place the tab labels on the left, with a "close" button on each tab, and will select the "dynamic" tab by default:

...


<s:url id="ajaxTest" value="/AjaxTest.action" />

<s:tabbedPanel labelposition="left" closeButton="tab" selectedTab="dynamic">
    <s:div label="static" id="static">
        This is an static content tab.
    </s:div>
    <s:div href="%{ajaxTest}" theme="ajax" label="dynamic" id="dynamic">
        This is a dynamic content tab. 
        The content of this div will be replaced with the text returned from "/AjaxTest.action"
    </s:div>
</s:tabbedPanel>

TabbedPanel's height will be by default the same as the currently selected tab, use the "doLayout" attribute to force a fixed height.

This tabbedPanel's height is 300 px:

...


<s:url id="ajaxTest" value="/AjaxTest.action" />

<s:tabbedPanel id="test2" theme="simple" cssStyle="height: 300px;" doLayout="true">
  <s:div id="left" label="left">
      This is the left pane<br/>
      <s:form >
          <s:textfield name="tt" label="Test Text" /> 
          <br/>
          <s:textfield name="tt2" label="Test Text2" />
      </s:form>
  </s:div>
  <s:div theme="ajax"  href="%{ajaxTest}" id="ryh1" label="remote one" />
</s:tabbedPanel>

Attribute	Description	Type
closeButton	Where the close button will be placed, possible values are "tab" and "pane"	String
selectedTab	The id of the tab that will be selected by default	String
doLayout	If doLayout is false (default), the tabbedPanel's height is the height of the currently selected tab	Boolean
labelposition	Where to place the tabs, possible vales are "top" (default), "right", "bottom" and "left"	String

Autocompleter

The autocompleter tag loads its options asynchronously when the page loads, and suggests options based on the text entered in the textbox. If the attribute "autoComplete" is set to "true" (defaults to false), the autocompleter will make suggestions in the textbox, as the user types. The autocompleter will always display a dropdown with the options that have at least a partial match with the text entered in the textbox. If the user clicks on the dropdown button, all the options will be shown in the dropdown. To force the value to be a valid option set the attribute "forceValidOption" to "true" ("false" by default).

Note

title	Autocompleter input format

Wiki Markup

    The text to be returned from your action must be a list in [JSON|http://json.org/] (Javascript Object Notation).
    Make sure your action returning the JSON list is not decorated adding any extra content.
    Like:
    [
        \["Display Text1", "Value1"\],
        \["Display Text2", "Value2"\]
    ]

//TODO: add example here on how to use JSON Result Type

This is a simple autocompleter without textbox autocomplete:

...


<s:url id="json" value="/JSONList.action" />

<s:autocompleter theme="ajax" href="%{json}" autoComplete="false"/>

This tag can be used in the "simple" theme, without ajax functionality. When using this tag in the "simple" theme, the option to be selected by default can be specified using the "value" attribute. Use the "list" attribute to specify the available options:

...


<s:autocompleter theme="simple" list="{'apple','banana','grape','pear'}" value="grape"/>

By default the dropdown's height is 120 px, if the list contains just a few items and is smaller than 120 px, the dropdown's height will be adjusted to the size of the list. To change the default value for the dropdown's height use the "dropdownHeight" attribute.

This autocompleter dropdown's height is 180 px:

...


<s:url id="json" value="/JSONList.action" />

<s:autocompleter theme="ajax" href="%{json}" dropdownHeight="180"/>

When the topic specified in the "refreshListenTopic" attribute is published, the options in the autocompleter will be reloaded. If the "onValueChangedPublishTopic" attribute is given a value, every time the selected value changes, a topic with that name will be published. This two attributes can be use to link two autocompleters. The "formId" and "formFilter" attributes (see Div tag for examples) can be used to submit a form, when the request is made.

When the selected value in "Autocompleter 1" changes, the "/Refresh" is published, forcing "Autocompleter 2", to reloads its options, submitting the form "selectForm":

...


<s:url id="json" value="/JSONList.action" />

<form id="selectForm">
  Autocompleter 1 <s:autocompleter theme="simple" name="select" list="{'fruits','colors'}"  onValueChangedPublishTopic="/Refresh" />
</form>
  Autocompleter 2 <s:autocompleter theme="ajax" href="%{json}" formId="selectForm" refreshListenTopic="/Refresh"/>

...

Attribute

...

Description

...

Type

...

autoComplete

...

Whether to make suggestions on the textbox (suggestions in the dropdown will still be done)

...

Boolean

...

forceValidOption

...

The text entered has to match an option, otherwise the value will be cleared when autocompleter loses focus

...

Boolean

...

delay

...

Time to wait before making the search (in milliseconds)

...

Integer

...

searchType

...

How to match entered text agains the available options, "startstring" (default), "startword" and "substring"

...

String

...

dropdownHeight

...

The height of the dropdown (in pixels), by default 120

...

Integer

...

dropdownWidth

...

The width of the dropdown (in pixels), by default same as autocompleter's width

...

Integer

...

formId

...

Form id whose fields will be serialized and passed as parameters

...

String

...

formFilter

...

Function name used to filter the fields of the form

...

String

...

refreshListenTopic

...

Topic name that will cause the options to be reloaded

...

String

...

onValueChangedPublishTopic

...

Topic name to be published when the value changes

...

String

...

value

...

Default value when "theme" is "simple"

...

String

...

list

...

Iteratable source to populate options

...

Child pages

Versions Compared

Old Version 15

New Version Current

Key

Description

Handling AJAX Responses

Topics

Examples

Tags

Anchor

Tabbed Panel

Autocompleter