RichUI Plugin

Author: Andreas Schmitt

• #Abstract
• #Installation
• #Components
• #Plugin version history

Abstract

This plugin adds a set of AJAX components which can be used to create rich user interfaces without having to deal with JavaScript libraries.

Installation

To install the plugin type:> grails install-plugin richui

Components

General information which applies to all components:

• #Resources
• #Remote resources
• #Skins
• #Global renderer configuration

• #Accordion
• #AutoComplete
• #CalendarDayView
• #CalendarMonthView
• #CalendarWeekView
• #Carousel
• #CheckedTreeView
• #DateChooser
• #Flow
• #Font (creates images dynamically)
• #Map
• #Portlet
• #Redirect
• #ReflectionImage
• #RichTextEditor
• #Star rating
• #TabView
• #TagCloud
• #Timeline
• #Tooltip
• #TreeView

Resources

Some of these components require JavaScript libraries or CSS. RichUI contains all these libraries like YUI etc. so you don't have to download them separately. To include the required resources into your GSP the following technique is used: <resource:componentName /> ComponentName stands for the name of a component. To include the required ressources for the AutoComplete component you would include the following markup in your HTML header:<resource:autoComplete />

Remote resources

All components based on Yahoo User Interface (YUI) offer the possibility to use local CSS and JavaScript resources (default) or remote resources served from Yahoo's servers. You can enable remote resources globally for all supported components by adding the following line to "yourproject/grails-app/conf/Config.groovy":

richui.serve.resource.files.remote=true

You can also set this mode individually for each component in the resource tag e.g.:

<resource:autoComplete remote="true" />

If you use remote resources you can delete "yourproject/plugins/richui-0.5/web-app/js/yui" and reduce the size of your WAR file.

The following components are based on YUI:

• AutoComplete
• DateChooser
• TabView
• Tooltip
• TreeView

Skins

Instead of the bundled CSS files you can create your own CSS skins and specify that these should be used. This is done via the skin attribute of the resource tag e.g. <resource:autoComplete skin="myAutoComplete" /> includes a CSS file which should be located in "yourproject/web-app/css/myAutoComplete.css". A custom CSS skin would be typically based on a bundled one so you can take the bundled ones as templates. They are located in "yourproject/plugins/richui-0.5/web-app/css".

Global renderer configuration

RichUI uses a renderer concept where each component is rendered by a dedicated renderer. Which renderer is used can be configured e.g. to easily switch between Yahoo Maps and Google Maps or tinyMCE and Yahoo Rich Text Editor etc. A default configuration can be found in RichuiConfig.groovy (richui-version/grails-app/conf). You can override this configuration by adding a property called richui.renderername="rendererclass" where renderernames can be found in (richui-version/grails-app/conf).

richui.richTextEditorRenderer="de.andreasschmitt.richui.taglib.renderer.YahooMapsRenderer"
richui.mapRenderer="de.andreasschmitt.richui.taglib.renderer.MicrosoftVirtualEarthRenderer"

Accordion

This component provides an accordion menu. It is based on http://www.hedgerwow.com/360/mwd/accordion/demo.php?page=1.

To use the Accordion component include the following markup in your GSP.

<resource:accordion skin="default" />
...
<richui:accordion>
    <richui:accordionItem id="1" caption="Sample 1">
    A sample text.
    </richui:accordionItem>
    <richui:accordionItem caption="Sample 2">
    Another sample text.
    </richui:accordionItem>
    <richui:accordionItem caption="Sample 3">
    Even another sample text.
    </richui:accordionItem>
</richui:accordion>

The Accordion tag supports the following attributes:

• class (CSS class)
• style (CSS style)

• caption (item caption)
• id (HTML id)

Example

GSP:

<resource:accordion skin="default" />
...
<richui:accordion style="width: 500px;">
    <richui:accordionItem caption="Sample 1">
    A sample text.
    </richui:accordionItem>
    <richui:accordionItem caption="Sample 2">
    Another sample text.
    </richui:accordionItem>
    <richui:accordionItem caption="Sample 3">
    Even another sample text.
    </richui:accordionItem>
</richui:accordion>

Customization

If you don't like the standard skin of the accordion you can change it by adding a skin attribute to the resource tag.

Default skin

<resource:accordion />

Custom

<resource:accordion skin="custom" />

AutoComplete

This component provides auto completion functionality for text fields. It is based on YUI.

To use the AutoComplete component include the following markup in your GSP.

<resource:autoComplete skin="default" />
...
<g:form>
    <richui:autoComplete name="name" action="${createLinkTo('dir': 'controller/action')}" />
</g:form>

This will render a HTML input tag with the name name and controller/action as datasource for auto completion. The AutoComplete tag supports the following attributes:

• name (name of the input tag) required
• action (datasource for auto completion, defaults to current action)
• controller (controller to which AJAX request should be send, defaults to current controller)
• id (id of the input tag, defaults to name if not specified)
• class (CSS class)
• style (CSS style)
• title (HTML title)
• shadow (specifies if shadow should be used for displaying auto complete box, can be true or false)
• minQueryLength (minimum query length before a query is send, can be an integer defaults to 0)
• queryDelay (delay in seconds before a query is send, can be an integer defaults to 0)
• delimChar (specifies the delimiter char e.g. ',' to separate multiple entries)
• value (value of the input text)
• forceSelection (forces selection of an suggested item, can be true or false)
• typeAhead (specifies if type ahead feature should be used, can be true or false)
• onItemSelect (a javascript function which is called when an item is selected, variable id is available if specified in controller)

Example

GSP:

<resource:autoComplete skin="default" />
...
<g:form>
    <richui:autoComplete name="person" action="${createLinkTo('dir': 'person/searchAJAX')}" />
    <richui:autoComplete name="searchperson" action="${createLinkTo('dir': 'person/searchAJAX')}" 
              onItemSelect="document.location.href = '${createLinkTo(dir: 'person/show')}/' + id;" />
    <richui:autoComplete name="persons" delimChar="," action="${createLinkTo('dir': 'person/searchAJAX')}" />
