The RichUI component plug-in for Grails is great! It provides a really simple means of accessing rich Ajax functionality in a Grails application. I used this plug-in recently to implement an AutoComplete text field but needed to apply some formatting to the results. This post explains how I did this.

I’m not going to explain anything that’s already documented for RichUI’s AutoComplete component. Basic formatting customisation is already documented, so if you’re looking to change the colours used or the width of the output then take a look there.

The code I was working on searched a multi-lingual database for words, the initial output being displayed looked like this:

in addition to this, I wanted to display locale flags for the languages alongside the results:

This change would involve modifying, not just the styles, but the actual HTML that was being used to render the results by the AutoComplete component.

The RichUI plug-in is based on the Yahoo User Interface Library or YUI for short. The AutoComplete component in RichUI, is just a Grails tag that creates a YUI AutoComplete component; the documentation for which explains how the HTML for the results list can be customised.

In short, to customise the HTML, there is a method named ‘formatResult‘ on the AutoComplete JavaScript object that gets called to render each of the results. By default, this method just returns the plain text of the result. However, it can be overridden to provide custom mark-up.

The documentation for the RichUI AutoComplete tag explains how a JavaScript function can be registered to handle an ‘onItemSelect’ event, but there is no explanation of how to override any other methods. After a little investigation of the RichUI plug-in code I found that the renderer that produces the HTML for the tag does in fact and associate any attributes declared on the tag as properties/methods on the YUI component. Note that this is not a documented feature, but one I would hope would not be changed in future versions of this plug-in.

So by declaring the RichUI tag like this:

<richui:autoComplete
    name="keywords"
    action="${createLinkTo('dir': 'word/findAjax')}"
    maxResultsDisplayed="20"
    formatResult="myFormatResult"/>

the renderer will generate JavaScript like this; setting not only the formatResult event handler, but the maxResultsDisplayed property too:

autoComplete = new YAHOO.widget.AutoComplete('keywords','...', dataSource);
autoComplete.maxResultsDisplayed = 20;
autoComplete.formatResult = myFormatResult;

it’s then just a matter of implementing a JavaScript function that generates the HTML for each of the items:

function formatResult(oResultData, sQuery, sResultMatch) {
  var sMarkup;
  var locale = oResultData[1];
  var imageUri = "${createLinkTo(dir:'/images/flags')}/" + locale + ".png";
  if (sResultMatch) {
    sMarkup = "<img src=" + imageUri + "/> " + sResultMatch
  } else {
    sMarkup = ""
  }
  return sMarkup;
}

Finally, it’s worth noting here that the data returned from the search controller is available in the ‘oResultData’ array that gets passed in to this function. In this example, you can see that the locale for the word is being accessed and used to generate the image URI.

To achieve this, the response is being generated in the search controller like this:

render(contentType: "text/xml") {
  results() {
    words.each { w ->
      result() {
        name(w.stem)
        id(w.locale)
      }
    }
  }
}

the name and id elements that are being produced in the XML are those specified in the schema that RichUI uses. The name element is the value that is usually displayed by the component, the ID is a supplemental value that is available to the RichUI ‘onItemSelect’ JavaScript event handler. it should be possible to extend this but I’ll leave that challenge for another day…

If you’d like to see this code in action take a look at the Language Spider project web-site.