GridSphere Tag Library User's Guide

List of Tables

2.1. Base Tag Attributes
2.2. Attributes to actionlink
2.3. Attributes to actionsubmit
2.4. Attributes to actionparam
2.5. Attributes to panel
2.6. Attributes to table
2.7. Attributes to table row
2.8. Attributes to table cell
2.9. Attributes to frame
2.10. Attributes to checkbox
2.11. Attributes to hiddenfield
2.12. Attributes to fileinput
2.13. Attributes to textfield
2.14. Attributes to password field
2.15. Attributes to radiobutton
2.16. Attributes to textarea
2.17. Attributes to text
2.18. Attributes to listbox
2.19. Attributes to listboxitem
2.20. Attributes to image
2.21. Attributes to messagebox
2.22. Supported validator types
2.23. Attributes to validator
2.24. Attributes to group
2.25. Attributes to datagrid
2.26. Attributes to datagridcolumn
2.27. Attributes to ActionMenuTag
2.28. Attributes to datagrid
2.29. Attributes to actionpanetag
3.1. Base Bean Attributes

List of Examples

2.1. GridSphere UI tag usage
2.2. JSR 168 UI tag usage
2.3. Usage of actionlink
2.4. Usage of actionsubmit
2.5. Usage of actionparam
2.6. Usage of form
2.7. Usage of fileform
2.8. Usage of panel
2.9. Usage of table
2.10. Usage of table row
2.11. Usage of table cell
2.12. Usage of frame
2.13. Usage of checkbox
2.14. Usage of hiddenfield
2.15. Usage of fileinput
2.16. Usage of textfield
2.17. Usage of password field
2.18. Usage of radiobutton
2.19. Usage of textarea
2.20. Usage of text
2.21. Usage of listbox
2.22. Usage of listboxitem
2.23. Usage of image
2.24. Usage of messagebox
2.25. Usage of validator
2.26. Usage of group
2.27. Usage of datagrid
2.28. Usage of datagrid
2.29. Usage of ActionMenuTag
2.30. Usage of ActionMenuItemTag
2.31. Usage of ActionMenuTag
3.1. Usage of visual beans from a portlet

Chapter 1. Introduction

The GridSphere UI tag and visual bean library makes it easier to develop portlets using the GridSphere Action portlet provider model described in the Tutorial. The UI tag library is used to construct interfaces as visual components that wrap underlying HTML elements with a default look and feel. The visual beans provide bean representations of the tags to be used in portlets for action handling or presentation logic. This reference guide is intended to summarize UI tag and bean usage.

The JSR 168 Portlet Specification also provides a collection of portlet tags that are implemented in GridSphere. Please see the specification for more details.

Chapter 2. GridSphere UI Tag Library

GridSphere UI tags are JSP tags that can be used in a JSP page to create user interfaces. The UI tag library descriptor which defines tag parameters and definitions can be found in webapps/gridsphere/WEB-INF/tlds/portletui.tld of the source directory. All tags may contain a beanId attribute. The valueof beanId is a String that identifies the tag so it may be retrieved as a visual bean in the portlet. See the Tutorial for an example.

Usage on GridSphere UI Tags

The UI tags may be used in both WebSphere portlets or JSR 168 compatible portlets. The following code snippets show the imports that must be included at the beginning of a JSP page to import the UI and portlet tag libraries.

Example 2.1. GridSphere UI tag usage


<%@ taglib uri="/portletUI" prefix="ui" %>
<%@ taglib uri="/portletAPI" prefix="portletAPI" %>
<portletAPI:init/>

Now the tags can be used within a JSP by using the "ui" reference specified in the taglib directive. The portletAPI directive and tag initialization make the portlet objects available to the tags.

Example 2.2. JSR 168 UI tag usage


<%@ taglib uri="/portletUI" prefix="ui" %>
<%@ taglib uri="http://java.sun.com" prefix="portlet" %>
<portlet:defineObjects/>

Now the tags can be used within a JSP by using the "ui" reference specified in the taglib directive. The portletAPI directive and tag initialization make the portlet objects available to the tags.

Base Tag Attributes

In general all UI tags inherit from a BaseComponentTag which provides various attributes for setting the look and feel, labels and values. Below is a list of the basic tag attributes, however not all are used for every UI tag. The beanID tag attribute can be used in every UI tag and provides a label for accessing the tag as a visual bean from the portlet. See the section on visual beans for more details.

Table 2.1. Base Tag Attributes

Attribute name	Required?	Description
beanID	no	string: a label used to express this component as a visual bean that can be made available to the portlet.
name	no	string: a name for this component. Generally this uses the underlying name attribute of the corresponding HTML element
value	no	string: the value of this component. Generally this uses the underlying value attribute of the corresponding HTML element
readonly	no	boolean: true if this component is intended to be read-only, false otherwise
disabled	no	boolean: true if this component is intended to be disabled, false otherwise
cssStyle	no	string: the CSS style to use for rendering this component

	Important
	Due to the way that GridSphere encodes beans, you MUST NOT use "_" in the beanID variables!

