The following screen gives an idea about the look and feel of the sortable list of stories.

jQuery Sortable component

Let us start to have a look at the front end. I am using jQuery together with jQuery-ui. Everybody doing series web development (should) know jQuery. I have written about jQuery before, but other have as well. Just do a search on google and the amount of articles is massive. Dzone also contains a few items each day about top 5 plugins for jQuery. I think the power of jQuery-ui is not known that much. If you have not seen it before, be sure to check it out. It can help you a lot in creating websites that look sharp with icons and colors that are well balanced. The ui framework contains a lot of interaction components, widgets and effects. This blog posts focus is on the Sortable interaction component.

With the sortable component you can actually drag the components in order. You get notified of the change.

Setting op de component

Before we can use the component we need to download the jquery-ui component. The jQuery UI project contains a download function to create your customized download. Don’t forget to include at least the sortable function. You can also follow a long with the sources I use in the your-scrum project. Now include the js files in your page. I use the script.js file to set generic libraries. (webapp/includes folder). Now open up the stories.jsp file under webapp/WEB-INF/jsp/story folder.

We begin by creating the list of items and use jQuery to make a sortable list out of it.

<ul id="sortable">
    <c:forEach items="${stories}" var="story">
        <li id="story_${story.id}" class="ui-state-default"><span class="listItemLabel">${story.name}</span></li>
    </c:forEach>
</ul>

Within the script block we now have to initialize the sortable component.

var idsOldOrder;
$(function() {
    $("#sortable").sortable();
    idsOldOrder = $("#sortable").sortable('serialize').toString();
    $("#sortable").disableSelection();
    $("#sortable").bind('sortupdate', function(event, ui) {
        var ids = $("#sortable").sortable('serialize').toString();
        $.post('/story/reorder', {ids: ids, oldIds: idsOldOrder}, function(data) {
            // nothing special
            window.alert(data);
        });
        idsOldOrder = ids;
    });
});

This code might look more difficult than you did expect. That is because more is happening here than you expect. Within this code we need only the first line to show the sortable items. The other lines are for notification of changes. Don’t worry we explain them as well. Time to move on.

Capturing change events

Have a look at the previous code block. The second line stories a special form of presentation in a string. We need this on the server to actually determine the change. Than in line 4, we bind a function to the sortupdate event. Again a string containing the ids in the new order is created. Using the jQuery Ajax tooling we send a request to the server. The POST is done to the url /story/reorder with two parameters: ids and idsOldOrder. The result is shown in an alert box, which is not nice, but it works for now.

From the client side perspective, that is all there is to it. I actually wanted to have a real change from the library, like this item is moved before that item. But I could not find how to do just that. Therefore I had to do the trick with the old order and the new order. Now the server has to take care of finding the actual change. More on that later.

Add task button

One of the stories for our project is to add a new task to a story. If you have a look at the image containing a screen dump (the first image of this blog post) you see on each story the amount of tasks and an orange plus sign. The plus sign is something we use from the jquery-ui project as well. How to do this.

First we must add the content to the html using the jsp. So we have to extend the jsp with a text containing the number of tasks and a link that we can click to go to the add task form. The jsp now becomes:

<ul id="sortable">
    <c:forEach items="${stories}" var="story">
        <li id="story_${story.id}" class="ui-state-default"><span
                class="listItemLabel">${story.name}</span><span
                class="listItemAdd"><a
                href="/story/${story.id}/task/form" title="add task"><spring:message code="generic.add"/></a></span><span
                class="listItemChilds">tasks(${story.numberOfTasks})</span></li>
    </c:forEach>
</ul>

Have a good look at the classes of the span elements. We are going to use them to change the appearance of the add link into that nice plus sign button. We are replacing the link with an image, clicking the image will call the function myClick which uses the actual link from the a element and opens that url. Have a look at the changes in the code.

var myClick = function (event) {
    var location = $(event.target).children("a")[0].href;
    window.location = location;
};
$(function() {
    // only show changes, refer to previous code block for other lines
    $("#sortable li span.listItemAdd").addClass("ui-icon ui-icon-circle-plus").click(myClick);
});