</g:form>

Controller:

class PersonController {
    def searchAJAX = {
        def persons = Person.findAllByNameLike("%${params.query}%")
        //Create XML response
        render(contentType: "text/xml") {
	    results() {
	        persons.each { person ->
		    result(){
		        name(person.name)
                        //Optional id which will be available in onItemSelect
                        id(person.id)
		    }
		}
            }
        }
    }
}

This component also supports pass through attributes. That means you can pass HTML, YUI data source and YUI configuration attributes by using one of the following prefixes html (HTML) and datasource (YUI data source). Attributes without prefix are considered to be YUI configuration attributes. With this feature you can directly use features of the underlying YUI compoenents. HTML attributes are passed through the rendered input field.

Example

<resource:autoComplete skin="default" />
...
<g:form>
    <richui:autoComplete name="person" action="searchAJAX" html:title="This is an auto complete field" datasource:delimChar=";" />
</g:form>

Customization

If you don't like the standard skin of the auto complete box you can change it by adding a skin attribute to the resource tag.

Default YUI skin

<resource:autoComplete />

Default RichUI skin (uses webapp/css/autocomplete.css in the plugin directory)

<resource:autoComplete skin="default" />

Custom

<resource:autoComplete skin="custom" />

The last option allows you to use your own stylesheet. See webapp/css/autocomplete.css in the plugin directory for an example. You can also modify this file directly if you like and use the second option.

CalendarDayView

This component displays domain objects on a calendar day view.

To use the CalendarDayView component include the following markup in your GSP.

<resource:calendarDayView />
…
<richui:calendarDayView startHour="7" endHour="21" date="${date}" format="dd.MM.yyyy" items="${appointments}" constraintDateFields="['startDate-endDate']" createLink="true" displayField="subject" teaser="true" teaserLength="20" action="show" />

You should also add the following lines to "yourproject/grails-app/i18n/messages.properties".

default.time=Time
default.monday=Monday
default.tuesday=Tuesday
default.wednesday=Wednesday
default.thursday=Thursday
default.friday=Friday
default.saturday=Saturday
default.sunday=Sunday

The CalendarDayView tag supports the following attributes:

• startHour (hour a day should start, defaults to 6)
• endHour (hour a day ends, defaults to 22)
• date (date which should be displayed, can be java.util.Date, defaults to new Date())
• format (date format in which the day's date should be displayed, defaults to dd.MM.yyyy)
• items (a list of domain objects which should be displayed)
• constraintDateFields (domain attributes which should be used to decide if and when an item is displayed, is a list of attributes and allows to specify from to date ranges)
• createLink (determines whether a displayed item should be rendered with a link, can be true or false, defaults to false)
• displayField (domain attribute which should be displayed, defaults to toString())
• teaser (determines whether displayField should be shortened, can be true or false, defaults to false)
• teaserLength (length of the teaser text, an be an integer, defaults to 30)
• action (action which should be invoked when a domain object is clicked, defaults to current action)
• controller (controller which should be invoked when a domain oject is clicked, defaults to current controller)

Customization

If you don't like the standard skin of the CalendarDayView you can change it by adding a skin attribute to the resource tag.

Default skin

<resource:calendarDayView />

Custom

<resource:calendarDayView skin="myCalendarDayView" />

CalendarMonthView

This component displays domain objects on a monthly calendar view.

To use the CalendarMonthView component include the following markup in your GSP.

<resource:calendarMonthView />
…
<richui:calendarMonthView items="${appointments}" createLink="true" 
constraintDateFields="['startDate-endDate', 'startDate', 'endDate']" displayField="subject" teaser="true" teaserLength="20" weekOfYear="true" weekAction="week" dayAction="day" month="${month}" action="show" />

You should also add the following lines to "yourproject/grails-app/i18n/messages.properties".

default.week=Week
default.monday=Monday
default.tuesday=Tuesday
default.wednesday=Wednesday
default.thursday=Thursday
default.friday=Friday
default.saturday=Saturday
default.sunday=Sunday

The CalendarMonthView tag supports the following attributes:

• items (a list of domain objects which should be displayed)
• constraintDateFields (domain attributes which should be used to decide if and when an item is displayed, is a list of attributes and allows to specify from to date ranges)
• createLink (determines whether a displayed item should be rendered with a link, can be true or false, defaults to false)
• displayField (domain attribute which should be displayed, defaults to toString())
• teaser (determines whether displayField should be shortened, can be true or false, defaults to false)
• teaserLength (length of the teaser text, an be an integer, defaults to 30)
• action (action which should be invoked when a domain object is clicked, defaults to current action)
• controller (controller which should be invoked when a domain oject is clicked, defaults to current controller)
• weekOfYear (determines whether week of year should be displayed, can be true or false, defaults to )
• month (the month which should be displayed, can be java.util.Date, defaults to new Date())
• weekAction (action which is invoked when a week is clicked)
• weekController (controller which is invoked when a week is clicked, defaults to current controller)
• dayAction (action which is invoked when a day is clicked)
• dayController (controller which is invoked when a day is clicked, defaults to current controller)

Customization

If you don't like the standard skin of the CalendarMonthView you can change it by adding a skin attribute to the resource tag.

Default skin

<resource:calendarMonthView />

Custom

<resource:calendarMonthView skin="myCalendarMonthView" />

CalendarWeekView

This component displays domain objects on a weekly calendar view.

To use the CalendarWeekView component include the following markup in your GSP.

<resource:calendarWeekView />
…
<richui:calendarWeekView startHour="7" endHour="21" date="${date}" format="dd.MM.yyyy" items="${appointments}" constraintDateFields="['startDate-endDate']" createLink="true" displayField="subject" teaser="false" teaserLength="20" action="show" dayAction="day" />

You should also add the following lines to "yourproject/grails-app/i18n/messages.properties".

default.time=Time
default.monday=Monday
default.tuesday=Tuesday
default.wednesday=Wednesday
default.thursday=Thursday
default.friday=Friday
default.saturday=Saturday
default.sunday=Sunday

The CalendarWeekView tag supports the following attributes:

• items (a list of domain objects which should be displayed)
• constraintDateFields (domain attributes which should be used to decide if and when an item is displayed, is a list of attributes and allows to specify from to date ranges)
• createLink (determines whether a displayed item should be rendered with a link, can be true or false, defaults to false)
• displayField (domain attribute which should be displayed, defaults to toString())
• teaser (determines whether displayField should be shortened, can be true or false, defaults to false)
• teaserLength (length of the teaser text, an be an integer, defaults to 30)
• action (action which should be invoked when a domain object is clicked, defaults to current action)
• controller (controller which should be invoked when a domain oject is clicked, defaults to current controller)
• date (the week which should be displayed, can be java.util.Date and should start with monday, defaults to new Date())
• dayAction (action which is invoked when a day is clicked)
• dayController (controller which is invoked when a day is clicked, defaults to current controller)

Customization

If you don't like the standard skin of the CalendarWeekView you can change it by adding a skin attribute to the resource tag.

Default skin

<resource:calendarWeekView />

Custom

<resource:calendarWeekView skin="myCalendarWeekView" />

Carousel

This component displays items e.g. photos in a carousel. It is based on Prototype UI.

To use the Carousel component include the following markup in your GSP.

<resource:carousel />
...
<richui:carousel direction="horizontal">
    <richui:carouselItem>
        <img src="/richuitest/images/imgs/1.jpg" alt="One"/><br/>One
    </richui:carouselItem>
    <richui:carouselItem>
        <img src="/richuitest/images/imgs/2.jpg" alt="Two"/><br/>Two
    </richui:carouselItem>
    <richui:carouselItem>
        <img src="/richuitest/images/imgs/3.jpg" alt="Three"/><br/>Three
    </richui:carouselItem>
    <richui:carouselItem>
        <img src="/richuitest/images/imgs/4.jpg" alt="Four"/><br/>Four
    </richui:carouselItem>
</richui:carousel>

This will render a carousel which allows you to navigate through the items specified. You can put any kind of HTML or GSP into a carouselItem. The Carousel tag supports the following attributes:

• direction (direction of the carousel, can horizontal or vertical) required
• carouselStyle (CSS style for entire carousel)
• carouselClass (CSS class for entire carousel)
• itemsStyle (CSS style for carousel items)
• itemsClass (CSS class for carousel items)

Example

GSP:

<resource:carousel />
...
<richui:carousel direction="vertical" carouselStyle="height: 450px;" itemsStyle="height: 400px;">
    <richui:carouselItem>
        <img src="/richuitest/images/imgs/1.jpg" alt="One"/><br/>One
    </richui:carouselItem>
    <richui:carouselItem>
        <img src="/richuitest/images/imgs/2.jpg" alt="Two"/><br/>Two
    </richui:carouselItem>
    <richui:carouselItem>
        <img src="/richuitest/images/imgs/3.jpg" alt="Three"/><br/>Three
    </richui:carouselItem>
    <richui:carouselItem>
        <img src="/richuitest/images/imgs/4.jpg" alt="Four"/><br/>Four
    </richui:carouselItem>
</richui:carousel>

Customization

If you don't like the standard skin of the carousel box you can change it by adding a skin attribute to the resource tag.

Default skin

<resource:carousel />

Classic skin (only available for horizontal orientation)

<resource:carousel skin="classic" />

CheckedTreeView

This component creates a tree view with checkboxes based on data given in XML. It is based on YUI.

To use the CheckedTreeView component include the following markup in your GSP.

<resource:checkedTreeView />
...
<g:form action="update">
     ....
     <richui:checkedTreeView id="ctree"
         xml="${projectTree}" showRoot="false"/>
     ....
     <input type="hidden" id="selectedIds"
         name="selectedSubprojectIds" value=""/>
     <g:actionSubmit value="Update" action="update"
         onclick="collectCheckedNodes('ctree','selectedIds');"/>
</g:form>

This will display a tree view displaying the data specified in data. The TreeView tag supports the following attributes:

• id (DOM id of the div)
• xml (data which should be displayed) required
• showRoot (determines whether root node should be displayed or not, can be true or false)

Example

GSP:

<resource:checkedTreeView />
...
<g:form action="update">
     ....
     <richui:checkedTreeView id="ctree"
         xml="${data}" showRoot="false"/>
     ....
     <input type="hidden" id="selectedIds"
         name="selectedSubprojectIds" value=""/>
     <g:actionSubmit value="Update" action="update"
         onclick="collectCheckedNodes('ctree','selectedIds');"/>
</g:form>

Controller:

import groovy.xml.MarkupBuilder
class PersonController {
    def list = {
    	def writer = new StringWriter()
	def xml = new MarkupBuilder(writer)
    	xml.person(name: "John Doe", id: 1){
    	    books(name: "Books", id: 2){
    	        book(name:"Book 1", id: 3, checked: false)
    		book(name:"Book 2", id: 4, checked: true)
    	    }
    	}
        if(!params.max)params.max = 10
        [ "data": writer.toString(), personList: Person.list( params )]
    }
}

Customization

If you don't like the standard skin of the checked tree view you can change it by adding a skin attribute to the resource tag.//Default YUI skin

<resource:checkedTreeView />

Default RichUI skin (uses webapp/css/treeView.css in the plugin directory)

<resource:checkedTreeView skin="default" />

Custom

<resource:checkedTreeView skin="custom" />

The last option allows you to use your own stylesheet. See webapp/css/treeView.css in the plugin directory for an example. You can also modify this file directly if you like and use the second option.

DateChooser

This tag allows you to select dates via a popup calendar. It is based on YUI and http://blog.davglass.com/files/yui/cal2.

To use the DateChooser component include the following markup in your GSP.

<resource:dateChooser />
...
<g:form>
    <richui:dateChooser name="birthday" format="dd.MM.yyyy" />
</g:form>

This will render a HTML input tag with the name birthday which will display a popup calendar when it is selected. The selected date will be displayed in format dd.MM.yyyy. The DateChooser tag supports the following attributes:

• name (name of the input tag) required
• id (id of the input tag, defaults to name if not specified)
• class (CSS class)
• style (CSS style)
• format (date format, dd.MM.yyyy, dd-MM-yyyy, dd/MM/yyyy, MM/dd/yyyy, yyyy-MM-dd are supported)
• locale (the locale for month names, en and de are supported, defaults to request locale)
• value (value of the input text, must be a Date)
• firstDayOfWeek (specifies first day of the week, can be Su, Mo, Tu, We, Th, Fr or Sa)
• time (enable time input mode, can be true or false, defaults to false)
• hourClass (CSS class for hour input field)
• hourStyle (CSS style for hour input field)
• minuteClass (CSS class for minute inpute field)
• minuteStyle (CSS style for hour input field)

Example

GSP:

<resource:dateChooser />
...
<g:form>
    <richui:dateChooser name="birthday" format="dd.MM.yyyy" value="${new Date()}" locale="de" firstDayOfWeek="Mo" />
</g:form>

This component supports pass through attributes. That means you can pass HTML attributes directly to the rendered HTML input field by using the prefix html.

Example

<resource:dateChooser />
...
<g:form>
    <richui:dateChooser name="birthday" format="dd.MM.yyyy" html:style="font-size: 16pt;" />
</g:form>

Flow

This tag displays images similar to Apple's Coverflow. It is based on ProtoFlow.

To use the Flow component include the following markup in your GSP.

<resource:flow />
...
<richui:flow reflection="true" slider="true" onClickScroll="true">
    <img src="/richuitest/images/imgs/1.jpg" alt="One"/>
    <img src="/richuitest/images/imgs/2.jpg" alt="Two"/>
    <img src="/richuitest/images/imgs/3.jpg" alt="Three"/>
    <img src="/richuitest/images/imgs/4.jpg" alt="Four"/>
</richui:flow>

This will render a coverflow which allows you to navigate by using the slider or clicking on the images. The Flow tag supports the following attributes:

• caption (displays img alt-attribute as caption, can be true or false, defaults to false)
• reflection (turns image reflection on and off, can be true or false, defaults to true)

• onClickScroll (turns on lick scrolling on and off, can true or false, defaults to true)
• startIndex (specifies initial scroll index, can be an integer, defaults to 2)
• slider (turns slider visibility on and off, can be true or false)

Example

GSP:

<resource:flow />
…
<richui:flow reflection="true" slider="true" onClickScroll="false">
    <g:link action="showPhoto" controller="Photo"><img src="/richuitest/images/imgs/1.jpg" alt="One"/></g:link>
    <img src="/richuitest/images/imgs/2.jpg" alt="Two"/>
    <img src="/richuitest/images/imgs/3.jpg" alt="Three"/>
    <img src="/richuitest/images/imgs/4.jpg" alt="Four"/>
</richui:flow>

Font

The Font tag allows you embed special fonts which are probably not available on client PCs. To accomplish this it creates images dynamically. It is inspired by http://rghosh.free.fr/groovyimages/index.html.

To use the Font component include the following markup in your GSP.

<richui:font text="Groovy is cool" fontName="Wargames" fontStyle="bold" size="36" color="#0000CC" />

This will generate an image displaying the text "Groovy is cool" using the Wargames font with font style bold, a size of 36pt and the color blue. The Font tag supports the following attributes:

• text (text to display) required
• fontName (name of the font) required
• fontStyle (style of the font, can be plain, bold and italic, defaults to plain)
• size (size of the font) required
• color (font color in HEX, defaults to #000000 black)

Example

GSP:

<richui:font text="Hello Grails" fontName="Arial" size="12" />

Map

The Map tag displays addresses on a map including search funtionality and driving directions. Depending on the renderer you choose it is either based on Google Maps API (default), Yahoo Maps or Microsoft Virtual Earth.

This component has been renamed to map since version 0.6. In previous versions the tag was called googlemaps.

To use the Map component include the following markup in your GSP.

<resource:map key="your key" />
...
<richui:map lat="40.689299" lng="-74.044" />

This will render a map displaying position 40.689299 (latitude) and -74.044 (longitude). For your key you have to supply your Google Maps key (http://code.google.com/apis/maps/signup.html) or Yahoo Application ID (http://developer.yahoo.com/wsregapp/). First of all you have to include the resource tag which supports the following attributes:

• key (your GoogleMaps key or Yahoo Application ID) required, Note: Microsoft Virtual Earth doesn't require a key
• version (GoogleMaps, Yahoo Maps or Microsoft Virtual Earth version, defaults to 2.x for GoogleMaps, 3.8 for Yahoo Maps and 6.2 for Microsoft Virtual Earth)

• type (Map renderer, can be GoogleMaps, YahooMaps and MicrosoftVirtualEarth, defaults to GoogleMaps)
• lat (latitude)
• lng (longitude)
• zoomLevel (initial map zoom level, defaults to 13)
• search (enable/disable search functionality, can be true or false, defaults to false)
• draggable (determines if markers can be moved, can be true or false, defaults to false)
• route (enable/disable driving directions, can be true or false, defaults to false)
• directionsLocale (locale for driving directions, can be something like fr, de_DE, en_US etc., defaults to request locale)
• class (CSS class for the whole component including search etc.)
• style (CSS style for the whole component including search etc.)
• mapStyleClass (CSS class for the map itself)
• mapStyle (CSS style for the map itself)
• markers (A list of maps of markers which should be displayed)
• latId (DOM id of a HTML input tag to display current latitude)
• lngId (DOM id of a HTML input tag to display current longitude)
• showStartMarker (specifies whether start position should be displayed or not, can be true or false, defaults to true)

• type (Map renderer, can be GoogleMaps, YahooMaps and MicrosoftVirtualEarth, defaults to GoogleMaps)
• lat (latitude)
• lng (longitude)
• zoomLevel (initial map zoom level, defaults to 13)
• mapStyleClass (CSS class for the map itself)
• mapStyle (CSS style for the map itself)
• markers (A list of maps of markers which should be displayed)

Example

GSP:

<resource:map type="GoogleMaps" key="your key" />

Map with search functionality

<richui:map type="GoogleMaps" lat="40.689299" lng="-74.044" search="true" />

Map with driving directions

<richui:map lat="40.689299" lng="-74.044" route="true" />

Map with markers

<richui:map markers="${[[latitude: 40.689299, longitude: -74.044, draggable: true, description: 'Statue of Liberty'],
[latitude: 40.69575, longitude: -74.056257, draggable: false, description: 'Liberty State Park']]}" />

Yahoo Maps

<resource:map type="YahooMaps" key="your application id" />
<richui:map type="YahooMaps" markers="${[[latitude: 40.689299, longitude: -74.044, description: 'Statue of Liberty'],
[latitude: 40.69575, longitude: -74.056257, description: 'Liberty State Park']]}" />