Action Tags

As discussed in the Tutorial, action tags are used to send actions back to portlets to trigger a particular sequence of logic operations. An action can come in 2 flavors, an actionlink or an actionsubmit. An action tag provides two attributes that are used to generate the appropriate action. A label attribute can be used to link to another portlet component. Action tags may also specify a secure attribute which indicates if this link or form should specify "http" or "https" access. An action attribute provides an action name that is made available to the Portlet via the ActionEvent object. Both action tags may also contain one or more actionparam tags to define action parameters. The trackme label is used to record to the database information about the link being clicked including client browser, timestamp, label and user information if available. The exturl can provide an external URL to redirect to.

ActionLink

This tag creates an actionlink which is a hyperlink containing an action name and possibly action parameters.

Table 2.2. Attributes to actionlink

Attribute name	Required?	Description
action	no	string: name of the action
label	no	string: component label
secure	no	boolean: if set to true, the link is "https", otherwise it is "http".
key	no	string: the key used to identify a value from the localized properties file located in `WEB-INF/classes/Portlet_XX.properties` of the portlet web application.
value	no	string: the value that is displayed in the hyperlink. The key attribute should be used wherever possible to provide localized string values.
name	no	string: adds a link target name to the hyperlink that can be specified by the anchor attribute.
anchor	no	string: adds an anchor to the actionsubmit element identified by a "#" plus the anchor for the link target.
onClick	no	string: adds a javascript onclick event handler.
useAjax	no	boolean: if true, this action will return only the markup fragment for this portlet using AJAX awithout refreshing the entire page
trackme	no	string: a label to define the action being tracked. Information including timestamp, client browser, user (if exists) and the trackme label are all persisted to the database. This provides a way to identify actions in the portal that an admin can later gather statistics on thru the ActionTrackingPortlet (when writtem ;-)
exturl	no	string: provide an external url that the portal will redirect to. Generally this is used in conjunction with "trackme" attribute to record an action before redirecting to external site. If exturl is specified, no action attribute needs to be set. In all other cases, an action must be assigned.

Example 2.3. Usage of actionlink


<ui:actionlink action="doActionLink" key="DOIT"/>

This example would create an html hyperlink pointing to the current portlet with a clickable localized text value DOIT that will trigger the doActionLink method to be performed in the portlet.


<ui:actionlink action="doActionLink" trackme="clickme">Click Me</ui:actionlink>

This example would create an html hyperlink pointing to the current portlet with a clickable text value of "Click Me" as specified in the body of the tag. The action will be recorded in the database under the "clickme" label.


<ui:actionlink exturl="http://www.google.com" trackme="google">Go to Google</ui:actionlink>

This example will create an external link to take the user to the Google website and record the user's navigation in the database under the "google" label. Note that no action needs to be specified, since a redirection occurs.


<ui:actionlink beanId="myAction" action="doActionLink" key="DOIT"/>

By providing a beanId, the tag will first check for the existence of a myAction ActionLinkBean that would have been created by the portlet and uses that first. Otherwise one is created using the specified default values.


<ui:actionlink secure="true" label="login">Click to login</ui:actionlink>

This example would create a secure "https" html hyperlink pointing to the Login portlet (as defined by label="login" in the layout descriptor file) with a clickable text value of "Click to login" as specified in the body of the tag.


<ui:actionlink label="login" action="doSomething">Click to login and doSomething</ui:actionlink>

This example would create an html hyperlink pointing to the Login portlet (as defined by label="login" in the layout descriptor file) that would also invoke the doSomething method of the Login portlet.


<ui:actionlink useAjax="true" action="doSomething">Click to do something</ui:actionlink>

This example will invoke the "doSomething" action method of the portlet and modify only the markup for this portlet using AJAX (the XMLHttpRequest object is used to return the fragment and the DOM is manipulated to add the modified markup)

ActionSubmit

This tag creates a button that triggers an action event

Table 2.3. Attributes to actionsubmit

Attribute name	Required?	Description
action	yes	string: name of the action
secure	no	boolean: if set to true, the link is "https", otherwise it is "http".
key	no	string: the key used to identify a value from the localized properties file located in `WEB-INF/classes/Portlet_XX.properties` of the portlet web application.
value	no	string: the value that is displayed in the hyperlink. The key attribute should be used wherever possible to provide localized string values.
name	no	string: the name of the actionsubmit element.
onClick	no	string: adds a javascript onclick event handler.
useAjax	no	boolean: if true, this action will return only the markup fragment for this portlet using AJAX awithout refreshing the entire page
anchor	no	string: adds an anchor to the actionsubmit element identified by a "#" plus the anchor for the link target.

Example 2.4. Usage of actionsubmit

                    <ui:actionsubmit action="doActionLink" key="DOIT"/>

