11 Doing advanced things - Reference Documentation
Authors: Marc Palmer (marc@grailsrocks.com)
Version: 1.0.RC2
Table of Contents
11 Doing advanced things
Once you've mastered the basics of the UI Sets and Theme system, you'll start wondering how to do some of the more advanced stuff.11.1 Creating non-standard UI elements
The UI Set tags attempt to provide the common denominator of UI elements that most plugins would need to offer basic UI functionality, and to support common features of modern website themes.There will definitely be some cases where you may want to expose extra UI elements through your UI Set.The approach to this would be to:- Declare your own tag, but use the
uixnamespace to avoid future clashes with tags added to Platform UI in future. - Implement your tag in a similar way to the Platform UI tags, calling the
renderUITemplatemethod on the UITagLib to leverage the template location mechanisms of the UI Set - Use CSS class configuration conventions similar to other Platform UI tags (see the
getUICSSClassmethod of the grailsUISets)
11.2 Creating adaptive theme layouts
There may be times where you would like to make your Theme adapt its presentation or styling based on some external factor - say based on configuration, absence of content for a specific zone, a user session variable or the presence of a model variable.An example might be integrated Twitter and Facebook sharing integration. Your theme might want to render the "like" and "tweet" buttons only if the controller indicates that sharing is desirable on the current page.Some of mechanisms available to you to perform these kinds of customisations include:- Standard
g:ifblocks to affect what is rendered by the layout - Judicious use of the layoutTemplate tag to include reusable Theme Template code
- The ifZoneContent and related tags for detecting presence of application-supplied zone content
- The ifLayoutIs and related tags that can enable a reusable Template to alter its output based on which Theme layout is active
11.3 Overriding theme layouts in your app
There may be times when one or more of the layouts provided by the Theme you are using does not function correctly or requires some changes to match with your branding.You could fork the theme, or you could simply override that Theme layout.To override a Theme layout you just provide a new GSP - containing the modified content of the Theme's layout GSP - in the same GSP view location as you would define it in your own theme:/grails-app/views/layouts/themes/<themeName>/<layoutName>.gsp
11.4 Overriding UI set templates in your app
There may also be times when one or more of the templates provided by the UI Set you are using does not function correctly or requires some changes to render exactly as you'd like.You could fork the UI Set, or you could override just the UI Set templates that you need to.To override a UI Set template you just provide a new GSP containing the modified content of the UI Set's GSP in the appropriate GSP view location:/grails-app/views/_ui/<uiSetName>/<templateName>.gsp
11.5 Modifying resources provided by Themes or UI Sets
Both Themes and UI Sets provide their resources using Resources framework modules named by convention.It is therefore possible to modify the resources included by a UI Set or Theme by using the Resources framework overrides mechanism.Using the Resources override mechanism you can:- Add or replace dependencies of the UI Set or Theme's resource module. You can introduce your own resources that load before the module by amending the dependsOn, or knock out dependencies.
- Alter properties of individual resources in one of the UI Set or Theme's modules, such as the disposition