Microsoft Virtual Earth

<resource:map type="MicrosoftVirtualEarth" />
<richui:map type="MicrosoftVirtualEarth" markers="${[[latitude: 40.689299, longitude: -74.044, description: 'Statue of Liberty'],
[latitude: 40.69575, longitude: -74.056257, description: 'Liberty State Park']]}" />

Choose global renderer

You can omit the type attribute on the resource:map and richui:map tag and set the renderer instead globally by adding one of the following lines to grails-app/conf/Config.groovy.

//richui.mapRenderer="de.andreasschmitt.richui.taglib.renderer.GoogleMapsRenderer"
//richui.mapRenderer="de.andreasschmitt.richui.taglib.renderer.YahooMapsRenderer"
richui.mapRenderer="de.andreasschmitt.richui.taglib.renderer.MicrosoftVirtualEarthRenderer"

Customization

In order to display localized labels for search functionality and driving directions add the following lines to your

messages.properties:map.search.search=Search
map.search.ok=OK
map.route.start=Start
map.route.destination=Destination
map.route.ok=OK
map.route.clear=Clear

Portlet

This tag allows you to build a user interface similar to iGoogle where content can be positioned via drag and drop. It is based on YUI.

To use the Portlet component include the following markup in your GSP.

<resource:portlet />
...
<richui:portlet views="[1, 2, 3, 4]" action="changeView" readOnly="false">
    <table style="width: 500px; border: none;">
        <tr>
            <td>
                <richui:portletView id="1" slotStyle="width: 250px; height: 250px;" playerStyle="width: 250px; height: 250px;">
                <h1>Content 1</h1>
                ...
                <img width="140" height="42" src="${createLinkTo('dir': 'images', file: 'grails_logo.jpg')}"/>
                </richui:portletView>
            </td>
            <td>
                <richui:portletView id="2" slotStyle="width: 250px; height: 250px;" playerStyle="width: 250px; height: 250px;">
                <h1>Content 2</h1>
                …
                </richui:portletView>
            </td>
        </tr>
        <tr>
            <td>
                <richui:portletView id="3" slotStyle="width: 250px; height: 250px;" playerStyle="width: 250px; height: 250px;">
                <h1>Content 3</h1>
                …
                </richui:portletView>
            </td>
            <td>
                <richui:portletView id="4" slotStyle="width: 250px; height: 250px;" playerStyle="width: 250px; height: 250px;">
                <h1>Content 4</h1>
                …
                </richui:portletView>
            </td>
       </tr>
    </table>
