jQuery UI Sortable Plugin (with XML)

[Clifton]

IMPORTANT: This jQuery plugin DOES NOT support IE 8.

Configuring jQuery UI Sortable plugin (with XML) for use on a ToolBook page.

DEMONSTRATION PAGE AND NOTES:

• Reference jQuery UI documentation: https://jqueryui.com/sortable/#default
• DEMONSTRATION:
  On load page an XML file is retrieved which loads all dependencies and completely configures nearly the entire page.
  The idea of this exercise is to be able to drag the items around until they have been sequentially sorted. Whenever an item is dragged, a user event is sent to the field which contains the activity. The response is to check the sort order and if it is sequentially correct, it changes the color of the event field to green and launches a css animation using pgAnimateCSS() which shakes the field indicating correctness. At the same time, the activity is disabled so that no more items can be dragged.
  
• The activity can be completely configured any way you want, but for the user event to be sent to ToolBook we had to write some JavaScript to handle the jQuery event. You can modify this code to suit your requirements. It is also possible to create multiple matching sortable lists where the user would drag elements between the lists.
• Though not absolutely necessary, it is recommended to set your export for HTML 5 display.

HOW TO SET THIS UP USING XML

1. The authoring layout in ToolBook is VERY simple. ONLY FIVE OBJECTS act as containers for the XML configuration engine to use.
   

   

   Simplicity of page layout at ToolBook Author Level

   Author_1_New.png (88.81 KiB) Viewed 4377 times

2. Actions are placed on page level to retrieve and load the XML file. Once the XML file and all dependencies are loaded, PowerPac's XMLHttpRequest() function sends an on user event to the field which contains the activity (named "FieldToSort"). This field also has actions for the on user event. No other actions are used relative to this activity.
   

   

   Actions on load page loads and applies data from XML file.

   PageActions.png (53.77 KiB) Viewed 4377 times

   
   

   

   On user event ... sent when all js files are loaded AND when user drags an item into position.

   FieldToSort_userEvent.png (39.25 KiB) Viewed 4377 times

   
   NOTES:
   
   1. The FIRST branch of if/then action executes when XML finishes loading all the stylesheets (1) and JavaScript files (2). The PowerPac function XMLHttpRequest() was directed to capture the page data in a variable called tmp and we check the XML tag (index of array tmp) called "pageScript" to make sure it can be executed with PowerPac's exeJavascriptDirect(). The XML script initializes the plugin and binds it to the HTML content in the field "FieldToSort". Finally, the action uses PowerPac's pgAnimateCSS() to fade in the activity field.
   2. The SECOND branch of if/then action executes every time the user drags an item into position. The initialization script ("pageScript")gathers the current order of the draggable items as a comma-separated list of integers based on the HTML id of each item. It then sends a user event to the field "FieldToSort" and the current sort list is then displayed in the field "cOrder". If the list is correct, then the "pageScript" disables the activity (see XML file below) so no more items can be dragged. The color of the field "cOrder" changes to green (using PowerPac's pgStyleObject() function) and PowerPac's pgAnimateCSS() is used to begin shaking the field.

The XML file "pg1_1.xml" which we call on load page contains the following data: (see inline comments)

We gave the XML file the same name as our page but with an .xml extension. In this case, it was called pg1_1.xml.
NOTE: In order to use XML files to configure page elements, your page objects that require XML configuration must begin with a non-numeric character and the name must not contain spaces.

XML File Format:

1. The XML root element is always called <page> ... </page>.
2. The <config> . . . </config> section is executed first and allows you to load stylesheets and JavaScripts and perform many other function executions.
3. Each of the following sections is a tagname which matches (case sensitive) the name of an object on the ToolBook page. The sub-tags in each of these sections defines the tasks to perform on this element, or object. For example, the sub-section <htmlText> . . . </htmlText> permits defining HTML tagged code that should be inserted in a field; the section <pgTBObjSet> . . . </pgTBObjSet> executes the PowerPac function pgTBObjSet() on the object using the parameters defined in XML data tag.
4. The XML data sections do not all have to correspond to objects on the ToolBook page. They can also be used to define variables or containers which store data which the page may access as various events occur. In the case of this XML file, we have defined a section called <pageScript> . . . </pageScript> to intialize the activity.
5. It is possible to have more than one config section. They are executed in the order in which they are defined in the XML document. In the case of this file, we defined <config2> . . . </config2> to execute after the entire data is parsed and its purpose it to re-position the fields preceeding the field "FieldToSort" so it is about 10px above the activity.

NOTES:

• You may notice other formatting in the XML. For example, some of this additional data was included to set up the border radius and shadow on the ToolBook background object and to set the initial state of the field "FieldToSort" to be hidden.
• The tags <![CDATA[ . . . ]]> are used whenever data must be interpreted exactly as entered. These tags also prevent mis-interpretation of the data when characters are used that are also part of the general structure of an XML file.
• XML data is cached in the client browser session. It is not discarded on page navigation and can be retrieved and used at any time in the ToolBook application. Once cached, pages load lightning fast when navigating back and forth between them. To access cached XML data, simply use PowerPac's XMLHttpRequest() function to get the data. If the data exists in the cache it will be returned back to the function. Otherwise, it will be loaded from the server.

FINAL COMMENTS:
Virtually every jQuery UI plugin can be used in a ToolBook application. I am glad to assist in setting these up to customize your projects to your specific needs and to create interesting effects and behaviors. Please contact me at [email protected].

HAVE FUN!