struts2-jquery-plugin

A struts2 ajax framework using the jQuery javascript library

Struts2 jQuery Plugin

The struts2-jquery-plugin is a plugin providing first-class support for AJAX to struts2.

The plugin uses the jQuery javascript library and a very lightweight publish/subscribe framework built on jQuery to implement a set of tags and tag widgets that enable asynchronous loading of UI components and de-coupled interaction between UI components in a simple, standard way.

Check out the project http://struts2-jquery.appspot.com/'>Showcase
Check out the new Chart component
Latest version uses (jquery 1.4.2 and final jQuery-ui.1.8.1)

Basic Usage
Tags
Publish/Subscribe Framework
Extending the Framework

Basic Usage

To use the struts2-jquery tags

Include the http://code.google.com/p/struts2-jquery-plugin/downloads/list in your application classpath
Include the struts jquery tag library on your jsp page (<%@ taglib prefix="sj" uri="/struts2-jquery-tags" %>)
Include the

<sj:head>

tag in the head of your jsp page 1. Use the ajax enabled struts2 tags

<sj:xxxx>

tags.

<%@ taglib prefix="s" uri="/struts-tags" %> <%@ taglib prefix="sj" uri="/struts2-jquery-tags" %> <html> <head> <sj:head compressed="false"/> <title><s:text name="application.title"/></title> </head> <body> <sj:div id="header" src="header.action"/> <sj:div id="content" src="content.action"/> <sj:div id="footer" src="footer.action"/> </body> </html>

Features

The tags have a lot of attributes which provide dynamic functionality and provide relevant event/event-handling hooks using the publish/subscribe framework to interact with each other or with custom client code. The easiest way to summarize the functionality provided by the tags is to list the features that the various 'types' of tags provide:

Loading Remote Content (anchor, dialog, div, submit)

Load remote content via ajax into one or multiple targets
Submit form(s) with request
Submit input element(s) (even independent of form) with request
Show loading element during load
Show loading text during load
Show error element on load error
Publish topic(s) (execute topic handlers) on loading complete
Publish topic(s) (execute topic handlers) on loading success
Publish topic(s) (execute topic handlers) on loading error
Expose reload topics (topics that will cause container to automatically reload content to via ajax)
Expose enable/disable topics (topics which will allow/prevent remote content loading)

'Input' Components (select,textfield,textarea,datepicker)

Load contents remotely using ajax (json string)
Expose reload topics (topics that will cause input to automatically reload content to via ajax)
Publish topic(s) (execute topic handlers) on input value change
Publish topic(s) (execute topic handlers) on input focus
Publish topic(s) (execute topic handlers) on input blur
Expose focus topic(s) (topics that will cause component to focus)
Expose blur topic(s) (topics that will cause input to lose focus)

'Interactive' Components (div,select,submit,textfield,tab,dialog,datepicker)

Expose enable topics (topics that will cause component to be enabled)
Expose disable topics (topics that will cause component to be disabled - this will also prevent ajax requests while disabled)

General Features (all components)

Expose hide topics (topics that will cause component to be hidden)
Expose show topics (topics that will cause component to be displayed)
Expose removed topics (topics that will cause component to be removed from DOM)

Publish/Subscribe Framework

The plugin uses a very lightweight but powerful publish/subscribe framework which allows for fully decoupled interaction between component events.

The framework comes with out-of-the box hooks for common component events (clickTopics) and event handlers (such as onClickTopics) which allow the components on the page to interact very flexibly yet simply with each other. For example, to make one div load when another is finished loading or show a dialog if there's a loading error is as easy as follows: <%@ taglib prefix="s" uri="/struts-tags" %> <%@ taglib prefix="sj" uri="/struts2-jquery-tags" %> <html> <head> <sj:head compressed="false"/> <title><s:text name="application.title"/></title> </head> <body> <sj:div id="firstDiv" onSuccessTopics="loadSuccess" onErrorTopics="loadError" src="first.action"/> <sj:div id="dependentDiv" showTopics="loadSuccess" src="second.action" cssStyle="display:none"/> <sj:dialog id="errorDialog" showTopics="loadError" src="error.action"/> </body> </html>

Another example, to update the contents of a second select box when the value in a first one changes is as easy as follows: <%@ taglib prefix="s" uri="/struts-tags" %> <%@ taglib prefix="sj" uri="/struts2-jquery-tags" %> <html> <head> <sj:head compressed="false"/> <title><s:text name="application.title"/></title> </head> <body> First Select: <sj:select id="firstSelect" name="firstSelect" onChangeTopics="firstSelectChanged" src="firstSelect.action"/> Second Select: <sj:select id="secondSelect" reloadTopics="firstSelectChanged" src="secondSelect.action" elementIds="firstSelect"/> </body> </html>

The publish/subscribe framework is fully exposed, so users can also implement custom handlers for any topics and can publish and subscribe to any topics using custom code as follows:

``` <%@ taglib prefix="s" uri="/struts-tags" %> <%@ taglib prefix="sj" uri="/struts2-jquery-tags" %>

        $.subscribe('loadSuccess', function(event,element) {
           alert('Successfully loaded first div');

           $.publish('loadSuccessConfirm');
        });

     </script>
  </head>
  <body>  
     <sj:div id="firstDiv" onSuccessTopics="loadSuccess" src="first.action"/>
     <sj:dialog id="successDialog" showTopics="loadSuccessConfirm" src="error.action"/>
  </body>

```

The above example will: 1. Display an alert when the div successfully completes loading by subscribing to the 'loadSuccess' topic which the div publishes (set to the div's onSuccessTopics event publisher) 1. Display the dialog by publishing the 'loadSuccessConfirm' topic (which the dialog's showTopics event listener is subscribed to)

For additional information on using the integrates publish/subscribe framework, see the jquery.subscribe.js source document included with the plugin or visit the jquery subscribe/publish plugin site at http://plugins.jquery.com/project/jQuerySubscribe.

Extending the Framework

The framework provides four explicit extension points: 1. Implementing custom subscribe/publish topics and handlers 1. Implementing and binding custom widgets 1. Implementing custom pre-binding function for existing components 1. Implementing custom post-binding function for existing components

See Customizations / Extensions for more...

Project Information

License: Apache License 2.0
57 stars
svn-based source control

Labels:
Struts2 jQuery ajax tags

Code

Archive