I’ve started writing articles for Smashing Magazine. Smashing is a much larger community with some amazing content.

Check out my latest articles there:

Web-Drawing Throwdown: Paper.js Vs. Processing.js Vs. Raphael

How To Create Web Animations With Paper.js

Searchable Dynamic Content With AJAX Crawling.

Check them out.

Today Bess Siegal drops by so we can show how Spiffy UI works with Node.js.

The best feature of REST is running it from anywhere and calling it from anywhere. Spiffy UI is a GWT framework you can run on any server. We’ve said that from the beginning, now we’re going to prove it.

This article turns the normal stack upside down and creates a rich GWT client that calls a JavaScript server written with Node.js. This simple server and rich client scales to the cloud and shows you a little about Spiffy UI security.

Creating Hello Spiffy Auth Node

Creating a new Spiffy UI project for Java is easy. The project creator gives you a simple build with a GWT client and a Java server. They’re both Java, but the separation between the client and server make it easy to replace the server with a different technology like Node.js.

Node.js runs JavaScript on your server; a little funny since we’re replacing the client-side JavaScript with GWT. The key to this architecture is making a thicker client with a thinner server. When servers get thinner they scale better and take fewer resources.

Spiffy UI already has Hello Spiffy Ant and Hello Spiffy Maven. We’ll make this new project Hello Spiffy Auth Node.

This project builds with Apache Ant. That tool creates the GWT compiled code in a directory called targetDir. Next we create our Node script, HelloSpiffyAuthNode.js. Before we create our server, we call init.

HelloSpiffyAuthNode.js, starting at line 26

init: function() {
    var targetDirFull = path.join(process.cwd(), targetDir);
    path.exists(targetDirFull, function(exists) { 
        if (exists) {
            HelloSpiffyAuthNode.runServer();
        } else {
            sys.puts('===================================================\n');
            sys.puts('You have to build the Spiffy UI client before \n');
            sys.puts('running the server.  Run the ant in the current \n');
            sys.puts('directory and then run the server again.\n');
            sys.puts('===================================================\n');
        }
    });
},

We run HelloSpiffyAuthNode.js from the project’s root directory so that joining the current working directory, process.cwd(), with targetDir will be the full path to where our static files are. Node.js needs a little extra code to serve our static files, and we want to make sure they’re there before we start the server1.

Serving static files from Node.js

The GWT compiler produces JavaScript embedded in some very long HTML files. From a server-side point of view these files are completely static. All the server needs to do is serve them. There are Node frameworks, such as Express, that can handle this for you, but we don’t need them for this simple example.

HelloSpiffyAuthNode.js, starting at line 51