</richui:portlet>

This will a table containing four portletViews which can be moved via drag & drop. The Portlet tag supports the following attributes:

• views (portletView ids as list) required
• action (action which should be called when a view is dropped)
• readOnly (specifies whether drag & drop moving is enabled, can be true or false, defaults to false)
• page (page identifier if multiple portlets are used e.g. in a tab view, defaults to 1)

• id (view identifier, corresponds to one of the views list entries in the Portlet-tag) required
• slotStyle (CSS style of a content slot, which is the container for the movable part)
• slotClass (CSS class of a content slot, which is the container for the movable part)
• playerStyle (CSS style of a content player, which is moveable)
• playerClass (CSS class of a content player, which is moveable)

Example

GSP:

<resource:portlet />
…
<richui:portlet views="[1, 2]" action="changeView" readOnly="false">
    <richui:portletView id="1" slotStyle="width: 250px; height: 250px;" playerStyle="width: 250px; height: 250px;">
        <h1>Content 1</h1>
        ...
        <img width="140" height="42" src="${createLinkTo('dir': 'images', file: 'grails_logo.jpg')}"/>
    </richui:portletView>
    <richui:portletView id="2" slotStyle="width: 250px; height: 250px;" playerStyle="width: 250px; height: 250px;">
        <h1>Content 2</h1>
        …
    </richui:portletView>
</richui:portlet>

PortletControllerclass PortletController {
    def changeView = {
        //Obtain id of view which has been moved (could be "1")
    	String drag = params.drag
        //Obtain id of view where view has been moved to (could be "slot_1_2")
        //where 1 stands for page 1 and 2 is view with id 2
        String drop = params.drop
        //Persist new view positions
        …
    }
}

Customization

If you don't like the standard skin of the portlet you can change it by adding a skin attribute to the resource tag.

Default skin

<resource:portlet />

User defined skin

<resource:portlet skin="user" />

The last option allows you to use your own stylesheet. See webapp/css/portlet.css in the plugin directory for an example.

Redirect ^

The redirect tag allows you to redirect to another URL.

To use the Redirect tag include the following markup in your GSP.

<richui:redirect url="${createLinkTo(dir:'login')}" />

This will redirect to the login page (login controller). The Redirect tag supports the following attributes:

• url (to redirect to) required

ReflectionImage

This tag adds reflection to images. It is based on http://cow.neondragon.net/stuff/reflection/.

To use the ReflectionImage tag include the following markup in your GSP. NOTE: Don't put resource tag into your HTML <head>, because it won't work

<resource:reflectionImage />
<richui:reflectionImage src="${createLinkTo('dir': 'images', file: 'grails_logo.jpg')}" />

