Order-Changed Callback - v0.4
- Anastasia Cheetham
- Colin Clark
This documentation refers to the v0.4 released version of the Order-changed Callback code. For documentation specific to the trunk, please see Talking to the Server Using The afterMove Event.
Application developers can use the Reorderer to allow their users to directly move around and re-arrange content on the page. In most cases, the application running on the server will want to know about any changes to the ordering. The order-changed callback is used for this purpose.
The order-changed callback is a function that is passed to Reorderer initialization. This function must be written by the application developer, and is responsible for communicating changes in ordering to the server in whatever form the server requires. This might take the form of an AJAX call sending a JSON object, or a form submission, for example.
Join the fluid-talk mailing list and ask your questions there.
Example callback: Form submission
A form submission can be used to send the updated order to the server. One way to accomplish this might be to associate a hidden <input> element with each orderable item. The value of the input element would be its ordinal number:
<form action="...">
<div id="container">
<div id="orderableItem0">
...
<input id="item0-index" value="0" type="hidden"/>
</div>
<div id="orderableItem1">
...
<input id="item1-index" value="1" type="hidden"/>
</div>
<div id="orderableItem2">
...
<input id="item2-index" value="2" type="hidden"/>
</div>
</div>
</form>
Any time an item is moved, the order-changed callback function will update the value of each hidden input with their new indices, and submit the form. When the application on the server receives the form submission, it can store the new information in whatever way it sees fit:
/**
* This function creates and returns a function that submits a form
*/
myCallbackCreator: function (container) {
// the findForm() function looks for a form element that is an ancestor of the container
var reorderform = fluid.utils.findForm (container);
// return a function that will be called each time the order changes
return function () {
// get the input elements associated with the orderable items by looking for
// elements whose id ends with "-index"
var inputs = jQuery("[id$='-index']";
// update the 'value' of the element with their current index (i.e. order)
for (var i = 0; i < inputs.length; i = i+1) {
inputs[i].value = i;
}
// submit the form using jQuery's post() function
if (reorderform && reorderform.action) {
jQuery.post(reorderform.action,
jQuery(reorderform).serialize(),
function (type, data, evt) { /* No-op response */ }
);
}
};
}
The function created can be passed to the Reorderer initialization function:
var myCallback = myCallbackCreator(myContainerEl);
fluid.reorderGrid("#container", "[id^='orderableItem']", myCallback);
Example callback: JSON
/**
* This function generates a JSON string containing ordering information.
* This string will be sent to the server by the callback.
*/
generateJSONStringForOrderables: function (orderables) {
// Create a simple data structure keyed by element id and with the ordinal number as value.
var orderMap = {};
jQuery.each (orderables, function (index, element) {
orderMap[jQuery(element).attr("id")] = index;
});
// Then serialize it to a JSON string.
return JSON.stringify(orderMap);
},
/**
* This function creates and returns a function that submits a form
*/
myCallbackCreator: function () {
// return a function that will be called each time the order changes
return function () {
var orderMapJSONString = generateJSONStringForOrderables(listOfOrderableItems);
// POST it back to the server via XHR.
jQuery.post (urlToPostJSON, {order: orderMapJSONString});
};
}