Getting the icon with the plus sign is a jQuery trick as well. There are some style sheets that contain all the icons. You just need to find the right class to add to a span and you are done. I used the ui-icon ui-icon-circle-plus. More on the available icons can be found in the documentation.

Other jQuery things

There are other things I use from jQuery. Check the references section for documentation. I use the corner plugin for the navigation. If you like the navigation implementation have a look at the main.jsp file in webapp/decorators. The final jQuery thing I want to mention is the hotkeys plugin. You can create hotkeys to be used on your page. I created a hotkey ctrl+s to open up the new story screen. The following code block shows the implementation.

var newStory = function (event) {
    window.location = '/story/form';
    event.stopPropagation();
    event.preventDefault();
    return false;
};
$(function() {
    $(document).bind('keydown', 'ctrl+S', newStory);
});

Finding the change on the server component

The current status is that we have a POST to the server with two string containing ids in the old and the new order. Now we have to find the change. On the server I use Spring 3 to handle requests. I am not going to explain all the spring 3 configuration in this post. If you want to learn about spring 3 I advise you to go over the reference documentation.

Handling the POST consists of two parts. The first part is finding the change from the two mentioned strings. The second part is communicate the change to the domain and persisting the change. In a next post I’ll focus more on the domain and the persistence part. For now have a look at the complete method that accepts the POST and handles it.

    @RequestMapping(value = "/story/reorder", method = RequestMethod.POST)
    public String reorderStories(@RequestParam("ids") String ids,
                                 @RequestParam("oldIds") String oldIds, ModelMap modelMap) {
        ItemSorter itemSorter = new ItemSorter();
        ChangedSortOfItems changedSortOfItems = itemSorter.determineChangeInStoryOrdering(strip(ids), strip(oldIds));

        Long movedItemId = null;
        try {
            if (StringUtils.hasText(changedSortOfItems.movedItem())) {
                movedItemId = Long.parseLong(changedSortOfItems.movedItem());
            }
        } catch (NumberFormatException e) {
            logger.warn("Number format exception of id from story to be planned while nog expected : "
                    + changedSortOfItems.movedItem());
        }

        Long beforeItemId = null;
        try {
            beforeItemId = Long.parseLong(changedSortOfItems.beforeItem());
        } catch (NumberFormatException e) {
            logger.warn("NUmber format exception while nog expected");
        }
        backlogService.plan(movedItemId, BEFORE, beforeItemId);

        modelMap.addAttribute("message", "story.order.changed");
        return "message";
    }

This code should not be to hard to follow, now lets have a look at the ItemSorter class. This class uses the string to find differences. An instance of ChangedSortOfItems is returned that contains information about the items that have changed. In the end it is all about going through the list of items to find the first that changed from position. The first item that is different does not have to be the actual item that is moved. We can check that by looking at the next item. Have a look at the code if you can see what happens.

    public ChangedSortOfItems determineChangeInStoryOrdering(String ids, String oldIds) {
        validateInput(ids, oldIds);

        if (ids.equals(oldIds)) {
            return ChangedSortOfItems.nothingChanged();
        }

        String[] arrayOfCurrentIds = StringUtils.delimitedListToStringArray(ids, delimiter);
        String[] arrayOfOldIds = StringUtils.delimitedListToStringArray(oldIds, delimiter);

        // A change must be found since the items are not equal
        ChangedSortOfItems change = null;
        int indexFirstChangedItem = findchangeInItems(arrayOfCurrentIds, arrayOfOldIds);
        // If you start at the beginning, the last item can never be the first item to change position
        String nextOfFirstChangedItem = arrayOfCurrentIds[indexFirstChangedItem + 1];

        if (nextOfFirstChangedItem.equals(arrayOfOldIds[indexFirstChangedItem])) {
            change = ChangedSortOfItems.movedBefore(arrayOfCurrentIds[indexFirstChangedItem],
                    arrayOfOldIds[indexFirstChangedItem]);
        } else {
            int lastitem = arrayOfCurrentIds.length - 1;
            for (int indexMovedBefore = indexFirstChangedItem; indexMovedBefore < arrayOfCurrentIds.length;
                 indexMovedBefore++) {
                String movedItem = arrayOfCurrentIds[indexMovedBefore];
                if (indexMovedBefore == lastitem) {
                    change = ChangedSortOfItems.movedToEnd(movedItem);
                    break;
                } else {
                    String aNextOldItem = arrayOfOldIds[indexMovedBefore + 1];
                    if (!movedItem.equals(aNextOldItem)) {
                        change = ChangedSortOfItems.movedBefore(movedItem, aNextOldItem);
                        break;
                    }
                }
            }
        }
        return change;
    }
    private int findchangeInItems(String[] arrayOfCurrentIds, String[] arrayOfOldIds) {
        for (int i = 0; i < arrayOfCurrentIds.length; i++) {
            String possibleMovedItem = arrayOfCurrentIds[i];
            String originalItem = arrayOfOldIds[i];
            if (!possibleMovedItem.equals(originalItem)) {
                return i;
            }
        }
        throw new NoChangeInSortFoundException();
    }