This will render a reflection for the image specified in src. The ReflectionImage tag supports the following attributes and can be used in the same way as a normal img-tag, because all attributes will be passed through:

• src (image source) required
• reflectionHeight (reflection height in percent, can be an integer, defaults to 50)
• reflectionOpacity (reflection opacity in percent, can be an integer, defaults to 80)

Example

GSP:

NOTE: Don't put resource tag into your HTML <head>, because it won't work

<resource:reflectionImage />
<richui:reflectionImage src="${createLinkTo('dir': 'images', file: 'grails_logo.jpg')}" reflectionHeight="30" reflectionOpacity="50" />

RichTextEditor

This tag provides a rich text editor component to enable users to format content. The editing features are not intended to be as sophisticated as those of the FCKeditor plugin. It is based on TinyMCE or YUI.

To use the RichTextEditor component include the following markup in your GSP.

<resource:richTextEditor />
...
<richui:richTextEditor name="description" value="${note?.description}" width="525" />

This will render the RichTextEditor component. The RichTextEditor tag supports the following attributes:

• name (editor name) required
• id (HTML id, defaults to name)
• value (editor content)
• height (editor height in pixels)
• width (editor width in pixels)

• type (editor type, can be simple first screenshot_, medium _second screenshot_, advanced _third screenshot or full _last screenshot_)

Example

GSP:

<resource:richTextEditor type="advanced" />
...
<richui:richTextEditor name="description" value="${note?.description}" width="525" />

This component also supports pass through attributes. That means you can pass HTML attributes directly to the underlying textarea by using the prefix html.

Example

<resource:richTextEditor type="advanced" />
...
<richui:richTextEditor name="description" value="${note?.description}" width="525" html:title="This editor fields also allows formatted text." />

Customization

To use YUI's RichTextEditor exchange the following line in grails-app/conf/RichuiConfig.groovy:richTextEditorRenderer: "de.andreasschmitt.richui.taglib.renderer.RichTextEditorRenderer", withrichTextEditorRenderer: "de.andreasschmitt.richui.taglib.renderer.RichTextEditorYUIRenderer",

Star rating

This tag provides a star rating component to enable users to rate content. It is based on http://www.masugadesign.com/the-lab/scripts/unobtrusive-ajax-star-rating-bar.

To use the StarRating component include the following markup in your GSP.

<resource:rating />
...
<richui:rating dynamic="false" units="5" rating="2" showCurrent="false" controller="rating" action="rate" />

This will render the star rating component displaying 5 stars and a current rating of 2 stars. The component is dynamic which means a user can rate and this rating will be asynchronusly submitted to controller rating and action rate. The StarRating tag supports the following attributes:

• dynamic (specifies whether rating can be modified or not, can be true or false, defaults to false)
• action (action to submit rating) required
• controller (controller to submit rating) required
• id (id of a domain object)
• showCurrent (shows current rating as text, can be true or false, defaults to false)
• units (determines the number of stars which will be displayed, can be 1-10, defaults to 5)
• rating (current rating, can be a double number, defaults to 0)
• noAjax (determines if rating should be stored in a form field instead of sending an AJAX request, can be true or false, defaults to false)
• inputId (id of an input form field where the rating is stored, only valid if noAjax ist set to true)

Example

GSP:

<resource:rating />
...
<g:render template="rate" model="[song: song, rating: '2']" />
Template (e.g. _rate.gsp):<richui:rating dynamic="true" id="${song.id}" units="3" rating="${rating}" controller="rating" action="rate" />

Controller:class RatingController {
    def rate = {
        //Get rating value
        def rating = params.rating
        //Compute new average value
        ...
        //Use domain id to obtain domain object
        Song song = Song.get(new Long(params.id))
        //Save new rating
        ...

        //Render template with new average rating
        render(template: "rate", model: [rating: average])
    }
}

TabView

This component creates tabbed views. It is based on YUI.

To use the TabView component include the following markup in your GSP.

<resource:tabView />
...
<richui:tabView id="tabView">
    <richui:tabLabels>
        <richui:tabLabel selected="true" title="My Tab 1" />
        <richui:tabLabel title="Tab 2" />
        <richui:tabLabel title="Tab 3" />
    </richui:tabLabels>
    <richui:tabContents>
        <richui:tabContent>
	    <h1>My Tab 1</h1>
            This is tab 1.
	</richui:tabContent>
	<richui:tabContent>
	    And this is tab 2.
	</richui:tabContent>
	<richui:tabContent>
	    This is tab 3.
            <g:link action="list">A link</g:link>
	</richui:tabContent>
    </richui:tabContents>
</richui:tabView>

This will render a TabView with three tabs My Tab 1, Tab 2 and Tab 3. The TabView tag supports the following attributes:

• id (DOM id for generated div)

• selected (specifies which tag is initially selected, can be true or false)
• title (title of the tab) required

Customization

If you don't like the standard skin of the tab view you can change it by adding a skin attribute to the resource tag.

Default YUI skin

<resource:tabView />

Default RichUI skin (uses webapp/css/tabView.css, webapp/js/yui/fonts/fonts-min.css and webapp/js/yui/tabview/assets/tabview-core.css in the plugin directory)

<resource:tabView skin="default" />

Custom

<resource:tabView skin="custom" />

The last option allows you to use your own stylesheet. See webapp/css/tabView.css in the plugin directory for an example.

TagCloud

This component creates a tag cloud displaying the occurrences of tags.

To use the TagCloud component include the following markup in your GSP.

<richui:tagCloud values="['Java': 5, 'Grails': 16, 'Groovy': 12]" />

This will render a tag cloud displaying the tags Java, Grails and Groovy. The TagCloud tag supports the following attributes:

• values (the values to display) required
• class (CSS class)
• style (CSS style)
• linkClass (CSS link class)
• linkStyle (CSS link style)
• controller (controller to which selected tag should be submitted)
• action (action to which selected tag should be submitted)
• sortField (specifies whether tags will be sorted by key or value, can key or value, defaults to key)
• sortOrder (specifies sort order, can asc and desc, defaults to asc)
• minSize (minimum tag font size, can be an integer, defaults to 0)
• maxSize (maximum tag font size, can be an integer, defaults to 50)
• showNumber (specifies whether ocurrence of a tag should be displayed or not, can be true or false, defaults to false)