var server = http.createServer(function(request, response) {
    /*
     * Handle based on the URI
     */
     var uri = url.parse(request.url).pathname;

    /*
     * Try to find a static file that matches the
     * current working directory/target/www/file name
     *
     * (process.cwd() gets the current working directory)
     */
     var filename = path.join(process.cwd(), targetDir, uri);  
     path.exists(filename, function(exists) {

         /*
         * Serve up the static file that is in /target/www
         */

         if (filename.match('/www/$') !== null) {
             // Then this is a request for the root and we'll return
             // the index.html file
             filename += 'index.html'; 
         }

         fs.readFile(filename, 'binary', function(err, file) {
            if (err) {
                response.writeHeader(500, {'Content-Type': 'text/plain'});
                response.end(err + '\n');
                return;
            }

            response.writeHeader(200);
            response.write(file, 'binary');  
            response.end();
        }); //end fs.readFile callback

Joining process.cwd(), targetDir, and the uri, creates the full path and name of the static file to serve.2 We then read the file and write it to the response.3

We also handle the URI at the root and return the default home page index.html4. This simple function returns any of the static files, including those created by GWT. Now we can implement our REST endpoints.

A REST server in Node.js

Our project implements one REST call at /simple/<name entered by user>. Normally we would implement this as a separate function, but our example is so simple that we just put it inline.

HelloSpiffyAuthNode.js, starting at line 71

if (!exists) {
    if (uri.indexOf('/simple/') === 0) { 
        /*
         * This is the REST call!
         */
        var user = uri.substring(8);
        var userAgent = request.headers['user-agent'];
        var payload = {user: user,
                       userAgent: userAgent,
                       serverInfo: 'Node.js'}; 
        response.writeHeader(200, {'Content-Type': 'application/json'});
        response.end(JSON.stringify(payload));
        return;
    }

If the static file was not found, we test whether the uri is a REST request5. If it is, we return our simple JSON response. 6

Handling localization

Spiffy UI provides a couple of servlets for handling localization. We took the same basic algorithm for matching the list of the browser’s preferred locales with the list of supported locales for our application and put it into HelloSpiffyAuthNode.js.

This may sound complex, but the idea is fundamentally simple. The browser specifies a list of preferred locales with every request to the server. For example, the browser might say, I prefer French, then I’ll take German, and if you don’t have either of those give me English. This makes it possible for websites to do their best to provide the correct content.

Before we can even respond to the browser we have to figure out what languages we support. We do this by reading all the internationalized libraries included by Spiffy UI to localize dates and times.

HelloSpiffyAuthNode.js, starting at line 167

/*
 * Load all the internationalized resources by reading the i18n directory
 */
fs.readdir(path.join(process.cwd(), targetDir,  i18nDir), 
           function(err, files) {
    HelloSpiffyAuthNode.resources = files;

    /*
     * After resources are retrieved then the server can listen
     */
    server.listen(port);

    sys.puts('=========================================================\n');
    sys.puts('Access Hello Spiffy Node at http://localhost:' + port + '\n');
    sys.puts('=========================================================\n');

});

All the files found in the i18nDir are stored in the HelloSpiffyAuthNode.resources variable.7 Then we add another simple condition to handle a localized date request.

HelloSpiffyAuthNode.js, starting at line 121

else if (uri === i18nDir + 'date' ||
         uri === i18nDir + 'jquery.ui.datepicker.js') {
    /*
     * This is an internationalized file request!
     */
    var resource  = HelloSpiffyAuthNode.getI18nDateResource(request, uri);
    filename = path.join(process.cwd(), targetDir, i18nDir, resource); 
    /*
     * Do not return -- let it get the correct i18n date file below
     */
}

The getI18nDateResource function returns the best fit for the given list of preferred locales in the request’s accept-language header as compared with the locales embedded in the file names stored in the HelloSpiffyAuthNode.resources variable. The full path to the appropriate localized static date JavaScript file is produced at the end of this condition block8.

This simple example does not use any Messages class. If you want to add one so you can localize strings, you just need to add additional logic in your Node script to load the localized properties files then implement script to mimic the behavior of Spiffy UI’s locale filter. Hello Spiffy Localization is a good example of localizing a Spiffy UI project.

That’s everything we need to serve our Hello Spiffy Auth Node project. We haven’t changed our client and our whole server is about 150 lines of code. We can run the project now and serve anonymous requests. However, we’d also like to secure the REST endpoint.

Adding security

We want to add an authentication layer to secure our data. Spiffy UI provides a security scheme for REST endpoints. We’ll implement that scheme on our server and our client will work with just a few minor tweaks.

Adding security to our client

Spiffy UI handles client-side security as part of the REST framework. We add a little to our UI to show the user when they’re logged in and support log out.

We add the welcome banner and logout link to our MainHeader.

Index.java, starting at line 76

Anchor logout = new Anchor("Logout", "#");
logout.getElement().setId("header_logout");
header.setLogout(logout);
if (!Index.userLoggedIn()) {
    logout.setVisible(false);
    header.setWelcomeString("");
} else {
    header.setWelcomeString("You are logged in!");
}
logout.addClickHandler(new ClickHandler() {
        public void onClick(ClickEvent event)
        {
            event.preventDefault();
            doLogout();
        }
    });

Also, a login listener is added so the welcome banner can show the user name when the user logs in.

Index.java, starting at line 129

RESTility.addLoginListener(new RESTLoginCallBack() {

    @Override
    public void onLoginSuccess()
    {
        if (RESTility.getUserToken() == null) {
            return;
        }
        header.setWelcomeString("Welcome " + RESTility.getUsername());
        JSUtil.bounce("#" + MainHeader.HEADER_ACTIONS_BLOCK, 5, 500, 30);
        JSUtil.show("#header_logout", "fast");
    }

    @Override
    public void loginPrompt()
    {
        //do nothing
    }
});

The supporting userLoggedIn and doLogout methods simply call methods provided by Spiffy UI’s RESTility.

Index.java, starting at line 220

/**
 * returns whether the  user is logged in or not
 * @return true if the user is logged in (browser cookie is there)
 */
public static boolean userLoggedIn()
{
    String userToken = RESTility.getUserToken();
    if ((userToken == null) || (userToken.length() <= 0)) {
        return false;
    }
    return true;
}

/**
 * Logout of the application
 */
public static void doLogout()
{
    RESTility.getAuthProvider().logout(new RESTObjectCallBack() {
        public void success(String message)
        {
            Window.Location.reload();
        }

        public void error(String message)
        {
            Window.Location.reload();
        }

        public void error(RESTException e)
        {
            MessageUtil.showFatalError(e.getReason());
        }
    });
}

That’s all we need to make our client aware of authentication. The next step is to add security to our server.

Adding security to our server

When the REST request is made, we must first check that the request is authorized by looking at the request’s authorization header.

HelloSpiffyAuthNode.js, starting at line 72

if (uri.indexOf('/simple/') === 0) {
    if (isAuth(request.headers['authorization'])) {
        /*
         * This is the REST call!
         */
        var user = uri.substring(8);
        var userAgent = request.headers['user-agent'];
        var payload = {user: user, 
                       userAgent: userAgent, 
                       serverInfo: 'Node.js'};
        response.writeHeader(200, {'Content-Type': 'application/json'});
        response.end(JSON.stringify(payload));
        return;
    } else {
        /*
         * Return the unauthenticated fault and include the header 
         * for authentication
         */
        response.writeHeader(401, {'Content-Type': 'application/json',
            'WWW-Authenticate': 'X-OPAQUE uri="http://localhost:' + port + 
            authUri + '", signOffUri=""'}); 
        var fault = {'Fault': {'Code': {'Value': 'Sender', 'Subcode': 
            {'Value': 'NoAuthHeader'}}, 'Reason': {'Text':''}}};
        response.end(JSON.stringify(fault));
        return;
    }
}

If authenticated, the regular payload is returned, otherwise the fault payload is returned with the WWW-Authenticate header for the authentication server.9 In this example the authentication server is the same Node server at authUri.

In the UI, you’ll see this in action when you click the “Submit” button. If you are not authenticated, you will be shown the login screen. When you click “Login,” the Spiffy UI framework will automatically POST a request to the URL /auth. It is up to the handler of /auth to continue to delegate authentication responsibilities to the URL specified by the WWW-Authenticate header. In our example, we know that /auth is the same as the authUri, so we by-pass the delegation and just handle it directly.

Now we add code to our Node server to handle the posted authentication request.

HelloSpiffyAuthNode.js, starting at line 99

else if (uri === authUri) {
    if (request.method === 'POST') {
        /*
         * Any username and password combination is fine for this
         * sample, return the token, which is just the timestamp.
         */
        var token = '' + new Date().getTime()
        var json = {'Token': token};
        tokens.push(token);
        response.writeHeader(200, {'Content-Type': 'application/json'});
        response.end(JSON.stringify(json)); 
        return;
    } else if (request.method === 'DELETE') {
        var authHeader = request.headers['authorization'];
        removeToken(authHeader);
        response.writeHeader(200, {'Content-Type': 'application/json'});
        
        var json = {'Status': 'OK'};
        response.end(JSON.stringify(json)); 
        return;
    }
}

If the request’s method is POST, we know that it is a request to authenticate. In this example, we just accept any username and password combination, keep track of the new token, and return the token back to the browser.10 Spiffy UI will then automatically re-issue the original REST request with the authentication token in its authorization header, so our Node server will validate it11 and return the expected /simple payload. In the browser you will then see the username you entered in the welcome banner and the results of the /simple REST request will be shown.

Lastly, we need to handle when you click “Logout.” Spiffy UI will send a DELETE request with the token in its authorization header, so our Node server removes the token from its list of authorized tokens and sends back an “OK” response12.

Next steps – adding real security

This example accepts any username and password as valid. It works well for the example, but it isn’t very secure. The next step is adding a real token and connecting with a real security provider. This security scheme is an excellent fit for SAML tokens.

The stateless nature of the SAML security scheme scales well and works very well with the REST architecture of Spiffy UI’s tokenized identity. SAML is well supported by many security providers, but it’s not the only option. Spiffy UI supports any token type you want to use.

The client for every server

GWT is a great technology for rich web applications, but Java isn’t the right language for every server. When you put Spiffy UI in the front and REST in the middle the backend is any server that works for you. We’ve created Spiffy UI applications working against PHP, Erlang, and now Node.js. Spiffy UI will work with .NET, Python, or any application server you like.

Bess Siegal is a software engineer at NetIQ and a founding contributor to Spiffy UI. She enjoys her one-minute commute so she can spend more time with her husband and 3 daughters.

Nine months ago I posted a video about Our Spiffy UI showing the process we used for combining GWT, JQuery, and REST to make a new kind of GWT application. It was fast, it was beautiful, and you couldn’t use it. That last part has changed. The Spiffy UI framework is now open source.

Spiffy UI combines the best part of GWT and JQuery, adds on a layer of REST and security, and provides a comprehensive CSS framework to create amazing GWT applications. It is open source and 100% free.

We’re currently developing version 0.7.5. There’s also some amazing Spiffy UI articles on the way. There’s a lot of work to do and we need your help. We need you to try the samples, give us feedback, tell a friend, and build Spiffy applications. Join the Spiffy UI community.

Check out the framework at www.spiffyui.org and find out a better way to write GWT applications.

This bar is boring on a computer, but it comes alive on a mobile device. Grab your iPad or Android device and take a look.

Drag your finger and the items move with you. They follow your speed and keep your momentum. Play with it a little. I’ll wait.

The sliding touch panel only shows up on mobile platforms. With a mouse it feels clunky, but sliding with your finger just feels right.

This article shows you how to implement a sliding touch panel in JavaScript. jQuery is the only dependency of the touch slider. The rest is pure JavaScript and HTML. It runs fast, feels natural, and works on every mobile device with touch support.

It all starts with a grid

The sliding panel is a set of div tags: two containers and a div for each cell. The first step is laying them all out in a simple grid.

createSlidePanel: function(/*string*/ gridid, /*int*/ cellWidth, 
                           /*int*/ padding) {
    var x = padding;
    
    $(gridid).each(function() {
        $(this).css({
            'position': 'relative',
            'left': '0px'
        });
        
        $(this).parent().css('overflow', 'hidden');
        $(this).children('.cell').each(function() {
            $(this).css({
                width: cellWidth + 'px',
                height: '90%',
                position: 'absolute',
                left: x + 'px',
                top: padding + 'px'
            });

            x += cellWidth + padding;
        });

Each cell has a fixed width and padding and we lay them out in a single row. We set the overflow property on the container to hidden so we don’t get scroll bars on the grid.

All layout is based in CSS. The grid’s div tag has a position of relative so we can easily move it to the left and right. As the grid moves we adjust the left attribute in the CSS to position the grid. The panel container doesn’t show any overflow so only the cells in the middle are visible.

CSS easily adjusts the positioning with a single property change and the browser renders it quickly. This straightforward layout lets us quickly get to the fun part: touching it.

Make it touchable

There are three important events for touch support:

ontouchstart is called when you first press your finger onto the screen.

ontouchmove is called every time you move your finger on the screen.

ontouchend is when you take your finger off.

The default action for touching and moving in the browser is to scroll. By overriding this behavior we’ll allow the user to scroll our panel without moving the entire window.

This works well for our widget, but it can easily go bad. Overriding the default behavior is often defying the user’s expectations. If you aren’t clear about what’s happening it quickly becomes a bad user experience.

Event handling is a little tricky because we want to make sure the links and any other widgets within the cells still work. We just want the moving events.

The most interesting binding is ontouchend. This one will control if we follow the behavior of the widget that was clicked on or off the panel.

$(gridid).each(function() {
    this.ontouchend = function(e) {
        e.preventDefault();
        e.stopPropagation();
        
        if (touchslider.sliding) {
            touchslider.sliding = false;
            touchslider.touchEnd($(this), e);
            return false;
        } else {
            /*
               We never slid so we can just return true
               and perform the default touch end
             */
            return true;
        }
    };
    ...

The first line binds the event so we can respond to it. Then we have to figure out if we should allow the default behavior or not. This depends if we’re at the end of a slide or just a widget interaction.

We always prevent the default handling of the event. The default is never what we want here. Android will just scroll the screen, but iPads will hover a little magnifying class control that looks broken for our widget.

Touch the screen

The start of the touch is about recording data.

touchStart: function(/*JQuery* elem, /*event*/ e) {
     jsslide.startX = e.targetTouches[0].clientX;
     jsslide.startLeft = jsslide.getLeft(elem);
     jsslide.touchStartTime = new Date().getTime();
     
},

We record the location and the time the touch happened. The location is important since all touches are relative. The time helps us keep track of momentum.

Mobile devices make these panels feel realistic by adding momentum. It gives you the feeling that the panel has weight. If you drag it fast then it keeps going beyond your stopping point. This is the strange physics of mobile momentum.

In the real world force equals mass times acceleration. We need to figure out that force so we know how much extra to let the panel move when you’re not pushing it. Our fake acceleration is the distance you moved multiplied by the time you spent doing it. The start and end time of the touch motion give us that information. Our widget doesn’t have any real mass, so we fake it. That part comes later.

Move your finger

Once the touch is started we need to worry about moving events. The user could move their finger in any direction so we need to handle them both.

touchMove: function(/*JQuery*/ elem, /*event*/ e) {
     if (!touchslider.sliding) {
         elem.parent().addClass('sliding');
     }
     
     touchslider.sliding = true;
     

     if (jsslide.startX > e.targetTouches[0].clientX) {
         /*
          * Sliding to the left
          */
         elem.css("left", "-" + (jsslide.startX - e.targetTouches[0].clientX - 
                                 jsslide.startLeft) + "px");
         jsslide.slidingLeft = true;
     } else {
         /*
          * Sliding to the right
          */
         var left = (e.targetTouches[0].clientX - jsslide.startX + 
                     jsslide.startLeft);
         elem.css('left', left + 'px');
         jsslide.slidingLeft = false;
     }
}

All positions are negative since the panel starts with a left property of zero. Then we figure out what direction it’s moving in based on the current location and the start of the touch. We don’t need any jQuery animations here since the touch is moving fast enough to simulate movement. Adding any extra effects would just slow things down.

Stop touching the screen

The end of the touch is where things get really interesting. There are a number of different ways the touch could end and we have to handle each of them individually.

Using native transitions

At first I created this using JQuery animations. They worked well, but they were a little choppy. Miller Medeiros left an awesome comment about using WebKit transitions so I gave it a try. They worked really well. I restructued the code a little to work with WebKit transitions and it looks great.

We can handle all animations through a single doSlide function. It sets the left property and specifies the transform.

doSlide: function(/*jQuery*/ elem, /*int*/ x, /*string*/ duration) {
     elem.css({
         left: x + 'px',
         '-webkit-transition-property': 'left',
         '-webkit-transition-duration': duration
     });
}

The tranform property is left and we specify a duration for the transform to take. We need to unset these properties once we start the touch again so we don’t wait a long time for every transition while the touch is moving.

Did they drag too far

During the touch moving they could have dragged the bar before the beginning or after the end of the items. We let them do it so the widget seems responsive, but then give them a gentle reminder by sliding the bar back to the right place.

touchEnd: function(/*JQuery*/ elem, /*event*/ e) {
     if (jsslide.getLeft(elem) > 0) {
         /*
          * This means they dragged to the right past the first item
          */
         touchslider.doSlide(elem, 0, '0.5s');
         elem.parent().removeClass('sliding');
         jsslide.startX = null;
     } 

If they drag to the right past the first item then our panel will be left floating with a large space on the left. In that case we’ll slide it back into place.

Dragging left past the last item works in a similar way. We animate the panel back into place so there isn’t any extra space on the right side.

Slide momentum

When the user slides in the middle we need to consider their slide momentum. This tells us how much farther we should push the panel once the touch ends. If they do a short slow drag then the panel shouldn’t move much extra. If they do a long fast drag then we want a large extra slide. The momentum allows the user to easily make big jumps in the slider without having to perform multiple slides.

Calculating the slide momentum is a little tricky. We need to consider the distance of the slide and how long it took.

slideMomentum: function(/*jQuery*/ elem, /*event*/ e) {
     var slideAdjust = (new Date().getTime() - jsslide.touchStartTime) * 10;
     var left = jsslide.getLeft(elem);
     
     var changeX = 12000 * (Math.abs(touchslider.startLeft) - Math.abs(left));
         
     slideAdjust = Math.round(changeX / slideAdjust);
     
     var newLeft = slideAdjust + left;
     
     /*
      * We need to calculate the closest column so we can figure out
      * where to snap the grid to.
      */
     var t = newLeft % touchslider.colWidth;
     
     if ((Math.abs(t)) > ((touchslider.colWidth / 2))) {
         /*
          * Show the next cell
          */
         newLeft -= (touchslider.colWidth - Math.abs(t));
     } else {
         /*
          * Stay on the current cell
          */
         newLeft -= t;
     }
     
     /*
      * Next we'll slide the panel...
      */

To start we need to know how long the slide took. We’ll get this number in milliseconds. Then we need to know the current location of the panel.

Next we need to know how far they slid: the difference between the absolute values of the position when the slide started and the position when it ends. Then we multiply that by a magic number.

The number of milliseconds the user was actively sliding could be very large, easily over 10,000. The amount they moved will be a pretty small number, typically under 1,000. We have to adjust the time to make it feel like the panel has real weight. There’s some solid math behind why I chose 12,000, but in the end it just makes it feel right.

We divide these two numbers and get the slideAdjust value. Then we apply it to the position of the panel depending on the movement to the left or the right. Now we just need to adjust the panel so they match our grid.

Once we’ve moved the panel, if we’re still in the bounds of the grid, then we want to snap the item to the left-hand side of the grid. This is the process of sliding the grid to the left or the right so there is a whole cell showing on the left side.

We calculated the width of each column when we did our first grid layout. Now we figure out of the panel is closer to the start of the cell or the end of it and adjust accordingly.

This is all ridiculous

I’m giving you a little gold star for making it this far . This article is packed full of math and low-level UI programming. This widget does the kind of work you often find in physics engines just so it can show a simple menu. That’s a telltale sign you’re too far out on the bleeding edge.

I could write a native app to do this. IOS and Android both have horizonal slide view widgets. They did the work for me. It would be easier, but native apps lock you in. There’s no way to write a native application for multiple mobile platforms, but you can make your web application look and feel like a native app.

The only solution for cross-platform mobile applications is HTML and JavaScript. That won’t change for at least the next couple of years. Some applications will always require native code, but most of them could be HTML and JavaScript. The environment isn’t as nice, but the cross-platform support is amazing.

Debugging JavaScript on mobile devices

There are some really nice tools for mobile development. XCode is at the top of my list. HTML doesn’t give you anything close to that level of support, but you can get a nice console.

I define a new function named output:

output: function(/*string*/ msg) {
    if (console) {
        console.info(msg);
    }
}

It prints to the console when it’s available. Safari on the iPad and iPhone have options to enable the console under the settings panel. Android does it a little better.

If I plug my Android device into the USB port of my computer and launch the Android SDK Dalvik Debug Monitor I can see a log of everything happening on my Android.

Browser logs are tagged with the word browser. That makes it pretty easy to find them. This interface isn’t pretty, but it works well and I don’t have to switch windows.

This new mobile world is strange, but mobile web applications are a big part of it. They look good, run fast, and aren’t that hard to work with.

Image credits

The images in this slider were provided by the Apple marketing department, the Android marketing department, iStockPhoto, Fir0002, Bff, Gentaur, and doug8888.

New software projects need to get off the ground. If 1.0 isn’t a success forget about 2.0. You move fast, change direction often, and don’t worry too much about the details.

If you’re lucky version 1 leads to 2 and 3 and 4. A few years pass and you’ve built up a customer base. People like the product, your job is secure, life is good. And you have a big problem.

Everything you did to push 1.0 out the door is coming back to haunt you. The code is full of spaghetti nobody wants to touch and development becomes a series of frustrated meetings where everyone asks, “how can that simple feature possibly take so long?” You have so much legacy code you can’t make any big changes. Your nimble product has turned into an aircraft carrier.

At first it’s hard to tell you’re in trouble. Sure there are a few rough patches, but all software has warts. You made it this far, you must be doing something right.

Then some of your old engineers leave the project. New ones join. If you’re lucky the new ones tell you you’re in a hole. You can dig out, but it takes time, effort, and a lot of money.

I’ve seen this process enough times to know it’s avoidable. It just takes planning for the future at a time when everyone around you wants to focus on today. That’s why I use Sonar and Checkstyle on all my new Java projects.

Sonar and Checkstyle are static analysis tools that look through your code for bugs and formatting issues. They’ll tell you if you assigned a variable to itself or put your curly-braces on the wrong line. Code checking tools make your development time shorter and get rid of annoying little bugs, but it’s always hard to sell them to your team.

These tools feel like they make you go slower. Maybe you know it’s good for you, but nobody likes being told to eat their vegetables.

Style tools are also the source of religious wars between programmers. Where should your curly-braces go? What is the right way to name your methods? How many lines before a class is too long? There’s no right answer to these questions, but there are consistent answers.

I want to share with you the way we use these tools, the rules we think are important, and how we convince new teams to use them.

Curly-braces

The curly-brace debates have been going on since we started writing ALGOL in 1968. Probably before that. So what looks better to you?

if (foo)
{
    doStuff();
}

if (foo) {
    doStuff();
}

One of them is more compact, the other one easier to line up. Which is the right way? There isn’t one. We’ve debated this issue for over 40 years because there’s no compelling argument either way.

We force curly-braces on the same line, but I can’t tell you why. I can say that keeping them consistent makes our code easier to read. Try switching back and forth too often and you’ll get lost.

No tabs

Using tab characters is another religious debate. Some people love tabs, others hate them. We ban them. We add hooks so you can’t check in files with tabs.

Tabs mostly cause us trouble because of our very mixed development environment. Our developers work on Windows, Linux, and Mac because we ship products on all of those platforms. Moving from one to the other means most developers use different editors.

Some editors make tabs eight spaces and some make them four. Most editors can show you correct indentation if you have one or the other, but mix them up and even the best editors get confused.

We indent four spaces and ban tabs. This is another area where the code consistency pays off.

Member names

We force all member names to start with m_. Let me show you why with an example. Can you spot the bug here:

public class User {
    private String firstName;
    private String lastName;
    private String email;
    private String telephone;

    public User(String strfName, String strlName,
                String strEmail, String strTelephone) {
        this.firstName = strfName;
        this.lastName = strlName;
        this.email = email;
        this.telephone = strTelephone;
    }
}

This simple class has a very common bug. Did you find it yet? Take another minute.

The variable email will never be assigned. Someone might depend on it being there and get a NullPointerException. Worst of all it will become a run-time exception.

Run-time exceptions are scary. They happen unpredictably and it’s easy to miss them in testing. We always try to turn run-time exceptions into compile-time exceptions. Those are easy to find and rarely cause problems for customers. As long as you have an automated build the chances of shipping a with a compile error are minuscule.

File length

Almost everyone can agree that a 500 line source file is fine and 10,000 lines is too long, but there are a lot of opinions in between. We limit our file lengths to 2,000 lines. There isn’t a really good reason for that number. It could have been 1,500 or 2,500. The key is choosing a length and sticking to it.

You may have a really good reason for making your file giant, but most of the time it turns into a 5,000 line monster. Too big to easily document and too complex to maintain.

JavaDoc

When I started programming I was against JavaDoc. It seemed like a crutch. I thought code should be readable without documentation. I still believe that, but there are some things your code can never say.

The code will never tell another programmer what your intention was. Is that missing block a bug, a feature you haven’t implemented, or there for a reason? The programmer’s intention is very important. The code is the implementation, but not the plan.

The biggest advantage of good comments is that they enable refactoring. The comments make it much easier for another developer to change something if they know how it was meant to work in the first place.

We require that all public, protected, or package private methods have JavaDoc which includes every argument and every declared exception. If you skip JavaDoc then you get a Checkstyle warning.

No @author tags

Speaking of JavaDoc, we ban @author tags in our code. I never liked these tags, but it was Karl Fogel who first explained to me what I didn’t like. Karl is a founding member of the Subversion project where they also ban author tags. For him it comes down to the bus factor.

The bus factor is the answer to a simple question, “how many people would need to get hit by a bus before nobody understands this code?” You want the number high and @author tags drive it lower.

The @author tag is a signpost telling everyone else to stay away. It creates an ownership mentality of a single class. Normally ownership mentality is great. When every developer feels like they own the product it drives quality up and fuels the passion that leads to inspiration.

The problem comes when you feel like the exclusive owner. Then your bus factor stays at one. If you leave the project it goes to zero. We encourage everyone to look at every part of the code base and banning @author tags helps us do it.

Spacing

This is one more issue with no right answer. What feels better to you?

String s[]=getMyStrings();
for(int i=0;i<s.length;i++)
{
    System.out.println(s[i]);
}

String s[] = getMyStrings();
for (int i = 0; i < s.length; i++)
{
    System.out.println(s[i]);
}

You might ask why put the space before the parenthesis and not after or why spaces around the plus sign but not the semi-colon. There isn’t a right answer. We chose this because it was the Sun Java coding standard, but the key is consistency.

Cyclomatic complexity

Spaghetti code is about more than just the code formatting. Methods that are too complex to understand are too complex to debug.

Complexity is easy to add. One developer adds a slightly complex method and then another adds one more condition. Then you need a special case for one more condition. And one more. Go through a couple of iterations and your code path is a maze of back alleys and dead ends.

Labyrinthine code is a sanctuary for bugs, but it’s something worse. Complex code is immovable code. Bringing new developers up to speed takes months and even the experienced ones can’t move the project very far.

The most dangerous part is that complex code is easy to ignore. You’ll fix it someday, but someday never comes. This technical debt drags your project down.

Sonar analyzes cyclomatic complexity and moves the complex code argument from opinion to fact. You choose how much complexity you can live with and warn programmers when their code complexity gets too high.

We set our cyclomatic complexity maximum at seven. That’s enough code paths for a few if statements with a couple of while loops thrown in. Anything more and it should be a separate method.

Bugs

So far we’ve talked mostly about formatting issues. They often lead to bugs, but they might not be bugs yet. Now let’s look at a few of the real bugs Sonar finds in most projects.

Empty if or else statements

boolean b = getMyBoolean();
if (b) {
    return;
} else {
}

What did the programmer who wrote this mean? Is it a copy and paste error or a real bug? Did they just forget to add code to that else statement? This leads to confusion, bad code, and technical debt. We don’t allow it.

Equals without hash code

public class User
{
    private String m_name;

    public User(String name)
    {
        m_name = name;
    }

    @Override
    public boolean equals(Object o)
    {
        return m_name.equals(o);
    }
}

This one comes from the excellent Effective Java by Joshua Block. The Java uses the hashcode and equals methods together in many of the collection classes. Overriding one without the other is always a bad idea.

Catching NullPointerException

try {
    myRiskyMethod();
} catch (NullPointerException npe) {
    // No need to do anything here
}

Ever seen code like this? I know programmers that talk about code smell and this code smells like a wet dog fresh from the compost pile.

This code gives more questions than answers. Why is this method risky? What does it mean if it throws a NullPointerException? Why couldn’t you handle it properly in the first place?

Leave this in your code and you’re a lazy programmer.

Unused locale variables, private methods, and formal parameters

If your method takes three arguments you better use them. If you don’t then why did you write it that way. What did you mean? Did you just forget or is this a bug?

Sonar plus Checkstyle gives us hundreds of checks and we try to fix all of them. I make Checkstyle warnings build errors to force programmers to fix all of them. I do it because fixing the warnings is faster than not fixing them.

Digging your way out

Using Checkstyle and Sonar for a new project is relatively easy. Choose the rules you want to enforce and make the build break if they aren’t followed. Your project will stay at zero warnings forever.

The hard part is existing projects. The first time you run the tools they’ll give you thousands, probably tens of thousands, of warnings. The sheer magnitude of them is overwhelming. I’ve seen many projects run their first report and never look at Checkstyle or Sonar again. These errors are worth fixing and don’t take as long as you’d think. The way forward is a simple process of tools, segregation, and persistence.

Use the tools

There are many products and open source projects that will fix up formatting errors in Java code. They can analyze your code and apply your style guidelines. The best one I’ve found is Eclipse.

Eclipse will format an entire project with a single click. It takes a little while on large projects, but you can run it overnight. The Eclipse code formatter will fix thousands of errors at once. The problem becomes much more tractable with all the simple formatting issues out of the way.

Segregate the code

It’s much easier to stay at zero warnings than 100. 100 and 101 warnings look identical, but the different between zero and one is staggering. Leave 100 warnings and pretty soon the number will creep up.

Segregating your code is the easiest way to get to zero. If you’re starting a new module check it separately from the rest. Keep that part at zero and then work on some of the others. Segregation makes modules easier to test and gives you more manageable goals. Maybe you can fix one module per month.

Persist

You don’t have to fix every error in a day. Slow and steady progress will improve your code quality over time. Just keep at it.

We often assign a special portion of each development effort to fixing these errors. Every developer devotes a little time to it and slowly works the number of warnings down.

The true cost of technical debt

You’ll never lose a sale because your curly-braces are on the wrong line or your files have tabs. You will lose customers because of missing features, unstable software, and a bad reputation. Spending your limited time adding features is a good thing. That makes these warnings seem trivial, but fixing these warnings will save you time.

Every Sonar or Checkstyle warning is a small bit of technical debt. They cause bugs, make your code more difficult to maintain, and turn your product into spaghetti code that nobody wants to work with. One or two don’t matter, but pile up hundreds and you’re in trouble.

These warnings are the issues you shouldn’t waste time on. They’re the NullPointerException you spend a day tracking down and the bad formatting that costs you an extra hour understanding the code. Let the tools find these problems so you can focus on the important features of your product.

Good software comes from distance. It’s only when you can step back and see the forest from the trees that you make the hard decisions and design the features your customers really need. If you spend all of your time putting out fires you’ll never get to the fun and profit.

Today my wonderful and amazing colleague Bess Siegal dropped by to talk with me about wrapping JQuery controls in GWT.  You might remember Bess from her last article, Creating A Multi-Valued Auto-Complete Field Using GWT SuggestBox And REST.

JavaScript can dynamically zoom photos, develop mobile applications, and create complex animations without flash.  And GWT can’t.  Well… not easily.  

There’s a world of JQuery plugins you can use easily and safely in your GWT project.  All it takes is a little planning and a little practice.  

This article walks you through creating a GWT wrapper for the JQuery UI Slider which has more features, testing, and customizability than any slider available in GWT.

Importing JQuery libraries

We’ll start by adding a few libraries.  Download the minified files for JQuery and JQuery UI and add them to your WAR.  Then reference them in your HTML file like this:

<link media="all" type="text/css" href="jquery-ui.css" rel="stylesheet"> 
<script src="jquery-1.4.4.min.js" type="text/javascript" charset="utf-8"></script> 
<script src="jquery-ui.min.js" type="text/javascript" charset="utf-8"></script> 

You can also have Google host them for you like this:

<link media="all" type="text/css" 
        href="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8.6/themes/base/jquery-ui.css" rel="stylesheet"> 
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js" 
        type="text/javascript" charset="utf-8"></script> 
<script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.8.6/jquery-ui.min.js" 
        type="text/javascript" charset="utf-8"></script> 

Let’s add some code

Now that you’ve imported the JQuery libraries, let’s start using them.  The JQuery UI Slider attaches to a DIV element in your page so our GWT Slider wrapper extends Widget.  

Picking the correct base class is an important part of creating a fully featured GWT control.  Our slider is just a DIV.  If your control uses a text field you could extend TextBox or any other GWT widget.

public class Slider extends Widget
    
    /**
     * Create a slider with the specified ID.  The ID is required
     * because the slider needs a specific ID to connect to.
     * @param id - id of the element to create
     * @param options - JSONObject of any possible option, can be null 
     *                  for defaults
     */
    public Slider(String id, JSONObject options)
    {           
        super();
        Element divEle = DOM.createDiv();
        setElement(divEle);
        divEle.setId(id); 
        
        m_defaultOptions = options;
        if (m_defaultOptions == null) {
            m_defaultOptions = getOptions(0, 100, new int[]{0});
        }        
    }

A DIV element is created and set as the element in the constructor 1.

Extending widget works well for the Slider, but it isn’t always the best choice.  When we wrapped the JQuery UI Date Picker we used TextBox as our base class.  Choosing the right base class let’s your JQuery wrapper act like a first class GWT widget.

Getting your slider’s options

getOptions2 is a static method to assist in creating the JSONObject
of options.  

    
    /**
     * A convenient way to create an options JSONObject.  Use SliderOption 
     * for keys.
     *
     * @param min - default minimum of the slider
     * @param max - default maximum of the slider
     * @param defaultValues - default points of each anchor
     * @return a JSONObject of Slider options
     */
    public static JSONObject getOptions(int min, int max, int[] defaultValues) 
    {
        JSONObject options = new JSONObject();
        options.put(SliderOption.MIN.toString(), new JSONNumber(min));
        options.put(SliderOption.MAX.toString(), new JSONNumber(max));
        JSONArray vals = intArrayToJSONArray(defaultValues);
        options.put(SliderOption.VALUES.toString(), vals);
        return options;
    }

    private static JSONArray intArrayToJSONArray(int[] values)
    {
        JSONArray vals = new JSONArray(); 
        for (int i = 0, len = values.length; i < len; i++) {
            vals.set(i, new JSONNumber(values[i]));
        }
        return vals;
    }

More options

There are also other constructors for the most common parameter options set during initialization. 

/**
 * Create a slider with the specified ID.  The ID is required
 * because the slider needs a specific ID to connect to.
 * @param id - id of the element
 * @param min - default minimum of the slider
 * @param max - default maximum of the slider
 * @param defaultValue - default point of a single anchor
 */
public Slider(String id, int min, int max, int defaultValue)
{
    this(id, min, max, new int[]{defaultValue});
}
    
/**
 * Create a slider with the specified ID.  The ID is required
 * because the slider needs a specific ID to connect to.
 * @param id - id of the element
 * @param min - default minimum of the slider
 * @param max - default maximum of the slider
 * @param defaultValues - default points of each anchor
 */
public Slider(String id, int min, int max, int[] defaultValues)
{           
    this(id, getOptions(min, max, defaultValues));
}

The SliderOption enumeration helps with additional slider options.  The Javadoc comments for each option is copied directly from JQuery UI Slider documentation.

Initialization

Constructing your GWT object is only the first step.  You also have to bind it to JQuery4 with the JavaScript Native Interface.  The best place to do this is the onLoad method.

We need this method because GWT causes a timing problem.  With a regular JQuery page you would just call the binding when your page loads.  GWT uses a delayed loading mechanism which loads the correct GWT code for your browser and language.  The onLoad3 method gives us a good place to bind to JQuery after our GWT object has been loaded into the page.

    @Override
    protected void onLoad()
    {
        if (m_defaultOptions == null) {
            m_defaultOptions = new JSONObject();
        }
        
        createSliderJS(this, getElement().getId(), m_defaultOptions.getJavaScriptObject());
        super.onLoad();
    }
    
    private native void createSliderJS(Slider x, String id, JavaScriptObject options) /*-{
        options.start = function(event, ui) {
            x.@com.example.slider.client.widget.slider.Slider::fireOnStartEvent(Lcom/google/gwt/user/client/Event;Lcom/google/gwt/core/client/JsArrayInteger;)(event, ui.values);
        };
        options.slide = function(event, ui) {
            return x.@com.example.slider.client.widget.slider.Slider::fireOnSlideEvent(Lcom/google/gwt/user/client/Event;Lcom/google/gwt/core/client/JsArrayInteger;)(event, ui.values);
        };
        options.change = function(event, ui) {
            var has = event.originalEvent ? true : false;
            x.@com.example.slider.client.widget.slider.Slider::fireOnChangeEvent(Lcom/google/gwt/user/client/Event;Lcom/google/gwt/core/client/JsArrayInteger;Z)(event, ui.values, has);                
        };
        options.stop = function(event, ui) {
            x.@com.example.slider.client.widget.slider.Slider::fireOnStopEvent(Lcom/google/gwt/user/client/Event;Lcom/google/gwt/core/client/JsArrayInteger;)(event, ui.values);
        };
        
        $wnd.$("#" + id).slider(options);
    }-*/;
    

In addition to the options set in the constructor, the createSliderJS method also maps the slider’s events to corresponding fireOnXEvent Java methods using the GWT technique for passing JavaScript values into Java code.  The values we pass are the native event and the values selected by the slider. 5.  Thus we have our cornerstone for event handling.

Event handling

When we’re done with our Slider it will look just like a standard GWT widget from the outside.  That way we can switch implementations and never worry about our choice of JavaScript library leaking out to other code in our project.  We’ll continue that strong encapsulation by creating a SliderEvent object and SliderListener interface to allow other code to get events from the Slider.

    private void fireOnStartEvent(Event evt, JsArrayInteger values)
    {
        int[] vals = jsArrayIntegerToIntArray(values);
        SliderEvent e = new SliderEvent(evt, this, vals);
        
        for (SliderListener l : m_listeners) {
            l.onStart(e);
        }
    }
    
    private boolean fireOnSlideEvent(Event evt, JsArrayInteger values)
    {
        int[] vals = jsArrayIntegerToIntArray(values);
        SliderEvent e = new SliderEvent(evt, this, vals);
        
        for (SliderListener l : m_listeners) {
            l.onStart(e);
        }
        
        boolean ret = true;
        
        for (SliderListener l : m_listeners) {
            if (!l.onSlide(e)) {
                //if any of the listeners returns false, return false,
                //but let them all do their thing
                ret = false;
            }
        }
        
        return ret;
    }
    
    private void fireOnChangeEvent(Event evt, JsArrayInteger values, 
                                   boolean hasOriginalEvent)
    {
        int[] vals = jsArrayIntegerToIntArray(values);        
        SliderEvent e = new SliderEvent(evt, this, vals, hasOriginalEvent);
        
        for (SliderListener l : m_listeners) {
            l.onChange(e);
        }
    }
    
    private void fireOnStopEvent(Event evt, JsArrayInteger values)
    {
        int[] vals = jsArrayIntegerToIntArray(values);
        SliderEvent e = new SliderEvent(evt, this, vals);
        
        for (SliderListener l : m_listeners) {
            l.onStop(e);
        }
    }

Each fire event method notifies all listeners and passes the native event and an int[] of values. The onSlide event allows for cancellation of the action by returning false6.  

Changing options after initialization

You may change a slider’s options after initialization.  There are get/setIntOption, get/setBooleanOption and get/setStringOption methods to maintain type-safety.  Each of these methods calls a corresponding JSNI method to get or set the option.  Getting and setting the slider’s values is a little different, so they have their own methods.

    /**
     * Convenience method for only 1 anchor
     * @return Returns the value.
     */
    public int getValue()
    {
        return getValueAtIndex(0);
    }
    
    /**
     * Sets the value of each anchor
     * @param values - int array of values
     */
    public void setValues(int[] values)
    {
        JSONArray vals = intArrayToJSONArray(values);
        setValuesJS(getElement().getId(), vals.getJavaScriptObject());
    } 
        
    /**
     * Gets the value of a anchor at the specified index
     * 
     * @param index  the index to retrieve the value for
     * 
     * @return the value
     */
    public int getValueAtIndex(int index)
    {
        return getValueJS(getElement().getId(), index);
    }
    
    
    private native void setValuesJS(String id, JavaScriptObject values) /*-{
        $wnd.$("#" + id).slider("option", "values", values);
    }-*/;
    
    
    private native int getValueJS(String id, int index) /*-{
        return $wnd.$("#" + id).slider("values", index);
    }-*/;

Extending the Slider

Because a slider that uses the range option is unique in that the values are limited to 2, a RangeSlider subclass was created to only allow get and set of 2 values.  You could extend the slider for any of the specific options required by your application.

Cleanup

The widget will cleanup after itself by calling destroy on the slider during onUnload, which is called immediately before a widget will be detached from the browser’s document.

    @Override
    protected void onUnload()
    {
        destroySliderJS(this, getElement().getId());
        super.onUnload();        
    }
    
    private native void destroySliderJS(Slider x, String id) /*-{
        $wnd.$("#" + id).slider("destroy");
    }-*/;

The Takeaway

For our web application projects at Novell, we like to use GWT for maintainability.  For all GWT’s benefits, we understand that it’s standard widgets are limited, especially when compared to its corresponding JQuery widget.  Fortunately, we’ve developed a repeatable method for wrapping JQuery UI controls, and we hope you can employ it with this slider as an example.  You may also feel free to use the slider code in your application.  Either way, please let us know if you do.

The code in this example is free and released under the Apache 2.0 license. The other programs needed to run this example are also free, but some of them may use different licenses. Make sure to read and understand each license before using a tool.

Bess Siegal is a software engineer at Novell.  She enjoys her one-minute commute so she can spend more time with her husband and 3 daughters.

My view of GWT is changing. When I wrote 5 GWT Anti-Patterns I saw it as the framework controlling my entire application. Now it’s my glue.

GWT is a wonderful foundation holding together the different parts of your application. It can grow and expand to new technologies and uses we haven’t thought of yet, but it can also hold us back. You can get stuck in GWT and never find your way out.

Each of these four anti-patterns addresses different ways to write code you wish you hadn’t. The solutions are all about opening doors instead of closing them.

1. GWT RPC

GWT RPC is the sexiest feature of the entire toolkit. Making AJAX simple lets you program for the web like it was a desktop. Don’t worry about remote communications or networks, GWT RPC takes care of that for you.

The problem

GWT RPC generates the network calls for you and automatically marshals Java objects between the browser and the server, but that ease of use comes at a cost.

It isn’t that easy. GWT RPC requires you to manage two interfaces plus the client-side calling code and a servlet to make it all work.

Error handling is hard. Network programming is the art of error handling. Networks are unpredictable and abstracting that away makes it much harder to respond well when something doesn’t go right.

You can’t tell what’s going on. Try debugging your GWT RPC through a network tool like Wireshark or HTTPFox. All the ease of debugging your Java by looking at the byte code.

It’s slow. GWT RPC adds a lot of overhead to the request, but that isn’t the worst part. When you think of remote procedure calls as free you make a lot of them. That’s the recipe for an application that loads in minutes instead of seconds.

The solution

Use REST. I’ve written patterns for using REST from GWT. There are also some good built-in features and third-party plugins to support it. REST looks daunting at first, but it isn’t that bad.

REST is everything GWT RPC isn’t: fast, easy to debug, and simple. It also does more.

REST forces you to build an API. GWT RPC makes everything look like the same program so you rarely create a solid API. With REST you have to. APIs make your code better even if nobody else ever calls them.

REST supports automated testing. Once you have a REST API you can test it without worrying about the client. I’ve written test suites in Ruby just to make sure I had good coverage.

REST decouples the client and server. Imagine shipping a new version of your GWT client without changing your server. You could fix bugs and not worry about destabilizing other parts of your code. You could even write a GWT client for a server written in a different language like we did when we created a multi-value auto-complete field with GWT and REST. That article has source code of a GWT application that calls to a Java servlet or PHP using REST.

2. Securing your GWT application

I sleep peacefully at night knowing my applications are secure. So do my customers.

GWT doesn’t solve the security problem for you so you might be tempted to put it all behind a firewall, password, or Spring framework and get perfect security. Perfect security isn’t perfect.

The problem

It’s easy to put your entire GWT application behind a secure framework. Require a login before you can even download the HTML. You feel happy knowing the bad guys can’t see your JavaScript, HTML, or CSS, but securing everything makes your application less secure.

The solution

In the end GWT is just a web page. People download, run it, and maybe view the source. Let them. Don’t secure any of the files that GWT generates and don’t put secure information in your source code.

Secure your data, not your code. It doesn’t matter if you’re using GWT RPC, REST, or anything else, you’re just exposing URLs with data. That’s the right place to put your security.

Create a single path, put all of your data behind it, and secure it with a servlet filter. You can make this path something like /data so your URLs look like /data/users or /data/roles. That simple path is easy to secure and easy to test.

You can even go a step further and move the code serving secure data into a separate WAR file. That avoids many accidental security problems.

Securing just your data makes your server easier to write and test. It also helps your browser code. Don’t make login a separate step in your application. Add a single point in your client for login and make it part of your GWT application.

3. Using only GWT

GWT is an insular environment. It separates you from JavaScript and can cut you off from a world of innovations and well tested software.

The problem

There are many frameworks that wrap existing JavaScript code. They work well, but they’re little more than a drop in the bucket. GWT is a great project, but it can’t keep up with the rest of the Internet.

The solution

Wrap existing third-party Javascript with GWT. For example, GWT doesn’t have a progress bar control and JQuery UI has a really nice one. Wrapping the JQuery UI progress bar is easy. Here’s all the code you need:

import com.google.gwt.user.client.ui.SimplePanel;

public class ProgressBar extends SimplePanel
{
    private int m_value = 0;

    public ProgressBar(String id)
    {
        getElement().setId(id);
    }

    @Override
    public void onAttach()
    {
        super.onAttach();
        addProgressBarJS(getElement().getId(), m_value);
    }

    public int getValue()
    {
        return m_value;
    }

    public void setValue(int value)
    {
        m_value = value;
        setValueJS(getElement().getId(), m_value);
    }

    private static native void setValueJS(String id, int barValue) /*-{
        $wnd.$('#' + id).progressbar('destroy');
        $wnd.$('#' + id).progressbar({
            value: barValue
        });
    }-*/;

    private static native void addProgressBarJS(String id, int barValue) /*-{
        $wnd.$("#" + id).progressbar({
            value: barValue
        });
    }-*/;
}

That’s it. Add JQuery and JQuery UI to your GWT HTML page, include the JavaScript files in your WAR, and write 42 lines of code. Now you have access to the JQuery progress bar in GWT and you’ve added strong typing to the control.

Don’t like the JQuery progress bar? Wrap someone else’s. You can always change your mind later, since none of the calling classes know you’re using it. I’ve wrapped the progress bar, the date picker, and half a dozen third-party JavaScript controls.

4. Using GWT for layout

We all know the evils of FlexTable, but we need to go further. The layout technology of the web is CSS.

The problem

GWT provides FlexTable, DockLayoutPanel, VerticalPanel, and many others to do layout in HTML. They put the layout in your code and make GWT feel a lot like Swing. So why shouldn’t you use them?

They’re ugly. CSS isn’t just for aesthetes. Look at any big professional website – Google, Amazon, Facebook – they all live and breathe CSS. Without it you can’t really control or customize how your application looks.

You have to recompile. Needing to recompile for every pixel you change hurts your productivity. It also means your customers can’t customize your application after you’re done with it.

You can’t use Firebug. All user interfaces require tweaking and Firebug lets you do it live. Stick with HTML layouts and you’re poking around in the dark hoping your changes are OK.

The solution

Put all of your layout in CSS. This was one of our fundamental rules on my last project. Assign classes to your elements, write tags first GWT, and make a professional application.

Conclusion

Our understanding of good on the web is changing. Just working isn’t enough anymore. Good applications run fast, look professional, and are easy to use. Most of these anti-patterns are advanced. They represent subtle new ways of thinking about GWT. Patterns at this level are a sign of maturing technology and our maturing understanding of it.

Update: The Spiffy UI Framework mentioned in this presentation is now open source. Check it out at http://www.spiffyui.org.

I’ve been working on a new project called The Novell Identity Manager Reporting Module. It generates comprehensive reports about identity data in very large organizations. It was also a chance to build a new web application from the ground up.

Official product names take a long time so within our group this project was known as Our Spiffy Reporting Tool. It represents many new directions and innovations for web application UI. It’s the application of some new philosophies. We integrated fluid grids and vertical rhythm, called all of our APIs using REST from GWT, and created a new auto-complete multi-valued suggest box.

This presentation also shows some of my personal transformation from desktop programming snob to a happy web application developer.

Here’s Our Spiffy UI:

This presentation was given in the browser with JQuery. It’s all open source and you can see the slides online.

Writing a WordPress plugin is inspiration, perspiration, testing, guess work, and frustration. You spend hours making your plugin just right, but you never know if it is just right. You hear from some of the happy users and none of the unhappy ones. This guess work leads to assumptions we can’t back up.

The team from Stresslimit Design and I have been working on the WordPress Editorial Calendar for months, but we have no real idea how people use it. How many weeks are people looking at in the calendar? How big are there screens? How many posts do they have per day? We need the answers to design the plugin, but we’re just fumbling through the dark.

With version 0.9 of the calendar we’re trying to turn on the light.

Why we’re collecting data

WordPress plugins go out into the wild and don’t phone home. You get a simple plugin statistics page, but never find out who’s using your plugin, how they’re using it, or even if they installed it after downloading. As a privacy nut I like that, but it makes my life as a designer difficult.

The editorial calendar is getting close to version 1.0 and we’re trying to refine our interface. Make those little tweaks that take it from good to great. We started with a simple question, how many weeks should we show on the calendar by default? I rarely post more than once a day and my 24-inch monitor stretches on like the Montana prairie so I want as many weeks as possible. I could even go up to eight or nine.

Nine weeks is the perfect answer for me, but it isn’t the right answer. Most users are stuck in Manhattan apartment sized screens and can’t see nine weeks with a magnifying glass. Well… that’s what I think, but I don’t really know. If I had real data on people’s window sizes I could make the right choice and make the calendar that much better.

That’s why we’re tracking data with this plugin. To make it work better. That’s most of the reason. We also want to know how many people are really using it.

Always make it opt-in

WordPress plugins have a gigantic amount of power. They can delete your data, steal your passwords, and hack your blog. When you install a plugin you’re saying I trust this plugin to not be evil. That’s a lot of trust and the Editorial Calendar has to earn it.

We could collect data automatically, but that’s evil. Instead we make all data collection opt-in. Users can very clearly see everything we collect and have to click the button before we collect anything.

How it works

The data collection is based on Mint. I already used Mint to track statistics for my own site. Mint is a more configurable and better looking competitor to Google Analytics. It also lets me hold onto my data instead of sending it to Google.

Normally Mint is part of your website with a simple declaration like <script src="/mint/?js" type="text/javascript"></script>. This causes the Mint JavaScript to get downloaded, collect information about the browser, and call back to the server without visitors ever knowing.

This type of website data collection is ubiquitous. Every major site does it and the total volume of personal information they collect is a little scary. My privacy rant is coming up in a little while.

Mint made collecting data from the Editorial Calendar pretty easy. It just takes a few lines of JavaScript to get Mint onto the Calendar page:

jQuery.getScript('http://www.zackgrossbart.com/edcal/mint/?js', function() {
    edcal.saveFeedbackPref();
});

Now I can dynamically load the mint JavaScript files and save the preference of that when it’s done. The dynamic loading is important because I don’t want to collect data every time and automatic data collection is way too scary. Right now we prompt the user to let us collect data after they’ve loaded the calendar three times, and we never collect any data until we get permission.

Peppers

Mint collects data about how people came to your site like who they were referred by and what terms they searched for to get there. It also collects information about the environment like what browser they’re running and if they have Flash. I needed data more specific to the calendar like how many weeks are people seeing and how many posts do they have per day. For that I needed to write a Pepper.

Peppers are the way you extend the capabilities of Mint. I love puns. They’re written in PHP and JavaScript and collect or display extra data. There are Peppers to tell you how big someone’s browser window is or who has a secret crush on your website. My Pepper collects data about the calendar.

This Pepper is open source and like the rest of the code on this blog it is released under the Apache License, Version 2.0. That means you can copy it, change it, or use it for free.

Setting up our Pepper

The Editorial Calendar Stats Pepper starts with a PHP file called class.php and a big comment.

<?php
/**************************************************
 Pepper
 
 Developer      : Zack Grossbart
 Plug-in Name   : Edcal Stats
 
 **************************************************/

 
$installPepper = "SI_EdcalStats";
    
class SI_EdcalStats extends Pepper
{
    var $version    = 1; // Displays as 0.01
    var $info       = array
    (
        'pepperName'    => 'Editorial Calendar Stats',
        'pepperUrl'     => 'http://www.zackgrossbart.com',
        'pepperDesc'    => 'Editorial Calendar Pepper',
        'developerName' => 'Zack Grossbart',
        'developerUrl'  => 'http://www.zackgrossbart.com'
    );

The $info array sets up our Pepper and gives us the basics; a title and description. With this class we define the functionality and feel of the Pepper using a special set of variables. We start by defining the panes we’ll show on the statistics page.

Defining our panes

var $panes = array
(
    'Editorial Calendar Stats' => array
    (
        'Stats'
    )
);

The Editorial Calendar Stats Pepper just has one pane where it shows the Stats for the calendar plugin. This makes our $panes array very simple.

Collecting data

The next step is to define the data we want to collect and where we’ll store it in the database.

var $manifest = array1
(
    'visit'    => array
    (
        'edcal_weeks' => "SMALLINT(5) NOT NULL DEFAULT '-1'",
        'edcal_posts' => "SMALLINT(5) NOT NULL DEFAULT '-1'",
        'edcal_author' => "TINYINT"
    )
);
    
function onRecord() 
{
    $edcalWeeks =  $this->Mint->escapeSQL($_GET['edcal_weeks']);2
    $edcalPosts =  $this->Mint->escapeSQL($_GET['edcal_posts']);
    $edcalAuthor =  $this->Mint->escapeSQL($_GET['edcal_author']);
    
    return array
    (
        'edcal_weeks' => (float) $edcalWeeks,
        'edcal_posts' => (float) $edcalPosts,
        'edcal_author' => (boolean) $edcalAuthor
    );
}

The $manifest array1 defines the database columns we need. Mint will create these database columns when this Pepper is installed. We need columns for the number of visible weeks, the number of posts, and if they are showing authors.

We populate these fields with the onRecord function. The values come on the URL so we access the data using the PHP $_GET function2.

Querying the calendar with JavaScript

function onJavaScript() 
{
    $js = "pepper/zackgrossbart/edcalstats/script.js"1;
    if (file_exists($js))
    {
        include_once($js);
    }
}

We access configuration values in the calendar using JavaScript. We tell Mint about our JavaScript file with the onJavaScript function1. This adds the script.js file to our Mint request.

Mint.SI.EdcalStats = 
{
    onsave  : function() 
    {
        if (edcal) {
            
            /*
             * Collect the number of weeks they are showing
             */
            var val = '&edcal_weeks=' + edcal.weeksPref;1
            
            
            /*
             * If they are showing authors
             */
            if (edcal.authorPref) {2
                val += '&edcal_author=1';
            } else {
                val += '&edcal_author=0';
            }
            
            /*
             * Get the average number of posts they have
             * per day
             */
            var dayCounts = [];
            
            jQuery("#cal_cont .dayobj > .postlist").each(function() {
                /*
                 * Don't consider days with zero posts
                 */
                if (jQuery(this).children().length > 0) {
                    dayCounts.push(jQuery(this).children().length);3
                }
            });
            
            var total = 0;
            for (var i = 0; i < dayCounts.length; i++) {
                total += dayCounts[i];
            }
            
            if (dayCounts.length > 0) {
                val += '&edcal_posts=' + Math.round(total / dayCounts.length);
            } else {
                val += '&edcal_posts=0';
            }
            
            return val;
                
        }
    }
};

The Editorial Calendar is already running in our JavaScript memory space so calling it from script.js is ideal. We can call the existing functions to collect the data we need. The current number of weeks1, the authors preference2, and the average number of posts per day3. JQuery makes it easy to iterate over the DOM.

Showing the data

Now that we’ve collected all of this data we need to show it on the Editorial Calendar Statistics page. For that we’ll implement the onDisplay function

function onDisplay($pane, $tab, $column = '', $sort = '')
{
$html = '';
    switch($pane) 
    {
        case 'Editorial Calendar Stats':
        $html  = '<table cellspacing="0" class="two-edcal-columns">';
        $html .= "\r\t<tr>\r";
        $html .= "\t\t<td style=\"padding-right: 4px;\" class=\"left\">\r";
        $html .= $this->getHTML_EdcalWeeks();
        $html .= "\t\t</td>";
        $html .= "\t\t<td class=\"right\">\r";
        $html .= $this->getHTML_EdcalPosts();
        $html .= "<br />";
        $html .= $this->getHTML_EdcalAuthor();
        $html .= "\t\t</td>";
        $html .= "\r\t</tr>\r";
        $html .= "</table>\r";
        break;
    }
    
    return $html;
}

We show a little table for each piece of data we’ve collected and define the contents of that table in separate functions.

What about privacy?

There is a constant tension between collecting data and preserving privacy. I know we’re only using this data to improve the plugin, but would I trust a group of strangers to use the data? Maybe.

This article is a how to, but it’s also about transparency. I want to make it clear what data we’re collecting and how we’re using it.

We went out of our way to make sure the data collected by the calendar is innocuous and non-commercial. We don’t sell the data. Honestly, nobody would want to buy it.

The whole point is to make the calendar better. The more we understand how it’s being used the better we can make the design. The calendar should be simple and easy to use, but simple isn’t so simple. Making something that feels good means we have to know how people use it and what feels good to them. These statistics help us do just that.

This is a guest post written by Bess Siegal. Bess and I work together and she recently created an auto-complete field that handles multiple values. She stopped by to show us how it works, provide an open source example, and give you all the details you need to create a multi-value auto-complete field in GWT using REST.

More Than Just Another Type-Ahead Script

Type ahead fields are ubiquitous. Type ja into Google and it prompts you for Jamn 94.5, Java, and Jack Johnson. These single value fields work well for search, but don’t scale to multiple values. Our latest tool allows users to search for multiple users, roles, and other objects using an auto-complete field, and for that we needed something new.

This article shows you how to create a multi-valued auto-complete field using the GWT SuggestBox and REST. Communicating between the client and server with REST gives this example a strong separation between the client and the server. I proved it using a server-side component written as a Java servlet, then swapping it out, thanks to Zack, with a server-side component written in PHP.

This sample uses JavaScript, HTML, CSS, and nothing else. It runs in all the major browsers and all the way back to Internet Explorer 6. It’s also a good introduction to REST and how to use it from a browser.

Try It

The multi-value auto-complete field can handle any type of data. Here’s an example that searches for crayon colors.

Search for blue, mac, or *

A Closer Look

I began by investigating the GWT SuggestBox. It’s not multi-valued, but it does automatically send a request and shows a suggestion list popup when you type into its text field. By default its suggestions come from a MultiWordSuggestOracle, which means all the suggestions reside on the client.

Using the GWT SuggestBox with RPC by Alex Moffat explains how to retrieve suggestions from a remote source using RPC by creating a custom SuggestOracle. It got me started on creating my own SuggestOracle using REST instead of using GWT’s RPC. The jQuery auto-complete plugin by Jörn Zaefferer inspired me to make it multi-valued.

Working Example

I’ll walk you through the working code example and explain how it:

• retrieves suggestions using REST
• allows for multiple selection
• performs as an auto-completer even for multiple values that have been pasted in
• allows for browsing through large data sets without having to use a div overflow scrollbar

REST Endpoint

The REST Endpoint can be any HTTP URL that supporst GET and takes the following parameters.

• q – the query
• indexFrom – the 0-based starting index
• indexTo – the last index, inclusive

The endpoint returns JSON in the following format:

{ 
 "TotalSize" : 25,
 "Options" : [
              {"Value" : "#9ACEEB", "DisplayName" : "Cornflower"},
              {"Value" : "#CC6666", "DisplayName" : "Fuzzy Wuzzy"}
             ]
}

“TotalSize” is the total number of results yielded by the query and “Options” is the array of name-value pairs in the results from indexFrom and to indexTo.

This well-defined API allows for a server implementation in any language. The source code includes a Java servlet that serves this purpose and also the endpoint Zack wrote in PHP that drives the live demo in this article.

MultivalueSuggestBox

The MultivalueSuggestBox is a custom GWT widget that utilizes the GWT SuggestBox. It extends Composite with a FlowPanel as its main widget. It encapsulates six inner classes that support server-side data retrieval.

Below is the constructor. Its arguments are the REST endpoint URL and a boolean to specify multi-value.1 A FlowPanel2 is instantiated so that a FormFeedback3 control can be included next to the SuggestBox. The FormFeedback is a custom GWT widget that shows an icon indicating the status of the control. This lets the user know whether the control is loading and more importantly, helps to identify invalid values.

A SuggestBox is instantiated using the RestSuggestOracle4.
The m_valueMap5 is instantiated to hold all the valid values found, keyed by name.

    
/**
 * Constructor.
 * @param the URL for the REST endpoint.  
 * @param isMultivalued - true for allowing multiple values
 */
public MultivalueSuggestBox(String restEndpointUrl, boolean isMultivalued)
{
    m_restEndpointUrl = restEndpointUrl;
    m_isMultivalued = isMultivalued;

    FlowPanel panel = new FlowPanel();
    TextBoxBase textfield;
    if (isMultivalued) {
        panel.addStyleName("textarearow");
        textfield = new TextArea();
    } else {
        panel.addStyleName("textfieldrow");
        textfield = new TextBox();
    }
        
    //Create our own SuggestOracle that queries REST endpoint
    SuggestOracle oracle = new RestSuggestOracle();
    //intialize the SuggestBox
    m_field = new SuggestBox(oracle, textfield);
    if (isMultivalued) {
        //have to do this here b/c gwt suggest box wipes 
        //style name if added in previous if
        textfield.addStyleName("multivalue");            
    }
    m_field.addStyleName("wideTextField");
    m_field.addSelectionHandler(this);
        
    panel.add(m_field);
    m_feedback = new FormFeedback();
    panel.add(m_feedback);        
        
    initWidget(panel);
      
    m_valueMap = new HashMap<String, String>();
       
    resetPageIndices();        
}

RestSuggestOracle

RestSuggestOracle6, like all the other classes mentioned in the remainder of this article, is an inner class within MultivalueSuggestBox. It extends SuggestOracle implementing requestSuggestions7 and overriding isDisplayStringHTML to return true. It creates a timer8 that is reset whenever the user types9 because we only want to query the server when the user has paused in their typing. This will prevent overloading the server with unnecessary overlapping requests. After the timer has elapsed, getSuggestions10 and conditionally findExactMatches11 are called.

/**
* A custom Suggest Oracle
*/
private class RestSuggestOracle extends SuggestOracle
{
private SuggestOracle.Request m_request;
private SuggestOracle.Callback m_callback;
private Timer m_timer;

RestSuggestOracle()
{
    m_timer = new Timer() {
        
        @Override
        public void run()
        {
            /*
             * The reason we check for empty string is found at
             * http://development.lombardi.com/?p=39 --
             * paraphrased, if you backspace quickly the contents of the field 
             * are emptied but a query for a single character is still executed.
             * Workaround for this is to check for an empty string field here.
             */
            
            if (!m_field.getText().trim().isEmpty()) {
                if (m_isMultivalued) {
                    //calling this here in case a user is trying to correct the 
                    //"kev" value of Allison Andrews, Kev, Josh Nolan or pasted 
                    //in multiple values
                    findExactMatches();
                }                    
                getSuggestions();
            }
        }
    };
}

@Override
public void requestSuggestions(SuggestOracle.Request request, 
			       SuggestOracle.Callback callback)
{                
    //This is the method that gets called by the SuggestBox whenever typing in the text field            
    m_request = request;
    m_callback = callback;
    
    //reset the indexes (b/c NEXT and PREV call getSuggestions directly)
    resetPageIndices();
    
    //If the user keeps triggering this event (e.g., keeps typing), cancel and restart the timer
    m_timer.cancel();        
    m_timer.schedule(DELAY);
}

getSuggestions

First we’ll look at getSuggestions12. This method performs the query for the contents of the suggestion list popup. First, it determines the search term. When not multi-valued, the search term is the contents of the suggest box text field. If it is multi-valued, the search term is the part of the string after the last DISPLAY_SEPARATOR, in this case a comma. It then sets the FormFeedback widget to a LOADING state, then calls queryOptions.

private void getSuggestions()
{
    String query = m_request.getQuery();
    
    //find the last thing entered up to the last separator
    //and use that as the query
    if (m_isMultivalued) {
        int sep = query.lastIndexOf(DISPLAY_SEPARATOR);
        if (sep > 0) {
            query = query.substring(sep + DISPLAY_SEPARATOR.length());                
        }
    }
    query = query.trim();
    
    //do not query if it's just an empty String
    //also do not get suggestions you've already got an exact match for 
    //this string in the m_valueMap
    if (query.length() > 0 && m_valueMap.get(query) == null) {
        updateFormFeedback(FormFeedback.LOADING, null);               
                                    
        queryOptions( 
                query,
                m_indexFrom,
                m_indexTo,
            new RestSuggestCallback(m_request, m_callback, query));
    }
}

queryOptions

The queryOptions13 method sends a GET request to the URL of the REST endpoint passed to the constructor of MultivalueSuggestBox1. It uses the GWT RequestBuilder object. queryOptions converts the response from JSON to type safe Java beans14. The arguments are the query string, the indices of the result set desired, and an OptionQueryCallback15.

/**
 * Retrieve Options (name-value pairs) that are suggested from the REST endpoint
 * @param query - the String search term 
 * @param from - the 0-based begin index int
 * @param to - the end index inclusive int
 * @param callback - the OptionQueryCallback to handle the response
 */
private void queryOptions(final String query, final int from, final int to, 
                          final OptionQueryCallback callback)
{
    RequestBuilder builder = new RequestBuilder(RequestBuilder.GET, 
        URL.encode(m_restEndpointUrl + "?q=" + query + "&indexFrom=" + 
        from + "&indexTo=" + to));
        
    // Set our headers
    builder.setHeader("Accept", "application/json");
    builder.setHeader("Accept-Charset", "UTF-8");
                
    builder.setCallback(new RequestCallback() {
            
        @Override
        public void onResponseReceived(com.google.gwt.http.client.Request request, 
                                       Response response)
        {
            JSONValue val = JSONParser.parse(response.getText());
            JSONObject obj = val.isObject();
            int totSize = (int) obj.get(OptionResultSet.TOTAL_SIZE).isNumber().doubleValue();
            OptionResultSet options = new OptionResultSet(totSize);
            JSONArray optionsArray = obj.get(OptionResultSet.OPTIONS).isArray();

            if (options.getTotalSize() > 0 && optionsArray != null) {
                    
                for (int i = 0; i < optionsArray.size(); i++) {                        
                    JSONObject jsonOpt = optionsArray.get(i).isObject();
                    Option option = new Option();
                    option.setName(jsonOpt.get(OptionResultSet.DISPLAY_NAME).isString().stringValue());
                    option.setValue(jsonOpt.get(OptionResultSet.VALUE).isString().stringValue());
                    options.addOption(option);
                }
            }                    
            callback.success(options);
        }

        @Override
        public void onError(com.google.gwt.http.client.Request request, 
                            Throwable exception)
        {
            callback.error(exception);
        }
    });
        
    try {
        builder.send();
    } catch (RequestException e) {
        updateFormFeedback(FormFeedback.ERROR, "Error: " + e.getMessage());
    }
}

OptionQueryCallback

The OptionQueryCallback abstract class handles success and error conditions from the REST call.

/**
 * Handles success and error conditions from the REST call
 */
private abstract class OptionQueryCallback
{
    abstract void success(OptionResultSet optResults);
    abstract void error(Throwable exception);
}

RestSuggestCallback

RestSuggestCallback16 extends OptionQueryCallback15 and is the object passed to queryOptions13 from getSuggestions12. The RestSuggestCallback constructor takes the SuggestOracle.Request, SuggestOracle.Callback, and the query as arguments.

Once the request succeeds RestSuggestCallback evaluates the response:

• if the total size is less than one, it means there were no suggestions returned from the REST endpoint, so the FormFeedback shows an ERROR status.17 The OptionSuggestion ArrayList remains empty.18
• if the total size is equal to one, then there was only one suggestion. In this case we skip the popup and just show the value in the text field. The name of the Option replaces the string after the last DISPLAY_SEPARATOR 19. The FormFeedback shows a VALID status20. The name and value are added to the value map.21. The OptionSuggestion ArrayList remains empty.18
• if the total size is greater than 1, the The OptionSuggestion ArrayList is built up22 and these suggestions are sent back to the SuggestOracle.Callback23. We also conditionally add the next and previous options for scrolling in the results.24 The FormFeedback shows an ERROR status until the user selects a valid option.25

/**
 * A custom callback that has the original SuggestOracle.Request 
 * and SuggestOracle.Callback
 */
private class RestSuggestCallback extends OptionQueryCallback
{
    private SuggestOracle.Request m_request;
    private SuggestOracle.Callback m_callback;
    private String m_query; //this may be different from m_request.getQuery when multivalued it's only the substring after the last delimiter
        
    RestSuggestCallback(Request request, Callback callback, String query)
    {
        m_request = request;
        m_callback = callback;
        m_query = query;
    }

    public void success(OptionResultSet optResults)
    {
        SuggestOracle.Response resp = new SuggestOracle.Response();
        List<OptionSuggestion> suggs = new ArrayList<OptionSuggestion>();
        int totSize = optResults.getTotalSize();
            
        if (totSize < 1) {
            //if there were no suggestions, then it's an invalid value
            updateFormFeedback(FormFeedback.ERROR, "Invalid: " + query);
                
        } else if (totSize == 1) {
            //it's an exact match, so do not bother with showing suggestions, 
            Option o = optResults.getOptions()[0];
            String displ = o.getName();
                
            //remove the last bit up to separator
            m_field.setText(getFullReplaceText(displ, m_request.getQuery()));
                
            //it's valid!
            updateFormFeedback(FormFeedback.VALID, null);

            //set the value into the valueMap
            putValue(displ, o.getValue());

        } else {
            //more than 1 so show the suggestions
                
            //if not at the first page, show PREVIOUS
            if (m_indexFrom > 0) {
                OptionSuggestion prev = new OptionSuggestion(
                    OptionSuggestion.PREVIOUS_VALUE, m_request.getQuery());
                suggs.add(prev);
            }
                
            // show the suggestions
            for (Option o : optResults.getOptions()) {
                OptionSuggestion sugg = new OptionSuggestion(
	            o.getName(), o.getValue(), m_request.getQuery(), m_query);
                suggs.add(sugg);
            }
                
            //if there are more pages, show NEXT
            if (m_indexTo < totSize) {
                OptionSuggestion next = new OptionSuggestion(
                    OptionSuggestion.NEXT_VALUE, m_request.getQuery());
                suggs.add(next);
            }
                
            //nothing has been picked yet, so let the feedback show an error (unsaveable)
            updateFormFeedback(FormFeedback.ERROR, "Invalid: " + m_query);
        }

        //it's ok (and good) to pass an empty suggestion list back to the suggest box's callback method
        //the list is not shown at all if the list is empty.
        resp.setSuggestions(suggs);
        m_callback.onSuggestionsReady(m_request, resp);
    }

    @Override
    public void error(Throwable exception)
    {
        updateFormFeedback(FormFeedback.ERROR, "Invalid: " + m_query);
    }    
}

OptionSuggestion

OptionSuggestion objects are collected into a List and passed to SuggestOracle.Callback.onSuggestionsReady24. It extends SuggestOracle.Suggestion overriding getDisplayString and getReplacementString and adding getValue and getName methods for Option IDs and names. You could add more properties depending on your needs. In this example, the names are the crayon colors and the values are their corresponding hex codes.

OptionSuggestion has two constructors. One is for navigation26 and the other is for an actual option27.

Since RestSuggestOracle.isDisplayStringHTML is true, HTML can be used for the display string. In the body of the first constructor, the HTML returned is a div with a class that is included in the css. It will show an appropriate image to indicate navigation. In the body of the second constructor, HTML bold tags are used to highlight the query search term within each suggestion in the list popup. The value returned by getReplacementString28 is determined by calling getFullReplaceText so that the text box does not lose any previously selected options in the multi-value case, and only the portion of the contents of the text field after the last DISPLAY_SEPARATOR is replaced.

    
/**
 * Constructor for navigation options
 * @param nav - next or previous value
 * @param currentTextValue - the current contents of the text box
 */    
OptionSuggestion(String nav, String currentTextValue)
{
    if (NEXT_VALUE.equals(nav)) {
        m_display = "<div class=\"autocompleterNext\" title=\"Next\"></div>";
    } else {
        m_display = "<div class=\"autocompleterPrev\" title=\"Previous\"></div>";
    }
    m_replace = currentTextValue;
    m_value = nav;
}
    
/**
 * Constructor for regular options
 * @param displ - the name of the option
 * @param val - the value of the option
 * @param replacePre - the current contents of the text box
 * @param query - the query
 */
OptionSuggestion(String displ, String val, String replacePre, String query)
{
    m_name = displ;
    int begin = displ.toLowerCase().indexOf(query.toLowerCase());
    if (begin >= 0) {
        int end = begin + query.length();
        String match = displ.substring(begin, end);
        m_display = displ.replaceFirst(match, "<b>" + match + "</b>");
    } else {
        //may not necessarily be a part of the query, for example if "*" was typed.
        m_display = displ;
    }
    m_replace = getFullReplaceText(displ, replacePre);
    m_value = val;
}    

onSelection

MultivalueSuggestBox implements SelectionHandler<Suggestion>, so onSelection29 is called after the user chooses an option among the items shown in the SuggestBox list popup. If an option is selected, the FormFeedback shows a VALID status and the option’s name and value are put30 into the value map. If the selection is one of the navigation options, the indices are changed and getSuggestions is called again31. Having the next/previous options allows for browsing of the result set within a reasonably sized popup that does not need scrollbars.

@Override
public void onSelection(SelectionEvent<Suggestion> event)
{
    Suggestion suggestion = event.getSelectedItem();
    if (suggestion instanceof OptionSuggestion) {
        OptionSuggestion osugg = (OptionSuggestion) suggestion;
        //if NEXT or PREVIOUS were selected, requery but bypass the timer
        String value = osugg.getValue();
        if (OptionSuggestion.NEXT_VALUE.equals(value)) {
            m_indexFrom += PAGE_Size;
            m_indexTo += PAGE_Size;
            
            RestSuggestOracle oracle = (RestSuggestOracle) m_field.getSuggestOracle();
            oracle.getSuggestions();
            
        } else if (OptionSuggestion.PREVIOUS_VALUE.equals(value)) {
            m_indexFrom -= PAGE_Size;
            m_indexTo -= PAGE_Size;
            
            RestSuggestOracle oracle = (RestSuggestOracle) m_field.getSuggestOracle();
            oracle.getSuggestions();
            
        } else {
            //made a valid selection
            updateFormFeedback(FormFeedback.VALID, null);
            
            //add the option's value to the value map            
            putValue(osugg.getName(), value);
            
            //put the focus back into the textfield so user
            //can enter more
            m_field.setFocus(true);
        }
    }
}

findExactMatches

Now let’s go back and look at findExactMatches32. This is only called if multi-valued was specified, and is useful because the user might want to copy and paste an entire set of names or need to change a name that is in the middle of the text field. If there is more than one name in the text field, a query is executed for every name that does not already have a value in the value map. It resets the member variables m_findExactMatchesTotal, m_findExactMatchesFound, and m_findExactMatchesNot33, then for every non-valued term it calls findExactMatch34.

/**
 * If there is more than one key in the text field,
 * check that every key has a value in the map.
 * For any that do not, try to find its exact match.
 */
private void findExactMatches()
{
    String text = m_field.getText();
    String[] keys = text.split(DISPLAY_SEPARATOR.trim());
    int len = keys.length;       
    if (len < 2) {
        //do not continue.  if there's 1, it is the last one, and getSuggestions can handle it
        return;
    }

    m_findExactMatchesTotal = 0;
    m_findExactMatchesFound = 0;
    m_findExactMatchesNot.clear();
    for (int pos = 0; pos < len; pos++) {
        String key = keys[pos].trim();

        if (!key.isEmpty()) {
            String v = m_valueMap.get(key);
            if (null == v) {
                m_findExactMatchesTotal++;
            }
        }
    }
    //then loop through again and try to find them
    /*
     * We may have invalid values due to a multi-value copy-n-paste,
     * or going back and messing with a middle or first key;
     * so for each invalid value, try to find an exact match.
     */
    for (int pos = 0; pos < len; pos++) {
        String key = keys[pos].trim();
        if (!key.isEmpty()) {
            String v = m_valueMap.get(key);
            if (null == v) {
                findExactMatch(key, pos);
            }
        }
    }        
}

findExactMatch

findExactMatch35 updates the FormFeedback to show a LOADING status. It then calls queryOptions13, but this time the indices are hard-coded from zero to some relatively small amount so the exact match can attempt to be found within the top suggestions.

An anonymous OptionQueryCallback36 evaluates the response:

• if the total size is equal to one, then the one option is the match, so the name and value will be placed in the value map and m_findExactMatchesFound is incremented.37
• if the total size is greater than one, it loops through the result set to find if there is an exact match within those top suggestions, and if so, the name and value will be placed in the value map and m_findExactMatchesFound is incremented.38
• if an exact match is not found, then the term is added to the m_findExactMatchesNot list.39

Once m_findExactMatchesFound + m_findExactMatchesNot.size() is equal to m_findExactMatchesTotal, the FormFeedback will be updated to either show VALID if all exact matches were found40 or ERROR if any name could not be exactly matched. All names that could not be matched will be shown within the tooltip (i.e., title) of the FormFeedback.41

private void findExactMatch(final String displayValue, final int position)
{
    updateFormFeedback(FormFeedback.LOADING, null);
    
    queryOptions( 
        displayValue,
            0,
            FIND_EXACT_MATCH_QUERY_LIMIT, 
        new OptionQueryCallback() {
            
            @Override
            public void error(Throwable exception)
            {
                // an exact match couldn't be found, just increment not found
                m_findExactMatchesNot.add(displayValue);
                finalizeFindExactMatches();
            }

            @Override
            public void success(OptionResultSet optResults)
            {
                int totSize = optResults.getTotalSize();
                if (totSize == 1) {
                    //an exact match was found, so place it in the value map
                    Option option = optResults.getOptions()[0];                        
                    extactMatchFound(position, option);
                } else {
                    //try to find the exact matches within the results
                    boolean found = false;
                    for (Option option : optResults.getOptions()) {
                        if (displayValue.equalsIgnoreCase(option.getName())) {
                            extactMatchFound(position, option);
                            found = true;
                            break;
                        }                            
                    }
                    if (!found) {
                        m_findExactMatchesNot.add(displayValue);
                    }
                }
                finalizeFindExactMatches();                    
            }

            private void extactMatchFound(final int position, Option option)
            {
                putValue(option.getName(), option.getValue());

                //and replace the text
                String text = m_field.getText();
                String[] keys = text.split(DISPLAY_SEPARATOR.trim());
                keys[position] = option.getName();
                String join = "";
                for (String n : keys) {
                    join += n.trim() + DISPLAY_SEPARATOR;
                }
                join = trimLastDelimiter(join, DISPLAY_SEPARATOR);
                m_field.setText(join);
                
                m_findExactMatchesFound++;
            }
            
            private void finalizeFindExactMatches()
            {
                if (m_findExactMatchesFound + m_findExactMatchesNot.size() == 
                        m_findExactMatchesTotal) {
                    //when the found + not = total, we're done
                    if (m_findExactMatchesNot.size() > 0) {
                        String join = "";
                        for (String val : m_findExactMatchesNot) {
                            join += val.trim() + DISPLAY_SEPARATOR;
                        }
                        join = trimLastDelimiter(join, DISPLAY_SEPARATOR);                                
                        updateFormFeedback(FormFeedback.ERROR, "Invalid:" + join);
                    } else {
                        updateFormFeedback(FormFeedback.VALID, null);
                    }
                }
            }
        });
}

You can call getValue42 when the values of the selected options are needed. This implementation of getValue returns a concatenated string of all the values delimited by VALUE_DELIM, in this case a semi-colon. If any of the names were found to be invalid, that is, never exactly matched or chosen, it is removed43 and the FormFeedback will show an ERROR status with a tooltip containing the invalid name(s)44. Depending on your needs, you might choose to return the value map or an array of names and values if order is important.

/**
 * Get the value(s) as a concatenated String
 * @return value(s) as a String
 */
public String getValue()
{
    //String together all the values in the valueMap
    //based on the display values shown in the field
    String text = m_field.getText();
    
    String values = "";
    String invalids = "";
    String newKeys = "";
    if (m_isMultivalued) {
        String[] keys = text.split(DISPLAY_SEPARATOR);
        for (String key : keys) {
            key = key.trim();
            if (!key.isEmpty()) {
                String v = m_valueMap.get(key);
                if (null != v) {
                    values += v + VALUE_DELIM;
                    //rebuild newKeys removing invalids
                    newKeys += key + DISPLAY_SEPARATOR;
                } else {
                    invalids += key + DISPLAY_SEPARATOR;
                }
            }
        }
        values = trimLastDelimiter(values, VALUE_DELIM);
        //set the new display values
        m_field.setText(newKeys);
    } else {
        values = m_valueMap.get(text);
    }
    
    //if there were any invalid show warning
    if (!invalids.isEmpty()) {
        //trim last separator
        invalids = trimLastDelimiter(invalids, DISPLAY_SEPARATOR);
        updateFormFeedback(FormFeedback.ERROR, "Invalids: " + invalids);
    }
    return values;
}

The Takeaway

This type-ahead control not only accepts multiple values but also auto-completes for a multi-valued copy and paste. The user-friendly interface doesn’t impose a minimum number of characters before sending a request because it can limit the results shown while still allowing a complete browse of the dataset.

You could do all of that without REST, but we keep the client code completely encapsulated with a REST interface. This sample could be extended with client-side caching to speed up performance.

The code in this example is free and released under the Apache 2.0 license. The other programs needed to run this example are also free, but some of them may use different licenses. Make sure to read and understand each license before using a tool.

We encourage you to use this example in your own applications and we’d love to see the results. Drop us a comment if you do.

Bess Siegal is a software engineer at Novell. She enjoys her one-minute commute so she can spend more time with her husband and 3 daughters.