This example would create a button displayed with the localized text from the key DOIT that will trigger the doActionLink method to be performed in the portlet.

               <ui:actionsubmit useAjax="true" action="doSomething">Click to do something</ui:actionsubmit>

ActionParam

This tag creates a an action parameter that may be nested inside an actionlink, an actionsubmit, or a form tag. An action parameter is simply a string name-value pair.

Table 2.4. Attributes to actionparam

Attribute name	Required?	Description
name	yes	string: the action parameter name
value	yes	string: the action parameter value

Example 2.5. Usage of actionparam


         <ui:actionsubmit action="doActionLink" key="DOIT">
            <ui:actionparam name="somename" value="avalue"/>
            <ui:actionparam name="anothername" value="anewvalue"/>
         </ui:actionsubmit>

This example would create a button that when triggered will invoke the doActionLink method of the portlet and also contains additional action parameters.

                
         <ui:actionsubmit action="doActionLink" key="DOIT">
            <ui:actionparam name="somename" value="avalue"/>
            <ui:actionparam name="anothername" value="anewvalue"/>
         </ui:actionsubmit>

This example is the same as above, but triggers the event in the portlet identified by the "aportlet".

Form

The form tag is used to create a form and can contain other UI tags as well as actionparam tags specifying action parameters. If a form tag contains a actionsubmit tag, then the action specified in the actionsubmit will override any action specified in the form tag. A form tag may also specify a label that will cause the form event to be sent to the portlet component identified by the label as specified in the layout descriptor file. The form tag also supports the secure attribute to indicate if this form should be processed over http or https. The attributes "trackme" and "exturl" are also supported as described in the actionlink tag section.Event handlers may be supported using the onSubmit tag attribute specifying a javscript function to invoke when a form is submitted.

Example 2.6. Usage of form


<ui:form action="doSomeAction">
...
</ui:form>

Creates a form that when submitted will invoke the "doSomeAction" method of the current portlet.


<ui:form secure="true" label="login" trackme="login">
...
</ui:form>

Creates a secure form that when submitted will invoke the portlet component as identified by the "login" attribute. The action will be recorded to the database by the login label specified in the trackme attribute.

FileForm

The file form tag is used to create a form that is used to accept multi-part mime encoded upload files. Generally, a fileinput tag is nested inside a fileform tag to allow access to the uploaded file from a fileinput bean. Please see fileinput tag for more information. Currently since files are uploaded as part of the servlet request, it's not possible to embed other tag elements inside of a fileform tag. We are hoping to remedy this shortcoming soon!

Example 2.7. Usage of fileform


<ui:fileform action="uploadFile">
        <ui:frame>
            <ui:tablerow>
                <ui:tablecell width="100">
                    <ui:text value="File: "/>
                </ui:tablecell>
                <ui:tablecell width="60">
                    <ui:fileinput beanId="userfile" size="20" maxlength="20"/>
                </ui:tablecell>
                <ui:tablecell/>
            </ui:tablerow>
        </ui:frame>
 </ui:fileform>

UI Tags

The rest of the UI tags generally wrap existing HTML elements, such as the checkbox, radiobutton, textfield tags. The panel and frame tags are container tags for other tag elements. A reasonably nice interface can be constructed by placing elements within forms within frames within panes as shown in the following code:


        <ui:form>
            <ui:panel>
                <ui:frame>
                   <ui:tablerow>
                      <ui:tablecell width="5%">
                          <ui:checkbox beanId="myCheckbox" value="somevalue"
                                       selected="true"/>
                      </ui:tablecell>
                   </ui:tablerow>
                </ui:frame>
                <ui:frame>
                   <ui:tablerow>
                       <ui:tablecell width="5%">
                           <ui:radiobutton beanId="myRadio" value="whatever"/>
                       </ui:tablecell>
                   </ui:tablerow>
                </ui:frame>
                <ui:frame>
                    <ui:tablerow>
                        <ui:tablecell width="100">
                            <ui:actionsubmit action="submit" key="SUBMIT_ACTION"/>
                        </ui:tablecell>
                    </ui:tablerow>
                </ui:frame>
            </ui:panel>
        </ui:form>

Panel

A panel is a stylized table that contains frame tags. A panel acts as a base container element like that used in any graphic toolkit.

Table 2.5. Attributes to panel

Attribute name	Required?	Description
align	no	string: left, center, right, justify for horizontal alignment
width	no	integer: the width of the panel
cellspacing	no	integer: the cellspacing table width
cols	no	comma separated list of strings: the width and number of columns in the panel

Example 2.8. Usage of panel


<ui:panel>
    <ui:frame>
        ...
    </ui:frame>

    <ui:frame>
        ...
    </ui:frame>
</ui:panel>

This default panel creates a panel with two frames one on top of the other.


<ui:panel cols="50%, 50%">
            <ui:frame>
                ...
            </ui:frame>
            <ui:frame>
                ...
            </ui:frame>
