This tutorial is currently being updated to the latest API. Until this warning is removed, please do not use this information.
This page will walk the reader through an example of adding the Reorderer to an HTML file. For more general information about the Reorderer API, see Reorderer API.
Tutorial: Adding the Reorderer to a List
You are organizing a small conference, and there is lots to do. Being the organized person you are, you create a to-do list. You'd like to use the Reorderer to allow the order of items to be changed.
Here's the HTML file for your to-do list before adding the Reorderer - it uses a simple ordered list:
You can download a copy of this file from here: simple-todo-list.html
The Reorderer requires that all orderable items (in our case, the ordered list items) be contained within an element (the "container") with a known ID. We'll consider the ordererd list element itself to be our container. Let's put an
id attribute on the
sortable-todo-list.html. Let's assume that you've downloaded the Fluid component library, and that it lives in a folder called
fluid-components. In the header of the HTML file, we'll link to the require files:
(If you've saved the demonstration file elsewhere, you'll have to adjust the paths.)
and we'll add a line of script at the end of the mark-up, in
sortable-todo-list.html, to invoke the initialization:
The initialization function in
demo.initTodoList(), will instantiate the Reorderer and configure it. For that, it will need the three parameters for the Reorderer constructor.
First, we need the container element for the Reorderer. We identified this element by attaching an ID to it, so let's use that:
li elements in the list are orderable, so let's use jQuery to select all of the
li elements that are direct children of the container:
Another way to identify the orderable elements would be using IDs. We could add an ID to each orderable list item, one with a unique prefix that we can identify with a function, like this:
Then we can use jQuery to find all the elements whose ID starts with that prefix, like this:
These are just example. You can use any method you like, so long as the function returns all of the elements you wish to reorder.
Finally, we need to select a LayoutHandler for use with our Reorderer. The LayoutHandler is what interprets keystrokes and understands what the arrow keys mean. The Reorderer includes a
ListLayoutHandler that will suffice quite nicely for our ordered list, so we'll just use that. It is instantiated with the orderable finder function we wrote:
(In the next release of the Reorderer, you will be able to easily write your own LayoutHandler. In the meantime, the out-of-the-box handlers should cover most types of supported markup.)
So now that we have all the ducks lined up, we just need to add the Reorderer to our list by instantiating it and returning it:
That's it! Our to-do items are now orderable using the mouse or the keyboard.
You can see a working version of the finished product at: sortable-todo-list.html.
You can download a copy of the HTML file from here: sortable-todo-list.html.
You've probably noticed, looking at sortable-todo-list.html, that it's very hard to tell what's orderable, and when you can or can't move things around. There are a number of "interesting moments" that happen while items are being reordered. These include, for example, the moment an item is "picked up" using the mouse, or the moment an item is selected using the keyboard. The Reorderer automatically adds CSS classes to items identifying all the interesting moments, so we can define styles for these classes to control the appearance of these moments.
Let's create a stylesheet. The first style we'll add is
orderable-default, which is attached to all orderable elements in their default state. Let's give them a grey background, so that we can see them clearly:
When the mouse cursor hovers over a draggable item, the
orderable-hover class is applied. Let's make the background light yellow when that happens:
While an item is being dragged using the mouse, an avatar is created and is given the class
orderable-avatar Let's make the avatar a bit see-through:
While an avatar is being dragged, an indicator is created to show where the item will be dropped. The avatar is given a class of
orderable-drop-marker. Let's make it red:
The keyboard can also be used to navigate to and move items. Different styles are used for that. The
orderable-selected style is used to identify which item currently has focus:
orderable-dragging style is applied when the Control key is pressed, to indicate that the item is being moved:
That's it. If we link to this stylesheet in our file, all of the interesting moments will now be visually apparent:
You can see the final stylesheet here: todo-list.css.
You can see a working version of the final styled version at: sortable-styled-todo-list.html.
You can download a copy of this file from here: sortable-styled-todo-list.html.