I hope the code is understandable. If not, questions can be asked in the comments .

Concluding

Again I have to conclude that jQuery is a fantastic framework for client side development. I also have to conclude that the documentation and available samples are not always thorough enough. I am still not sure if there is no easier way to find the actual change. But maybe one of the readers of this blog out there can help me out. I do love the extendibility of the jQuery components.

If you liked this post, please push me up at dzone, if you have questions or remarks do not hesitate to use the comments.

References

• http://code.google.com/p/your-scrum/
• http://jqueryui.com/demos/sortable/
• http://jquery.malsup.com/corner/
• http://code.google.com/p/js-hotkeys/
• http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html

Training Overview, this application used almost the same architecture as the raffle application. More focus on testing with and without the springframework, and jquery together with spring mvc 2.5

So what is it all about, that jQuery. To me it is a very easy to use light weight dom browsing framework with some very handy plugins. The architecture as been made to be very extendible. Let’s start with a very easy example:

$(document).ready(function() {
	$("#easysample").hide();
});

<div id="easysample">Easy sample</div>

This sample shows a div and a piece of javascript (that should be positioned in the header within script tags). Right after the dom tree has been created and before it will be shown, the function ready will be called. Within this function we do a search on the dom for an elemen called easysample. To the result we say hide. Easy does it. This is the first time I thought about the difference between creating the dom and making it ready to be shown on the screen. The normal javascript function onLoad in the body tag waits till the whole document is shown on the screen, which is pretty strange if you know up front that you are going to change it. Next to that it looks strange as well, it is a sort of flickr in the website when starting the page. So this is what $(document).ready is about. The second part starting with function () is the callback function. We provide the ready function with what we call a callback function. The event should call this function when it occurs.

This sample is a bid stupid, because you will get a blank screen. Let’s put a link in there that will help us show the div, hide it again, and keep a counter within the div showing the amount of times it was hidden. Here is the complete code:

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title>Easysample</title>
    <script type="text/javascript" src="js/jquery-1.2.1.min.js"></script>
    <script type="text/javascript">
        var clickTimes = 0;
        $(document).ready(function() {
            $("#easysample").hide();
            $("#togglelink").click(function() {
                $("#easysample").html("Easy sample : clicked " + ++clickTimes + " times").toggle();
            });
        });
    </script>
</head>
<body>
    <span id="togglelink">Click me</span>
    <div id="easysample">Easy Sample</div>
</body>
</html>

Again right after the document model is ready we hide the div and we assign a callback function to the click event of the span. The function html sets the provided text as the contents for the element that was found. The toggle function toggles between hide and show. You can find a running version of the sample here.

Just like hiding and showing, we an also toggle styles. Have a look at the following example code. I’ll only show the document ready part:

$("#togglelink").click(function() {
    $("#easysample").html("Easy sample : clicked " + ++clickTimes + " times").toggleClass("attention");
});

You can find a running version of the sample here