</ui:panel>

This creates a panel with two frames side by side each of 50% width

Table

A table tag is a wrapper for a standard HTML table. A table tag may contain nested table row tags that themselves may contain table cell tags. In general the frame tag should be used instead of the table tag to create a common look and feel.

Table 2.6. Attributes to table

Attribute name	Required?	Description
align	no	string: left, center, right, justify for horizontal alignment
border	no	string: integer number of pixels to use as a border
background	no	string: location of an image to use as a background
width	no	integer: the width of the panel
cellspacing	no	integer: the cellspacing table width
sortable	no	boolean: if true then the data in the table can be sorted by header
title	no	string: specifies a table title using underlying HTML caption element
zebra	no	boolean: if true then every other row will be highlighted

Example 2.9. Usage of table


<ui:table>
    <ui:tablerow>
        <ui:tablecell>
            <ui:text value="Something"/>
        </ui:tablecell>
        <ui:tablecell>
            <ui:text value="And.."/>
            <ui:text value="  more Nothing"/>
        </ui:tablecell>
    </ui:tablerow>
</ui:table>

This creates a table consisting of a table row with two table cells displaying text messages

Table Row

A table row tag may contain nested table cell tags and is used within a table or frame tag.

Table 2.7. Attributes to table row

Attribute name	Required?	Description
header	no	boolean: true if this row is a header equivalent to <th> in HTML
zebra	no	boolean: true if this row should be darkened
align	no	string: left, center, right, justify for horizontal alignment
valign	no	string: top, middle, bottom or baseline for vertical alignment

Example 2.10. Usage of table row


<ui:table>
    <ui:tablerow>
        <ui:tablecell>
            <ui:text value="Something"/>
        </ui:tablecell>
        <ui:tablecell>
            <ui:text value="And.."/>
            <ui:text value="  more Nothing"/>
        </ui:tablecell>
    </ui:tablerow>
</ui:table>

This creates a table consisting of a table row with two table cells displaying text messages

Table Cell

A table cell tag is used inside of a table row tag. One or more table cell tags can be included in a table row tag. Any other tag may be contained inside a table cell tag.

Table 2.8. Attributes to table cell

Attribute name	Required?	Description
width	no	integer: the width of the cell
height	no	integer: the height of the cell
cellspacing	no	integer: the cellspacing table width
align	no	string: left, center, right, justify for horizontal alignment
valign	no	string: top, middle, bottom or baseline for vertical alignment

Example 2.11. Usage of table cell


<ui:table>
    <ui:tablerow>
        <ui:tablecell>
            <ui:text value="Something"/>
        </ui:tablecell>
        <ui:tablecell>
            <ui:text value="And.."/>
            <ui:text value="  more Nothing"/>
        </ui:tablecell>
    </ui:tablerow>
</ui:table>

This creates a table consisting of a table row with two table cells displaying text messages

Frame

A frame tag is a stylized table tag that performs the same purpose, but provides a default CSS look and feel and can be used to render messages if the key or value attribute has been specified. In general the frame tag should be used instead of the table tag to create a common look and feel. A frame tag may contain nested table row tags that themselves may contain table cell tags.

Table 2.9. Attributes to frame

Attribute name	Required?	Description
align	no	string: left, center, right, justify for horizontal alignment
width	no	integer: the width of the panel
cellspacing	no	integer: the cellspacing table width
sortable	no	boolean: if true then the data in the table can be sorted by header
zebra	no	boolean: if true then every other row will be highlighted
key	no	string: name of the key to lookup localized text from the `WEB-INF/classes/Portlet_XX.properties` localized properties file
value	no	string: actual text to display
style	no	string: the style to display text in. Possible values include `error`, `info` `alert`, `status` and `success`. The default style used is `info`

Example 2.12. Usage of frame

<ui:panel>
    <ui:frame>
        <ui:tablerow>
            <ui:tablecell>
                <ui:text value="Something"/>
            </ui:tablecell>
            <ui:tablecell>
                <ui:text value="And.."/>
                <ui:text value="  more Nothing"/>
            </ui:tablecell>
        </ui:tablerow>
    </ui:frame>
</ui:panel>

This creates a frame consisting of a table row with two table cells displaying text messages

<ui:panel>
    <ui:frame value="Something bad happened!" style="error">
</ui:panel>

This creates a frame that displays the specified error message in the error style.

<ui:panel>
    <ui:frame beanId="errorMessage">
</ui:panel>

This creates a frame that uses the "errorMessge bean to render itself. The errorMessage bean is created and values are set in the portlet. If no beanId of "errorMessage" has been defined (as in when the page is first displayed) then no frame will be rendered.

