THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
| Warning | ||
|---|---|---|
| ||
The Dojo plugin will be deprecated on Struts 2.1 |
...
| Note | ||
|---|---|---|
| ||
To use these ajax tags you need to set the "theme" attribute to "ajax". |
Common Attributes
These attributes are common to all the ajax tags:
Attribute | Description | Type |
|---|---|---|
href | url used to make the request | String |
beforeLoading | Javascript code which will be executed before the request is made | String |
afterLoading | Javascript code which will be executed after the request is made | String |
Div
The div tag is a content area that can load its content asynchronously. The div tag can be forced to reload its content using a topic. To defined the topic that will trigger the refresh of the panel, use the "refreshListenTopic" attribute.
This div will refresh every time the topic "/refresh" is published:
...
<s:div theme="ajax" href="/AjaxTest.action" refreshListenTopic="/refresh"/>
To publish this topic use this in your Javascript code:
...
dojo.event.topic.publish("/refresh");
The div tag can be configured to update its content periodically, using a timer. Use the "updateInterval" attribute to set the interval for the mentioned timer; this value is expressed in milliseconds. If "autoStart" is set to true, "delay" can be used to force the timer to wait for the "delay"(in milliseconds also) period before starting.
This div will refresh periodically every 2 seconds, starting 3 seconds after the page is loaded:
...
<s:div theme="ajax" href="/AjaxTest.action" updateInterval="2000" delay="3000"/>
There is an "autoStart" attribute that controls whether the timer will be started when the page is loaded, its value is "true" by default. The timer can be started and stopped using topics using "startTimerListenTopic" and "stopTimerListenTopic".
This div will not start the timer by default and will listen to the start/stop topics to control the timer:
...
<s:div theme="ajax" href="/AjaxTest.action" startTimerListenTopic="/startTimer" stopTimerListenTopic="/stopTimer" updateInterval="3000" autoStart="false"/>
The div panel shows "Loading..." by default when the request is in process. To customize this text, use the "loadingText" attribute. If an error of any sort occurs, the error will be shown in the div area, to customize the error message, use the "errorText" attribute.
This div uses custom error/loading messages:
...
<s:div href="/AjaxTest.action" theme="ajax" errorText="There was an error" loadingText="reloading" updateInterval="5000"/>
If the loaded text contains Javascript code sections, these sections will be executed if the "executeScripts" attribute is set to true.
If parameters need to be passed to the url, the "formId" attribute can be used to specify a form whose fields will be serialized and passed on the request as parameters. The attribute "formFilter" can bet set to the name of a Javascript function that will be used to filter the fields of "formId". The "formFilter" function will be called for each field, passing the field as a parameter, and must return true if the field is to be included, or false otherwise.
This div will submit the field "firstName", of the form "userData" and ignore other fields:
...
<script type="text/javascript">
function filter(field) {
return field.name == "firstName";
}
</script>
<form id="userData">
<label for="firstName">First Name</label>
<input type="textbox" id="firstName" name="firstName">
<label for="lastName">Last Name</label>
<input type="textbox" id="lastName" name="lastName">
</form>
<s:div href="/AjaxTest.action" theme="ajax" formId="userData" formFilter="filter"/>
If the attribute "handler" is set, the Javascript function specified by its value will be called, instead of making the request. Use the "handler" function when you want to handle the request yourself.
This div will not make any request, and will just call the function "handler". The first parameter of the function is the Dojo widget for the div, and the second the DOM node for the div.
...
<script type="text/javascript">
function handler(widget, node) {
alert('I will handle this myself!');
node.innerHTML = "Done";
}
</script>
<s:div theme="ajax" href="/AjaxTest.action" handler="handler"/>
| |
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). |
executeScripts | false | When true, Dojo will extract code from the <script> tags from the response and execute it based on the separateScripts value. |
| 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). |
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
Attribute | Description | Type |
|---|---|---|
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 |
startTimerListenTopic | Topic name that will start the timer | String |
stopTimerListenTopic | Topic name that will stop the timer | String |
executeScripts | Javascript code in the loaded content will be executed | Boolean |
updateInterval | Time between requests (in milliseconds) | Integer |
delay | Time to wait before making the first request(in milliseconds) | Integer |
autoStart | Start timer automatically when page loads | Boolean |
Submit
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.
Regular submit button that will update the content of div1:
...
<div id="div1">Div 1</div>
<s:submit type="submit" theme="ajax" value="submit" targets="div1" href="/AjaxTest.action"/>
Submit button using an image:
...
<div id="div1">Div 1</div>
<s:submit type="image" theme="ajax" label="Alt Text" targets="div1" src="${pageContext.request.contextPath}/images/struts-rocks.gif" href="/AjaxTest.action"/>
If the submit button is used inside a form, the form will be submitted asynchronously:
...
<s:form id="form" action="AjaxTest">
<input type="textbox" name="data">
<s:submit type="button" theme="ajax" label="Update Content"/>
</s:form>
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.
...
<s:form id="form1">
<input type="textbox" name="data">
</s:form>
<s:submit type="submit" theme="ajax" href="/AjaxTest.action" 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 | Javascript code in the loaded content will be executed | Boolean |
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:a theme="ajax" href="/AjaxTest.action" 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
...
Javascript code in the loaded content will be executed
...