(Quick Reference)

5 Recipes - Reference Documentation

Authors: Marc Palmer (marc@grailsrocks.com)

Version: 1.0.RC2

5 Recipes

These sections explain how to achieve some common functionality using the UI APIs.

5.1 Setting the theme at runtime

The current theme is determined on a per-request basis. If no theme is explicitly set, it will default to the theme specified in Config.

One use of this is to allow the user to select the look and feel of an application. You could also change the theme based on the current User Agent, or based on the Locale of the user for example.

You can call the theme:set tag from inside a controller or GSP:

<theme:set name="mega"/>

You can also access the grailsThemes bean and set the theme per-request or per-session, from a service, filter or controller:

    // Set it once now and forget for the future requests
    grailsThemes.setSessionTheme(request, "mega")

    // Or just set it for this request
    grailsThemes.setRequestTheme(request, themeNameFromUserPreferences)

5.2 Rendering complex inputs

Inputs in forms can sometimes deviate from the straight forward label plus widget pattern. Some forms require an alternative layout for some fields, aggregation of multiple fields into one visual group - say a "from" and "to" date that represent a period.

You can usually achieve this with UI Set tags by making use of the ui:field customisation tags ui:fieldInput, ui:fieldErrors, ui:fieldLabel and ui:fieldHint.

These allow you to use ui:field but replace the various components of a field (label, hint, errors, input) with your own markup - which can use other UI tags.

Say we needed to render two date fields using a single label for the two, to specify a date period:

    <ui:field label="report.date.range">
            <ui:input bean="${form}" name="startDate"/>
            <ui:input bean="${form}" name="endDate"/>

Because the ui:input tag does smart field rendering but without any decoration, you can reuse it here to render the fields.

5.3 Using UI Sets without Themes

It is perfectly possible to use UI Sets without themes. You may not want to use the Theme layout system at all, but want to leverage the abstracted UI elements.

To do this you simply need to tell the UI API which UI Set to use for the current request. Normally this is inferred from the request's current Theme.

You can do this in a couple of ways. In Config you can set the UI Set to use:

plugin.platformUi.ui.set = 'myUISet'

Alternatively you can set it at runtime e.g. in a tag, controller or filter using the grailsUISets bean:

grailsUISets.setRequestUISet(request, "myUISet")