<ui:panel>
    <ui:frame sortable="true" zebra="true">
        <ui:tablerow>
            <ui:tablecell>
                <ui:text value="Oranges"/>
            </ui:tablecell>
            <ui:tablecell>
                <ui:text value="0.59"/>
            </ui:tablecell>
        </ui:tablerow>
        <ui:tablerow>
            <ui:tablecell>
                <ui:text value="Kiwis"/>
            </ui:tablecell>
            <ui:tablecell>
                <ui:text value="0.79"/>
            </ui:tablecell>
        </ui:tablerow>
    </ui:frame>
</ui:panel>

This creates a data frame of fruits and prices that can be sorted per column and creates "zebra" table rows where every other row is highlighted.

<ui:panel>
    <ui:frame value="Something bad happened!" style="error">
</ui:panel>

This creates a frame that displays the specified error message in the error style.

<ui:panel>
    <ui:frame beanId="errorMessage">
</ui:panel>

CheckBox

This tag displays a checkbox.

Table 2.10. Attributes to checkbox

Attribute name	Required?	Description
name	no	string: the checkbox name
value	yes	string: the checkbox value
selected	no	boolean: true if selected, default is false
disabled	no	boolean: true if disabled, default is false

Example 2.13. Usage of checkbox


<ui:checkbox name="name" value="value" selected="true" disabled="false"/>

This creates a selected checkbox with the name 'name' and the value 'value'.

<ui:checkbox name="myCheckBox" value="value #1" selected="true"/>
 <ui:checkbox name="myCheckBox" value="value #2"/>
 <ui:checkbox name="myCheckBox" value="value #3"/>

This creates multiple check boxes identified by the same beanId with different display values such that the bean can be retrieved in the portlet and will contain the selected check boxes in the group.

HiddenField

This tag renders a hidden field that can be used to provide a form with additional name/value attributes.

Table 2.11. Attributes to hiddenfield

Attribute name	Required?	Description
name	no	string: name of the hiddenfield
value	no	string: the value of the hiddenfield

Example 2.14. Usage of hiddenfield

<ui:hiddenfield beanId="myHiddenField" name="fruit" value="orange"/>

This example creates a hiddenfield with a name and value. The beanId label can be used to retrieve the bean from a portlet.

FileInput

This tag renders a file-input field that can be used to handle file uploads.

Table 2.12. Attributes to fileinput

Attribute name	Required?	Description
size	no	integer: the displayed size in number of characters of the input field
name	no	string: name of the textfield
maxlength	no	integer: maximum length of the textfield
readonly	no	boolean: true if read-only, default is false
disabled	no	boolean: true if disabled, default is false

Example 2.15. Usage of fileinput

<ui:fileinput beanId="myFileInput" value="Initial value" size="15"/>

This example creates a fileinput with the beanId myFileInput such that it can be retrieved in the portlet action method.

TextField

This tag renders a textfield.

Table 2.13. Attributes to textfield

Attribute name	Required?	Description
size	no	integer: the displayed size in number of characters of the input field
name	no	string: name of the textfield
maxlength	no	integer: maximum length of the textfield
value	no	string: initial textfield value
readonly	no	boolean: true if read-only, default is false
disabled	no	boolean: true if disabled, default is false

Example 2.16. Usage of textfield

<ui:textfield beanId="myTextField" value="Initial value" size="15"/>

This example creates a textfield with the beanId myTextField such that it can be retrieved in the portlet action method.

Password

This tag renders a password field.

Table 2.14. Attributes to password field

Attribute name	Required?	Description
size	no	integer: the displayed size in number of characters of the input field
name	no	string: name of the password field
maxlength	no	integer: maximum length of the password field
value	no	string: initial password value
readonly	no	boolean: true if read-only, default is false
disabled	no	boolean: true if disabled, default is false

Example 2.17. Usage of password field

<ui:password name="password" value="" size="15"/>

This example creates a password field with the name password, no default value and a size of 15 characters.

RadioButton

This tag shows a radiobutton. You can group multiple radiobuttons simple by giving the radiobuttons the same name.

Table 2.15. Attributes to radiobutton

Attribute name	Required?	Description
name	no	string: the checkbox name
value	yes	string: the checkbox value
selected	no	boolean: true if selected, default is false
disabled	no	boolean: true if disabled, default is false

Example 2.18. Usage of radiobutton

<ui:radiobutton name="name" value="value" selected="true" disabled="false"/>

This creates a selected radiobutton with the name 'name' and the value 'value'.

<ui:radiobutton beanId="myButton" value="value #1" selected="true"/>
 <ui:radiobutton beanId="myButton" value="value #2"/>
 <ui:radiobutton beanId="myButton" value="value #3"/>

This creates multiple radio buttons identified by the same beanId with different display values such that the bean can be retrieved in the portlet and will contain the selected radio button in the group.

TextArea

This tag creates a textarea.

Table 2.16. Attributes to textarea

Attribute name	Required?	Description
rows	no	integer: the maximum number of rows to display
cols	no	integer: the maximum number of columns to display
name	no	string: name of the text area
value	no	string: initial text area text to display
readonly	no	boolean: true if read-only, default is false
disabled	no	boolean: true if disabled, default is false