Example

GSP:

<style>
.tag {
    height: 150px; background: #DDDDDD; border: 1px solid #BBBBBB; width: 400px;
}
.tagLink {
    text-decoration: none; margin-left: 3px; margin-right: 3px; color: #656565;
}
</style>
<richui:tagCloud values="['Java': 5, 'Grails': 16, 'Groovy': 12]" class="tag" linkClass="tagLink" controller="tag" action="filter" sortField="key" sortOrder="desc"/>

Controller:class TagController {
    def filter = {
        //Get selected tag
        String tag = params.selectedTag
        …
    }
}

Timeline

This component creates a timeline which shows events. It is based on SIMILE.

To use the Timeline component include the following markup in your GSP.

<resource:timeline />
...
<body onload="initTimeline();">
<richui:timeline style="height: 350px; border: 1px solid #aaa" datasource="http://localhost:8080/richuitest/person/events" />

This will render a SIMILE timeline using http://localhost:8080/richuitest/person/events as datasource. The Timeline tag supports the following attributes:

• startDate (initial date position, can be a Date defaults to new Date())
• datasource (XML data which specifies events that will be displayed) required
• class (CSS class)
• style (CSS style)
• eventBandWidth (width of the event band in percent, defaults to 70)
• eventIntervalUnit (specifies the unit of an interval, can be day, week, month and year, defaults to month)
• eventIntervalPixels (width of an interval in pixels, defaults to 100)
• legendBandWidth (width of the legend band in percent, defaults to 30)
• legendIntervalUnit (specifies the unit of an interval, can be day, week, month and year, defaults to year)
• legendIntervalPixels (width of an interval in pixels, defaults to 200)
• eventBandSpanHighlightDecorators ()
• eventBandPointHighlightDecorators ()
• legendBandSpanHighlightDecorators ()
• legendBandPointHighlightDecorators ()

<body onload="${pageProperty(name:'body.onload')}">

Example

GSP:

<resource:timeline />
...
<body onload="initTimeline();">
<richui:timeline style="height: 350px; border: 1px solid #aaa" startDate="${new Date() - 20}" datasource="http://localhost:8080/richuitest/person/events" eventBandWidth="85" eventIntervalPixels="200" legendBandWidth="15" legendIntervalPixels="500" eventIntervalUnit="month" legendIntervalUnit="year" />
<richui:timeline style="height: 350px; width: 450px; border: 1px solid #aaa" startDate="${new Date() - 70}" 
            datasource="http://localhost:8080/richuitest/person/events" eventBandSpanHighlightDecorators="[[date: new Date() + 7, startDate: new Date(), endDate: new Date() + 100, color: '#FFFF00', opacity: 50, startLabel: 'Sample', endLabel: 'End sample'], [date: new Date() + 14, startDate: new Date() + 20, endDate: new Date() + 25, color: '#0000FF', opacity: 50, startLabel: 'Sample', endLabel: 'End sample']]" />

Controller:

import java.text.SimpleDateFormat
class PersonController {
    def events = {
        render(contentType: "text/xml") {
            data() {
                //Special date format which is needed for the timeline control
	        String startDate = new SimpleDateFormat("MMM dd yyyy HH:mm:ss", Locale.US).format(new Date()) + " GMT"
		event('start': startDate, 'title':"Nice title", 'link':"http://localhost:8080/richuitest/person/show/1", "This is a description")
                startDate = new SimpleDateFormat("MMM dd yyyy HH:mm:ss", Locale.US).format(new Date() + 20) + " GMT"
                event('start': startDate, 'title':"Hello World", 'link':"http://localhost:8080/richuitest/person/show/2", "This is another description")
                //Start and end date
                startDate = new SimpleDateFormat("MMM dd yyyy HH:mm:ss", Locale.US).format(new Date() + 40) + " GMT"
                String endDate = new SimpleDateFormat("MMM dd yyyy HH:mm:ss", Locale.US).format(new Date() + 45) + " GMT"
                event('start': startDate, 'end': endDate, 'title':"Hello again", 'link':"http://localhost:8080/richuitest/person/show/3", "This is another description")
//A custom icon and color
event('start': startDate, 'title':"Hello again", 'link':"http://localhost:8080/richuitest/person/show/3", textColor: "#FF0000", color: "#FFFF00", icon:"http://simile.mit.edu/timeline/api/images/dark-red-circle.png", "This is another description")
	    }
        }
    }
}

Tooltip

This component creates a JavaScript tooltip.It is based on YUI.

To use the Tooltip component include the following markup in your GSP.

<resource:tooltip />
...
<a id="sample" href="#" title="This is a tooltip">A link</a>
<richui:tooltip id="sample" />

This will show a tooltip when you hover over the link. The Tooltip tag supports the following attributes:

• id (DOM id of the HTML element for which the tooltip should be displayed. The text is specified via the HTML title attribut) required

TreeView

This component creates a tree view based on data given in XML. It is based on YUI.

To use the TreeView component include the following markup in your GSP.

<resource:treeView />
...
<richui:treeView id="tree" xml="${data}"/>

This will display a tree view displaying the data specified in data. The TreeView tag supports the following attributes:

• id (DOM id of the div)
• xml (data which should be displayed) required
• onLabelClick (a javascript function which is called when a node label is clicked, variable id is available if specified in controller)
• showRoot (determines whether root node should be displayed or not, can be true or false)

Example

GSP:

<resource:treeView />
...
<richui:treeView xml="${data}"/>
<richui:treeView xml="${data}" onLabelClick="document.location.href = '${createLinkTo(dir: 'person/show')}/' + id;"/>
<richui:treeView xml="${data}" onLabelClick="if(node.depth == 2) document.location.href = '${createLinkTo(dir: 'person/show')}/' + id;"/>

Controller:

