(Quick Reference)

4 Making plugin UIs that integrate with apps - Reference Documentation

Authors: Marc Palmer (marc@grailsrocks.com)

Version: 1.0.RC2

4 Making plugin UIs that integrate with apps

One if the main wins of Platform UI is that plugins can expose UI without having a style that clashes with that of the application, and with less work required to create "good enough" UIs that the application developer can then style more specifically if they need to.

Exposing a reusable UI in a plugin

There are some key considerations to providing a UI that the developer will be able to use with their chosen look and feel.

  1. Avoid custom layout markup, the Theme controls layout
  2. Add CSS classes to container elements where customisation may be desirable (allows app dev to override CSS for plugin UI elements to fix up layout issues)
  3. Only where absolutely necessdary, supply a non-standard theme layout of your own, and the developer can adapt it for their theme. Document the zones required.
  4. There is no standard grid, try to stick to fluid or % based layout

How to implement non-standard UI elements

With 1.0 you'll have to create your own tag that uses a GSP template to render your field, so that the application developer can override that GSP template to match the UI set and theme they have chosen.

In the future it should be possible to reuse existing UI tags and helper methods to achieve this using the same conventions used by UI Sets.

You can make your plugin UI adaptive based on the theme or UI set in user, or the presence of other plugins in the app.

  • Your plugin can provide resource "overrides" for resource modules provided by specific UI sets or themes. You can replace existing resources or monkey in your own code into a module by adding a dependency.
  • Your plugin can detect presence of plugins using the Grails plugin:isAvailable tag
  • Your plugin can detect the current Theme and UI Set in use in the request using the ui:ifSetActive and theme:name tags.

Customising UI provided by a plugin

The application developer needs to be able to customize or "fix up" the UI you provide. It's simply not possible for you to provide a UI that looks perfect in every different Theme and CSS/JS framework the user chooses.

The developer has the following options to provide customisations of your UI:

  • UISet CSS class overrides, for when you are using normal UI Set tags
  • CSS using CSS classes you have applies to container elements and documented
  • Theme layout overrides, allowing them to replace specific Theme layouts to work around problems
  • UISet template overrides, allowing them to replace UI tag implementations
  • GSP view overrides, the nuclear option which allows them to override your plugin's view