Example 2.19. Usage of textarea

<ui:textarea name="myTextArea" value="This is text" rows="120"
                                        cols="30"  disabled="false" />
 <ui:textarea name="myTextArea" rows="120" cols="30"  disabled="false">this is text</>

This creates a 120x30 text area with the name 'myTextArea' and the text 'This is text'. The second example uses the tag body to specify the displayed text.

Text

The text tag is used to display (localized) text

Table 2.17. Attributes to text

Attribute name	Required?	Description
key	no	string: name of the key to lookup localized text from the `WEB-INF/classes/Portlet_XX.properties` localized properties file
value	no	string: actual text to display
style	no	string: the style to display text in. Possible values include `error`, `info` `alert`, `status`, `success`. The default style used is `info`

Example 2.20. Usage of text

<ui:text key="GREETING_MSG"/>
<ui:text value="something bad happened" style="error"/>
<ui:text style="error">something bad happened</>
<ui:text style="error" format="font-style:italic;color:red">something bad happened</>

The first example prints a localized message using the GREETING_MSG as a key. The second example displays a message using the error look and feel and the third example is the same as the second, but uses the tag body to specify the display message. The fourthe example shows ow you can override the default look and feel to make the text italic and red by overriding the underlying CSS.

ListBox

This tag creates a listbox. A listbox can contain listbox item tags.

Table 2.18. Attributes to listbox

Attribute name	Required?	Description
multiple	no	boolean: indicates if multiple selection is possible
size	no	integer: the number of items to display in the listbox, default is 1

Example 2.21. Usage of listbox

<ui:listbox bean="myListbox"/>

This example creates a listbox from the bean.

ListBox Item

This tag creates an item in a listbox. You need to pass in a see listboxbean.

Table 2.19. Attributes to listboxitem

Attribute name	Required?	Description
name	no	string: a name identifier
value	no	string: the list item value to be displayed
selected	no	boolean: indicates if this element is selected

Example 2.22. Usage of listboxitem

<ui:listbox>
    <ui:listboxitem value="hello" selected="true"/>
    <ui:listboxitem value="goodbye"/>
</ui:listbox>

This example creates a listbox containing two listbox item elements, one of which is initially selected.

Image

This tag creates an image same as using <img src="..."/> in HTML can be nested inside an actionlink tag to provide a clickable image.

Table 2.20. Attributes to image

Attribute name	Required?	Description
src	no	string: the location of the image to be used
alt	no	string: an alt tag
title	no	string: text to be displayed when mouse hovers over image
border	no	integer: the border size
height	no	integer: the image height
width	no	integer: the image widthe
align	no	integer: the image alignment: top, bottom, left, right

Example 2.23. Usage of image

<ui:actionlink action="doSomething>
    <ui:image src="/mywebapp/html/images/cool.jpg" title="a cool image" border="0"/>
</ui:actionlink>

This example creates a clickable image that will trigger the doSomething method of the portlet to be invoked. The image is located under the webapp directory in the supplied src attribute and has no border.

MessageBox

This tag creates a message box to display alerts, info, warnings or errors with the desired style.

Table 2.21. Attributes to messagebox

Attribute name	Required?	Description
value	no	string: a label for the message box
key	no	string: a key used to lookup a value for the message box from a localized properties file
style	no	string: the message style, a value contained in `MessageStyle` class or the JSR 168 specification value from PLT.C.3 e.g. "portlet-msg-error"

Example 2.24. Usage of messagebox

<ui:messagebox style="<%= MessageStyle.MSG_SUCCESS %>" value="File successfully uploaded"/>

Validator

A validator tag can be nested inside of a text field tag to provide client side form validation using JavaScript. Currently, the following javascript check functions found in validation.js are supported:<br></br>

Table 2.22. Supported validator types

function type	Description
checkDate	checks if valid date
checkDigit	checks if character provided is a single digit
checkNotEmpty	checks if empty
checkEmail	check if valid email
checkNumber	check if number
checkNumberLessThan	check if number is less than a provided number
checkNumberGreaterThan	check if number is greater than a provided number
checkPhone	checks if a 10 digit phone number
checkCreditCardNumber	checks if valid card number using Luhn's formula
checkCreditCardType

Note: The checking functions that require parameters e.g. checkNumberLessThan still need to be worked on

Table 2.23. Attributes to validator

Attribute name	Required?	Description
type	yes	string: the javascript checking function
value	no	string: a message to display if validation is unsuccessful
key	no	string: a key used to lookup a display value from a localized properties file if validation is unsuccessful

Example 2.25. Usage of validator

<ui:textfield beanId="userNameTF">
         <ui:validator type="checkNotEmpty" key="USER_NAME_BLANK"/>
     </ui:textfield>

Group

This tag creates a simple border around elements placed within it to provide a natural grouping for the desired user interface.

Table 2.24. Attributes to group