import groovy.xml.MarkupBuilder
class PersonController {
    def list = {
    	def writer = new StringWriter()
	def xml = new MarkupBuilder(writer)
    	xml.person(name: "John Doe"){
    	    books(name: "Books"){
    	        book(name:"Book 1")
                //Optional id
    		book(name:"Book 2", id: 1)
    	    }
    	}
        if(!params.max)params.max = 10
        [ "data": writer.toString(), personList: Person.list( params )]
    }
}

Customization

If you don't like the standard skin of the tree view you can change it by adding a skin attribute to the resource tag.//Default YUI skin

<resource:treeView />

Default RichUI skin (uses webapp/css/treeView.css in the plugin directory)

<resource:treeView skin="default" />

Custom

<resource:treeView skin="custom" />

The last option allows you to use your own stylesheet. See webapp/css/treeView.css in the plugin directory for an example. You can also modify this file directly if you like and use the second option.

Plugin version history ^

• Feb. 04, 2009 (version 0.6)
• Global renderer configuration
• googlemaps component renamed to map and support for Yahoo Maps and Microsoft Virtual Earth
• Timeline supports highlighting of events
• Bug fixes
• AutoComplete onItemSelect
• Dec. 31, 2008 (version 0.5)
• Pass through attributes for AutoComplete, DateChooser and RichTextEditor
• All components are skinnable using a skin convention
• Support for serving YUI resource files remotely
• Calendar beta components (CalendarMonthView, CalendarWeekView and CalendarDayView added)
• YUI updated to 2.6
• StarRating can store rating in form field (no AJAX mode)
• Many improvements and bug fixes thanks to contributions from community members
• CheckedTreeView
• DateChooser improvements
• More supported date formats
• timezone attribute
• Possibility to enter time
• Apr. 24, 2008 (version 0.4)
• Accordion added
• Timeline supports eventBandWidth, eventIntervalUnit, eventIntervalPixels, legendBandWidth, legendIntervalUnit and legendIntervalPixels
• Bug fixes
• Grails, RichUI & existing HBM-Files
• TagCloud controller attribute has no effect
• Mar. 31, 2008 (version 0.3)
• Timeline javascript files are now served locally
• Mar. 24, 2008 (version 0.3)
• Updated to Grails 1.0.2
• YUI updated to 2.5.1
• AutoComplete supports forceSelection, typeAhead and title (thanks to Sanjay Mysoremutt)
• DateChooser supports firstDayOfWeek setting
• New components
• Carousel
• Flow
• Portlet
• ReflectionImage
• RichTextEditor
• Feb. 05, 2008 (version 0.2)
• Updated to Grails 1.0
• Jetty issue fixed
• TagCloud issue fixed
• Rating component improved
• Jan. 23, 2008 (version 0.2)
• AutoComplete supports onItemSelect attribute to specify a custom javascript function
• DateChooser defaults to no date and locale defaults to request locale
• GoogleMaps directionsLocale defaults to request locale
• TreeView supports onLabelClick attribute to specify a custom javascript function
• Bug fixes
• Jan. 6, 2008 (version 0.1)
• Initial version released Comments &nbsp;Hide Comments | dellsoft Jan 06, 2008 07:32

User Comments

Jan 15, 2008 19:55, Updated by Carl Garcia

>grails install-plugin http://svn.codehaus.org/grails-plugins/grails-richui/tags/LATEST_RELEASE/grails-richui-0.1.zip

Feb 17, 2008 04:39, Juha Mynttinen

Mar 03, 2008 02:45, Sanjay Mysoremutt

"Enter the number to search for"  name="queryTxt" action="${createLinkTo('dir': 'claim/searchFileNumber')}"/>"searchClaim" value="search claim"  title="Search for the specified claim"/>
  "queryTxt"/>

...was not working… The tooltip depends on a title attribute, which autocomplete wasn't rendering. Fixed this by adding the following code

title: "${attrs?.title}", "")

in:

• Projectpluginsrichui-0.2srcgroovydeandreasschmittrichuitaglibrendererAutoCompleteRenderer.groovy
• Class: de.andreasschmitt.richui.taglib.renderer.AutoCompleteRenderer
  
• Method:

protected void renderTagContentbuilder."div"(""){
            input("class": "${attrs?.'class'}", style: "${attrs?.style}",
                   type: "text", id: "${attrs?.id}", name: "${attrs?.name}",
                    value: "${attrs?.value}", title: "${attrs?.title}", "")
            "div"("class": "searchcontainer yui-skin-sam", id: resultId, ""){}Also added        if(!attrs?.title){
            attrs.title = ""
        }

And then it worked fine. (Thanks a lot for these wonderful excellent plugins!)

Mar 03, 2008 05:13, Sanjay Mysoremutt

Objective was to use this in the controller:

def persons = Person.findAllByNameLike("%${params.query}%")
render(persons as XML)

Needed the introduction of two new attributes objectName and columnName

<richui:autoComplete name="person" objectName="person" columnName="name" action="${createLinkTo('dir': 'person/searchPerson')}" />

Changes required in local copy of the plugin. Added the following in AutoCompleteTagLib.groovy

if(!attrs?.objectName){
            attrs.objectName = "result"
}

Jun 15, 2008 19:13, killes

if(attrs?.params){
builder.yieldUnescaped " autoCompleteDataSource.scriptQueryAppend = "${attrs?.params}";n"
}

to

if(attrs?.params){
def iter = attrs?.params.iterator()
def inputString = iter.next().toString().replace('{','').replace('}','')
while( iter.hasNext()) {
inputString = inputString + '&' + iter.next().toString().replace('{','').replace('}','')
}
builder.yieldUnescaped " autoCompleteDataSource.scriptQueryAppend = "${inputString}";n"
}

June 14, 2008, Dan Tanner

July 05, 2008, Andreas Schmitt

July 21, 2008, Greg Ball

July 29, 2008, Andreas Schmitt

August 25, 2008, Chris Fraser

October 18, 2008, Andreas Schmitt

November 25, 2008, Andreas Schmitt