(Quick Reference)

3 Configuration - Reference Documentation

Authors: Benjamin Wolff

Version: 1.0.1

3.1Application Configuration

3.2Entry Point Configuration

3.3Theme Configuration

3.4Logging Configuration

3.5RWT Version Configuration

3 Configuration

The RWT configuration goes into a special block in the grails-app/conf/Config.groovy file.

rwt {
    // RWT configuration goes here.
}

There are different aspects that can be configured, the global RWT application settings, the entry point settings, and the theme settings.

For more information about RWT in general please have a look at the RAP/RWT 2.1 developer's guide.

Classpath Resources
Some configuration settings (e.g. theme CSS files) expect a relative path to a file that is visible on the classpath. The easiest way is to put your static file resources in a sub-folder of src/java or src/groovy of your Grails application. This way the files are available in the classpath without any additional configuration.
This also enables you to reference files that are provided in the classpath by other plugins or libraries.

3.1 Application Configuration

There are a few configuration settings available that configure global aspects of a RWT application. Currently, all the documented settings here are optional. Therefore, you don't have to specify any of them if you don't have any special requirements.

The global RWT configuration go directly into the rwt configuration block in the Config.groovy:

rwt {
    // Global RWT application configuration goes here.
}

The currently supported settings are:

operationMode - The RWT operation mode as a string (optional) . Currently supported values are 'JEE_COMPATIBILITY' (default) , 'SWT_COMPATIBILITY', and 'SESSION_FAILOVER'.
phaseListeners - A list of either Class instances or the names (string) of a registered Spring bean that implement the PhaseListener interface (optional) . In case a Class instance is used the class needs to have a public default constructor without arguments. The list can also contain Class instances and bean names at the same time.
themableWidgets - A list of Class instances of themable custom widgets (optional) . For more information about custom widgets please see the RWT documentation and the RWT JavaDocs.

The following snippet shows an example configuration of all currently available RWT application configuration values:

rwt {
    operationMode = 'SWT_COMPATIBILITY' // "Required to use blocking SWT/JFace APIs like Display#sleep()"
    phaseListeners = [org.example.MyPhaseListener, 'myPhaseListenerBean'] // "Class instances and bean names can be mixed."
    themableWidgets = [org.example.MyThemableWidget1, org.exampleMyThemableWidget2]
}

3.2 Entry Point Configuration

An RWT application can consist of one or more entry points. Each entry point is configured as a configuration block within the rwt section.

rwt {
    entrypoints {
        hello {
            bean = 'entryPointBean'
            …
        }
    }
}

The given example configures an entry point with the name hello. By default, this entry point will be mapped to the relative URL path '/hello'. The following settings need to be provided for an entry point configuration:

bean - The name (string) of the registered Spring bean that implements the EntryPoint interface (required) .
pageTitle - The title (string) that will be displayed as the browser's title (optional) .
favicon - Relative path to an .ico image that will be used as the favicon for the entry point (optional) .
themeId - The ID of the registered theme (optional) . Please see the theme configuration section in this guide.
headHtml - Relative path to a file containing HTML (optional) . The content of the file will be added to the <head> element of the host page. Please see the RWT JavaDocs for more information.
bodyHtml - Relative path to a file containing HTML (optional) . The content of the file will be added to the <body> element of the host page. Please see the RWT JavaDocs for more information.

A Grails-RWT application can contain an arbitrary number of entry points, which usually refer to different entry point beans.

rwt {
    entrypoints {
        hello {
            bean = 'helloEntryPoint'
            …
        }        helloAgain {
            bean = 'helloAgainEntryPoint'
            …
        }
    }
}

In this example there will be two entry points accessible under '/hello' and '/helloAgain'. For customizing the default URL mapping behaviour please see the Advanced Topics chapter.

Shown below is an example with all currently available entry point configuration values:

rwt {
    entrypoints {
        hello {
            bean = 'helloEntryPointService'
            pageTitle = 'Hello RWT World!'
            favicon = 'icons/favicon.ico'
            themeId = 'mytheme'
            headHtml = 'html/head.html'
            bodyHtml = 'html/body.html'
        }
    }
}

3.3 Theme Configuration

The plugin supports a simply configuration of RWT themes and theme contributions that can be used in the entry point configuration. The themes are provided via CSS files and configured via relative paths in the application's classpath. Shown below is an example theme configuration:

rwt {
    themes {
        rwtdefault = 'themes/default.css'
        mytheme = 'themes/mytheme.css'
        mytheme2 = ['themes/mytheme2.css', 'themes/mytheme3.css']
    }
}

Themes are configured in the themes block, each entry in this block represents a different theme, the name of the entry is the theme ID that is used to reference it in the entry point configuration. A special theme name is rwtdefault. This name references the default RWT theme and the CSS files provided for this name are treated as contributions and will be merged into the RWT default theme. Additions to this theme are automatically applied to your widgets without the need to add a theme configuration to your entry point. The example shown above also creates the two custom themes with the ID mytheme and mytheme2.

As mentioned before, the values of the themes are paths denoting a CSS file on the classpath. The value can be a single path string or a list of path strings. In case a list of paths is provided, the first file will be used as the main theme file and the subsequent files are treated as contributions to this theme file. The order in which they are specified determine the order in which the contributions are applied. This mechanism allows it to enhance your own themes with theme additions coming from other plugins or libraries, as long as the CSS files are accessible via the classpath.

For more information about theming in RWT and what widgets and properties are supported in the CSS please refer to the RWT theming reference.

3.4 Logging Configuration

The plugin logs some information in the INFO and DEBUG levels. To increase the verbosity of the log messages you can enable the debug level for some plugin artifacts. Add the following lines to the log4j section of your Config.groovy file:

log4j = { // Other logging configurations

debug 'grails.app.conf.RwtPluginBootStrap' debug 'grails.plugins.rwt' debug 'grails.rwt' debug 'RwtGrailsPlugin' }

3.5 RWT Version Configuration

The current version of the plugin is based on RWT version 2.1. The required libraries are resolved from the Maven central repository using the default Grails dependency mechanism (Ivy). An application can override these dependencies manually to use a more recent version of RWT. This can be useful to test new milestone releases or use new service releases without having to wait for a new release of the Grails-RWT plugin.

The internal mechanisms of the Grails RWT plugin are currently based on the API of version 2.1. If you use a new RWT version that comes with breaking API changes the plugin won't work anymore. In order to use the latest RWT version in this case a new release of the Grails RWT plugin is necessary.

Here is an example configuration in the BuildConfig.groovy to use the RWT 2.2 milestone release:

grails.project.dependency.resolution = {    dependencies {
        compile('org.eclipse.rap:org.eclipse.rap.rwt:2.2.0-M1')
        compile('org.eclipse.rap:org.eclipse.rap.jface:2.2.0-M1')
        compile('org.eclipse.rap:org.eclipse.rap.jface.databinding:2.2.0-M1')
    }
}

The RWT JFace libs require three additional dependencies which are currently not present in the Maven central in the required version. Therefore, these dependencies are bundled in the lib folder of the RWT plugin. If you manually configure a newer RWT JFace version, you should make sure that the provided dependencies still satisfy the required version range of the RWT JFace libs. If they require new versions of the dependency you could grab the libs i.e. from the RAP target platform and put those in the lib folder of the project, so that they override the outdated versions provided by the RWT plugin.

<< 2Getting Started

4Advanced Topics >>