So we know how to identify an element, know how to show and hide it, can change the contents and can add style. The mentioned book covers a lot more of course, there is a lot to be said about the whole event model. This model is not very consistent across all browsers. jQuery makes it a lot easier to do. For me two other things were very important: Making things look nice without to much effort and doing some ajax. Let’s have a look at that.

For visual effects we will use a plugin that is supported by the jQuery team called UI, yes cool isn’t it? You can find more information at there website with some cool demo’s. I like the sortable table plugin. Not that I did not see more fancy scripts, and actually I am missing a filter option, but I’ll have a look at that the coming weeks. Take a look at the following code. I do not present the whole html code mode you will understand what happens. Before you can use this yourself, read about the stylesheets, the images etc. You do need to include the javascript with the table stuff in there, you need to include some styles and three images there are referenced by the style sheet.

    <link rel="stylesheet" type="text/css" href="styles/flora.tablesorter.css"/>
    <script type="text/javascript" src="js/jquery-1.2.1.min.js"></script>
    <script type="text/javascript" src="js/jquery.tablesorter.pack.js"></script>
    <script type="text/javascript" src="js/jquery.tablesorter.pager.js"></script>
    <script type="text/javascript">
        $(document).ready(function() {
            $("#datalist")
                    .tablesorter({sortList:[[2,0],[3,1]], widgets: ['zebra']})
                    .tablesorterPager({container: $("#pager")});
        });
    </script>

    <table id="datalist" class="tablesorter">
        ...
    </table>

A lot of the nice stuff is handled in the stylesheet. Please take a look at the online sample here. The above code shows the two additional scripts to load (beware, I had to download the most recent versions which can be found here). We also need to load a stylesheet, I took the one from the ui.query homepage. For the pager stuff you need to add an additional div and some icons. Download the complete package from the website and you will find the required resources. There is one thing I want to mention as well. The tablesorter function accepts a sortList parameter. This sortList is an array of arrays. Where the inner arrays contain two numbers, the first represents the column (starting at zero), the second reopresents the sorting. A zero for sorting means ascending and 1 descending. These are used as deafults when the table is creted.

We are almost at the end of my introduction. The final thing to show is some ajax to call the server. The sample will come up with a table that has some clickable fields. By clicking on the field you will obtain detailed information about the field from the server. For now the detailed information is coming from a php page and that is not working for me. But the general concept stays the same. You can find the running sample here. The most important part of the code is in the next code block.

    <script type="text/javascript">
        $(document).ready(function() {
            $("#datalist").tablesorter({sortList:[[2,0],[3,1]], widgets: ['zebra']});
        });
        function details(name) {
            $("#detailscontent").load("persondetails.php", {personname : name}, function() {

            });
        }
    </script>
    <body>
    ...
        <tr><td><a href="#" onclick="details('jettro')">Jettro</a></td><td>35</td><td>1.80</td><td>male</td></tr>
    ...
        <div id="detailscontent">Details</div>
    </body>

The detailscontent div is used to present the new obtained data. Within the link we call a javascrip, deatils. This javascript does load the new content for the div. This piece of code is all there is to it:

$("#detailscontent").load("persondetails.php", {personname : name}, function() {});

The function accepts the page to load (persondetails.php), the parameters to pass to the server using the request object ({personname : name}) and finally a callback function, which we do not use in the sample.
For another application I am creating (you cannot see this live, but you can see the code), I am also using this technique. In this application I am talking to a spring-mvc 2.5 application. You can find the maven generated site here (same as the one at the beginning of this blog item. You can find the complete code of this application in google code. The following piece of code should look familiar by now. It is called after clicking a link and it calls the url projectemployees.view with the parameters projectId.

        function fillEmployeesBox(projectId) {
            $("#employeesBox").load("projectemployees.view",{projectId : projectId}, function() {
                $(".zebra tr:nth-child(even)").addClass("striped");
                $("#employeesBox").show();
            });
        }

Hope you liked this short introduction into jquery. There are a lot of resources to be found on the web. Of course the jquery homepage http://jquery.com/ is a very good place to start. And I have shown a book which helps me a lot during my jquery programming.