A central concept in Spring Javascript is the notion of applying decorations to existing DOM nodes. This technique is used to progressively enhance a web page such that the page will still be functional in a less capable browser. The addDecoration method is used to apply decorations.

The following example illustrates enhancing a Spring MVC <form:input> tag with rich suggestion behavior:

<form:input id="searchString" path="searchString"/>
<script type="text/javascript">
    Spring.addDecoration(new Spring.ElementDecoration({
        elementId: "searchString",
        widgetType: "dijit.form.ValidationTextBox",
        widgetAttrs: { promptMessage : "Search hotels by name, address, city, or zip." }}));
</script>
        

The ElementDecoration is used to apply rich widget behavior to an existing DOM node. This decoration type does not aim to completely hide the underlying toolkit, so the toolkit's native widget type and attributes are used directly. This approach allows you to use a common decoration model to integrate any widget from the underlying toolkit in a consistent manner. See the booking-mvc reference application for more examples of applying decorations to do things from suggestions to client-side validation.

When using the ElementDecoration to apply widgets that have rich validation behavior, a common need is to prevent the form from being submitted to the server until validation passes. This can be done with the ValidateAllDecoration:

<input type="submit" id="proceed" name="_eventId_proceed" value="Proceed" />
<script type="text/javascript">
    Spring.addDecoration(new Spring.ValidateAllDecoration({ elementId:'proceed', event:'onclick' }));
</script>
        

This decorates the "Proceed" button with a special onclick event handler that fires the client side validators and does not allow the form to submit until they pass successfully.

An AjaxEventDecoration applies a client-side event listener that fires a remote Ajax request to the server. It also auto-registers a callback function to link in the response:

<a id="prevLink" href="search?searchString=${criteria.searchString}&page=${criteria.page - 1}">Previous</a>
<script type="text/javascript">
    Spring.addDecoration(new Spring.AjaxEventDecoration({
        elementId: "prevLink",
        event: "onclick",
        params: { fragments: "body" }
    }));
</script>
        

This decorates the onclick event of the "Previous Results" link with an Ajax call, passing along a special parameter that specifies the fragment to be re-rendered in the response. Note that this link would still be fully functional if Javascript was unavailable in the client. (See the section on Handling Ajax Requests for details on how this request is handled on the server.)

It is also possible to apply more than one decoration to an element. The following example shows a button being decorated with Ajax and validate-all submit suppression:

<input type="submit" id="proceed" name="_eventId_proceed" value="Proceed" />  
<script type="text/javascript">
    Spring.addDecoration(new Spring.ValidateAllDecoration({elementId:'proceed', event:'onclick'}));
    Spring.addDecoration(new Spring.AjaxEventDecoration({elementId:'proceed', event:'onclick',formId:'booking', params:{fragments:'messages'}}));
</script>
        

It is also possible to apply a decoration to multiple elements in a single statement using Dojo's query API. The following example decorates a set of checkbox elements as Dojo Checkbox widgets:

<div id="amenities">
<form:checkbox path="amenities" value="OCEAN_VIEW" label="Ocean View" /></li>
<form:checkbox path="amenities" value="LATE_CHECKOUT" label="Late Checkout" /></li>
<form:checkbox path="amenities" value="MINIBAR" label="Minibar" /></li>
<script type="text/javascript">
    dojo.query("#amenities input[type='checkbox']").forEach(function(element) {
        Spring.addDecoration(new Spring.ElementDecoration({
            elementId: element.id,
            widgetType : "dijit.form.CheckBox",
            widgetAttrs : { checked : element.checked }
        }));
    });
</script>
</div>