Attribute name	Required?	Description
label	no	string: a label for the group
key	no	string: a key for the localized string contained in the properties file
width	no	string: the width of the border
height	no	string: the height of the border

Example 2.26. Usage of group

<ui:group label="Fruits">
    <ui:image src="/mywebapp/html/images/banana.jpg"/>
    <ui:text value="banana"/>
    <p>
    <ui:image src="/mywebapp/html/images/orange.jpg"/>
    <ui:text value="orange"/>
    <p>
    <ui:image src="/mywebapp/html/images/pear.jpg"/>
    <ui:text value="pear"/>
</ui:group>

DataGridTag

	Important
	The DataGridTag will NOT work with JSR 168 portlets and requires major changes. Its use is discouraged for now.

This tag displays a a 'scrollable' table.

Table 2.25. Attributes to datagrid

Attribute name	Required?	Description
beanId	yes	string: unique identifier
size	no	string: size of the 'scollable' window
header	no	string: header for the datagrid
list	no	list: list of objects to be displayed

Example 2.27. Usage of datagrid

Datagrid is used in conjunction with datagridcolumn.


<ui:datagrid beanId="userlistdg" size="4" header="List of Users" list="<%=users%>">
...
</ui:datagrid>

This creates a table with the first 4 entries of the list users. DataGridColumn is needed to specify any columns which be displayed.

DataGridColumnTag

This tag displays an entry in a 'scrollable' datagrid table. Only used inside a datagridtag.

Table 2.26. Attributes to datagridcolumn

Attribute name	Required?	Description
source	no	string: specifies the name of the method which will be called on the itemslist of the datagridtag to set the displayvalue
header	no	string: header for the datagridcolumn
source	no	string: methodname to be called on the elements of the datagrid to be set as value of the child objects
paramname	no	string: if the child of datagridcolumntag is an actionlink this parametername will be added to the link (with the value of paramvalue)
paramvalue	yes	string: if the child of datagridcolumhtag is an actionlink this is the name of the method to be called on the itemlist of a datagridtag to generate an actionparameter with the name of paramname and the generated value

	Important
	The value for the localized keys has to be defined in the `WEB-INF/classes/DataGrid(de\|cs\|nl...).properties` file.

	Important
	Only actionlink, checkbox and text are supported inside a datagridcolumn.

	Important
	All methodcalls on the list objects of the datagrid must return strings!

Example 2.28. Usage of datagrid

DatagridColun is used in conhunction with datagrid.


   <ui:datagrid beanId="userlistdg" size="4" header="List of Users" list="<%=users%>">
       <ui:datagridcolumn header="Name" source="getName">
            <ui:text/>
        </ui:datagridcolumn>
    </ui:datagrid>

This creates a table with the first 4 entries of the list users. The first column will have the heading 'Name' and will generate the values by calling the method 'getName' on the elements of the list users.


   <ui:datagrid beanId="userlistdg" size="4" header="List of Users" list="<%=users%>">
      <ui:datagridcolumn header="Username" source="getName" paramname="oid" paramvalue="getOid">
           <ui:actionlink action="viewUser">
               <ui:actionparam name="menu" value="action"/>
           </ui:actionlink>
       </ui:datagridcolumn>
    </ui:datagrid>

This creates a table with the first 4 entries of the list users. The first column will have the heading 'Username' and will generate a link with the value of 'getName' on the list of users. Furthermore each entry will be a link with the calling the method 'viewUser' in the Portlet. Two types of parameters are defined here. The dynamic one is has the name 'oid' and the value of that will be the result of the methodcall 'getOid' on the items of the list users defined in the datagridtag. The second parameter is a static parameter. Each ActionLink has also the parameter 'menu' with the value 'action'. Only one dynamic parameter is supported.


   <ui:datagrid beanId="userlistdg" size="4" header="List of Users" list="<%=users%>">
       <ui:datagridcolumn source="getOid">
           <ui:checkbox beanId="checkBox"/>
       </ui:datagridcolumn>
    </ui:datagrid>

This creates a table with the first 4 entries of the list users. This will generate a checkbox in each row with the name 'checkbox' and the value of the method call 'getOid' on the list of users.

ActionMenuTag

This tag displays a menu.

Table 2.27. Attributes to ActionMenuTag

Attribute name	Required?	Description
title	no	string: title of the menu
layout	no	string: layout of the menu, either 'vertical' or 'horizontal' (default)
key	no	string: key for the localized header of the menu

	Important
	The value for the localized keys has to be defined in the `WEB-INF/classes/ActionMenu(de\|cs\|nl...).properties` file.

Example 2.29. Usage of ActionMenuTag

ActionMenuTag is used in conjuntion with ActionMenuItemTag


<ui:actionmenu title="Menu" layout="vertical" >
...
</ui:actionmenu>

This creates a a vertical menu with the title 'Menu'.

ActionMenuItemTag

This tag displays a menuitem within a ActionMenutag.

Table 2.28. Attributes to datagrid

Attribute name	Required?	Description

Example 2.30. Usage of ActionMenuItemTag

ActionMenuItemTag is used in conjuntion with ActionMenuTag.

 
 <ui:actionmenu title="Menu" align="vertical" >
     <ui:actionmenuitem>
        <ui:actionlink action="showList" value="Show List"/>
     </ui:actionmenuitem>
 </ui:actionmenu>

This creates a a vertical menu with the title 'Menu' and one entry. This entry is an ActionLink with an action ShowList and a value 'Show List'. Any UI tag can be used inside an actionmenuitem.

ActionPaneTag

This displays an "action pane" that can be used to contain an "action menu" (see ActionMenuTag above) and an "action body" (see the example below). The result is that a visible border will be drawn around the action menu and body content. This is particularly useful when the "action menu type" is set to "actiontab". The action menu will then display a row of tabs where the selected tab will wrap the content of the action body, similar to how portlet tabs are drawn by GridSphere's layout manager.

Table 2.29. Attributes to actionpanetag

Attribute name	Required?	Description
menutype	no	string: "actiontab" or "actionbar"
align	no	string: alignment of the menu, either 'vertical' or 'horizontal' (default)
key	no	string: key for the localized header of the menu

	Important
	When using the action pane tag, be sure to be include the action menu above the action body to produce the desired effect of an action tab pane or menu being displayed above the area in which content should be displayed.

Example 2.31. Usage of ActionMenuTag

ActionPaneTag is used in conjuntion with ActionMenuTag and ActionBodyTag.

 
 <ui:actionpane menutype="actiontab">
     <ui:actionmenu>
         <!-- Include action menu items here. For the best results, when menutype is set to "actiontab", use
              action links inside the action menu. For example...
         <ui:actionmenuitem>
             <ui:actionlink action="doAction1" value="Do Action 1"/>
         </ui:actionmenuitem> -->
         <ui:actionmenuitem>
             <ui:actionlink action="doAction2" value="Do Action 2"/>
         </ui:actionmenuitem> -->
     </ui:actionmenu>
     <ui:actionbody>
         <!-- This is where content should be displayed, similar to how portlets are displayed under tabs. -->
     </ui:actionbody>
 </ui:actionpane>

This creates an action tab pane, with action tabs on top and the content of each tab displayed below.

Chapter 3. GridSphere UI Visual Bean Library

Table of Contents

Usage on GridSphere UI Visual Beans
Base Bean Attributes
Supported Visual Beans

The GridSphere visual beans act as counterparts to the visual tag library, making it possible to access beans from within portlets to obtain updated values for dynamic form elements such as textfields, hiddenfields, password fields, listboxes, and so on.

Usage on GridSphere UI Visual Beans

Usage of the visual beans requires that your portlet subclass from ActionPortlet The ActionPortlet provides a FormEvent object that subclasses from ActionEvent and provides interfaces for obtaining visual beans. The FormEvent provides methods to obtain any kind of visual bean as the following usage example shows:

Example 3.1. Usage of visual beans from a portlet

            public void doSomething(FormEvent event) {
                HiddenFieldBean hf = event.getHiddenFieldBean("fruit");
                String fruit = hf.getValue();
                // do something with fruit...

                ListBoxBean lb = event.getListBoxBean("fruitlist");
                List fruits = lb.getSelectedValues();
                // do something with fruits...
            }

The example shows how a hidden field and listbox elements can be retrieved from the presentation using the UI tags described. If the beans are updated, the presentation page will be rendered with the new values.

Base Bean Attributes

Just like the UI tags, all visual beans inherit from a BaseComponentBean which provides various attributes for setting the look and feel, labels and values. Below is a list of the basic bean attributes, however not all are used for every visual bean. As a general coding practice, presentation attributes such as color, font, etc should be set in the UI tags and not in the beans in the portlet code.

Table 3.1. Base Bean Attributes

Attribute name	Required?	Description
name	no	string: a name for this component. Generally this uses the underlying name attribute of the corresponding HTML element
value	no	string: the value of this component. Generally this uses the underlying value attribute of the corresponding HTML element
readonly	no	boolean: true if this component is intended to be read-only, false otherwise
disabled	no	boolean: true if this component is intended to be disabled, false otherwise
cssStyle	no	string: the CSS style to use for rendering this component

Supported Visual Beans

The following lists the supported visual beans that can be obtained via the FormEvent interface. More information on each of the beans methods can be found in the Javadoc API

ActionLinkBean
ActionMenuBean
ActionMenuItemBean
ActionSubmitBean
CheckBoxBean
FileInputBean
FrameBean
HiddenFieldBean
ImageBean
ListBoxBean
MessageBoxBean
PanelBean
PasswordBean
TableBean
TableCellBean
TableRowBean
TextBean
TextAreaBean
TextFieldBean
RadioButtonBean