Adding Tiles to the Mini HR Application

The Tiles Tag Library Tags

Table 7-1 lists each of the tags in the Tiles Tag Library and provides a short description of each tag's purpose. The remainder of this section discusses each tag in detail, including a complete description of the tag, a table listing each of the tag's attributes, and a usage example for the tag. In the tables that describe each tag's attributes, pay special attention to the Accepts JSP Expression and Required columns.

Table 7-1: The Tiles Tag Library Tags

Tag	Description
add	Defines an entry for a list created with the putList tag.
definition	Defines a tile (which is a region within a page) and stores it in a JSP scripting variable.
get	Deprecated. Originally for compatibility with the now-defunct Template Tag Library. Use the insert tag instead.
getAsString	Renders the value of a Tiles attribute to the JSP's output stream.
importAttribute	Stores the values of all defined Tiles attributes in JSP scripting variables.
initComponentDefinitions	Initializes the Tiles definition factory with definitions from a Tiles XML configuration file.
insert	Inserts a Tiles definition or attribute into a JSP page.
put	Defines an attribute for a definition.
putList	Defines a list attribute (of java.util.List type) containing an ordered collection of individual attributes.
useAttribute	Stores the value of a Tiles attribute in a JSP scripting variable.

The Required column simply denotes whether the given attribute is required when using the tag. In addition to the required column denoting whether an attribute is required, the rows for required attributes are highlighted in gray so that you can determine at a glance which attributes are required.

If an attribute is required and you do not specify it when using the tag, the tag will throw a javax.servlet.jsp.JspException at run time. Note that you can declare an error page in your JSP with a page directive to capture any JspExceptions that might be thrown, as shown here:

<%@ page errorPage="error.jsp" %>

If an exception occurs, the page specified by the errorPage attribute will be internally redirected to display an error page.

The Accepts JSP Expression column denotes whether or not the given attribute's value can be specified with a JSP expression. If a JSP expression is used to specify an attribute value, the expression must comprise the complete value, quote (") to quote ("), as shown here.

Correct:

<tiles:put name="<%=title%>">

Incorrect:

<tiles:put name="<%=title%>-title">

Notice in the incorrect example that "-title" is used as part of the value for the name attribute following the expression. This is invalid because there are extra characters between the end of the expression and the ending quote.

A corrected version of the incorrect example follows:

<tiles:put name="<%=title + "-title"%>"/>

The concatenation of "-title" is now part of the expression and the expression comprises the complete value for the attribute.

The add Tag

The add tag is used to define an entry for a list created with the putList tag. There are two ways that the value for the entry can be specified. The value can be specified with the value attribute, or the value can be placed between opening and closing add tags, as shown next:

<tiles:add>value goes here</tiles:add>

Attributes

Attribute	Description	Accepts JSP Expression	Required
beanName	Specifies the name of an object whose value will be used for this entry. If the property attribute is also specified, one of the fields of the object defined by this attribute will have its getter method called to return the object whose value will be used for this entry.	Yes	No
beanProperty	Specifies the field of the object specified by the name attribute whose value will be used for this entry.	Yes	No
beanScope	Specifies the scope (application, page, request, or session) to look in for the object specified by the name attribute. If not specified, each scope will be searched, in this order: page, request, session, and then application.	No	No
content	Deprecated. Originally for compatibility with the now-defunct Template Tag Library. Use the value attribute instead.	Yes	No
direct	Deprecated. Originally for compatibility with the now-defunct Template Tag Library. Use the type attribute set to "string" instead.	No	No
role	Specifies the role the currently authenticated user must have for this entry to be added to the enclosing list. If the user is not in the specified role, the entry will not be added to the list.	Yes	No
type	Specifies the type (string, page, or definition) of the value. If present, it indicates how the value specified with the value attribute is treated.	No	No
value	Specifies the value for this entry.	No	No

Example Usage

The following example illustrates the basic usage of the add tag:

<tiles:insert page="/mainLayout.jsp">   <tiles:putList name="menu">     <tiles:add value="Home"/>     <tiles:add value="Products"/>     <tiles:add value="Search"/>   </tiles:putList> </tiles:insert>

Each add definition is added to the enclosing list in the order specified.

The definition Tag

The definition tag is used to define a tile (which is a region within a page) and store it in a JSP scripting variable. Additionally, this tag allows you to specify the scope in which the JSP scripting variable should be placed. Once this definition is defined, it can be inserted into JSPs by using the insert tag.

Attributes

Attribute	Description	Accepts JSP Expression	Required
extends	Specifies the name of another definition that this definition extends.	Yes	No
id	Specifies the name of the JSP variable that will hold this definition.	No	Yes
page	Specifies the URL for the tile.	Yes	No
role	Specifies the role the currently authenticated user must have for this definition to be created. If the user is not in the specified role, the definition will not be created.	Yes	No
scope	Specifies the scope (application, page, request, or session) in which the JSP scripting variable defined by the id attribute will be stored. If not specified, the JSP scripting variable will be stored in page scope.	No	No
template	Deprecated. Originally for compatibility with the now-defunct Template Tag Library. Use the page attribute instead.	Yes	No

Example Usage

The following example illustrates the basic usage of the definition tag:

 <tiles:definition name="mainLayout"                   page="/layouts/main.jsp">   <tiles:put name="header" value="/layouts/header.jsp"/>   <tiles:put name="footer" value="/layouts/footer.jsp"/> </tilesdefinition> 

Each of the attributes nested underneath the definition tag can be accessed by the JSP specified with the page attribute.

The getAsString Tag

The getAsString tag is used to render the value of a Tiles attribute to the JSP's output stream.

Attributes

Attribute	Description	Accepts JSP Expression	Required
ignore	Accepts true or false to specify whether this tag should return without error if the specified Tiles attribute does not exist. Defaults to false, which will cause a run-time exception to be thrown if the attribute does not exist.	Yes	No
name	Specifies the name of a Tiles attribute whose value should be rendered.	Yes	Yes
role	Specifies the role the currently authenticated user must have for the specified Tiles attribute to be rendered.	Yes	No

Example Usage

The following example illustrates how to use the getAsString tag:

<tiles:getAsString name="title"/>

This example renders the value of the title attribute to the JSP's output stream.

The importAttribute Tag

The importAttribute tag is used to store the values of all defined Tiles attributes in JSP scripting variables. Additionally, this tag allows you to specify the scope in which the JSP scripting variables should be placed. This tag functions similarly to the useAttribute tag in that it can store the value of a specific attribute in a JSP scripting variable. However, it differs in that it can import all attributes at once and that it does not have an id attribute to specify the name of the JSP scripting variable in which values will be stored.

Attributes

Attribute	Description	Accepts JSP Expression	Required
ignore	Accepts true or false to specify whether this tag should return without error if the specified Tiles attribute does not exist. Defaults to false, which will cause a run-time exception to be thrown if the attribute does not exist.	Yes	No
name	Specifies the name of a Tiles attribute that should be imported.	Yes	No
scope	Specifies the scope (application, page, request, or session) that attribute values should be stored in. If not specified, JSP scripting variables will be stored in page scope.	No	No

Example Usage

The following example illustrates how to use the importAttribute tag:

<tiles:importAttribute/>

This example stores the values of all defined Tiles attributes in JSP scripting variables. Alternatively, you could import just one attribute by specifying its name with the name attribute, as shown here:

<tiles:importAttribute name="title"/>

The initComponentDefinitions Tag

The initComponentDefinitions tag is used to initialize the Tiles definition factory with definitions from a Tiles XML configuration file. This tag was created when Tiles was initially a third-party add-on to Struts. At that time, Tiles required you to use a special subclass of ActionServlet to initialize the definition factory. Alternatively, you could use this tag to initialize the factory. However, now that Tiles has been integrated into the core of Struts, this tag is no longer relevant. The Tiles plugin takes care of initializing the definition factory now.

Attributes

Attribute	Description	Accepts JSP Expression	Required
classname	Specifies the fully qualified class name of the Tiles definition factory to use.	No	No
file	Specifies the Tiles configuration file containing the definitions for the factory.	No	Yes

Example Usage

The following example illustrates how to use the initComponentDefinitions tag:

<tiles:initComponentDefinitions file="tiles-defs.xml"/>

As you can see, using this tag is straightforward.

The insert Tag

The insert tag is used to insert a Tiles definition or attribute into a JSP page. Additionally, this tag can be used to create and insert a definition at the same time by specifying a layout JSP with the page attribute and optionally nesting put tags inside this tag.

Attributes

Attribute	Description	Accepts JSP Expression	Required
attribute	Specifies the name of an attribute to insert.	No	No
beanName	Specifies the name of an object whose value will be inserted into the JSP. If the property attribute is also specified, one of the fields of the object defined by this attribute will have its getter method called to return the object whose value will be inserted into the JSP.	Yes	No
beanProperty	Specifies the field of the object specified by the name attribute whose value will be inserted into the JSP.	Yes	No
beanScope	Specifies the scope (application, page, request, or session) to look in for the object specified by the name attribute. If not specified, each scope will be searched, in this order: page, request, session, and then application.	No	No
component	Deprecated. Use the page attribute instead.	Yes	No
controllerClass	Specifies the fully qualified class name of a controller object that is executed before this definition is inserted.	Yes	No
controllerUrl	Specifies the URL for a controller that is executed before this definition is inserted.	Yes	No
definition	Specifies the name of a definition to insert.	Yes	No
flush	Accepts true or false to specify whether the JSP's output stream should be flushed before this definition is inserted. Defaults to false.	No	No
ignore	Accepts true or false to specify whether this tag should return without error if the specified Tiles attribute does not exist. Defaults to false, which will cause a run-time exception to be thrown if the attribute does not exist.	Yes	No
name	Specifies the name of an entity (definition or attribute) to insert.	Yes	No
page	Specifies the URL to a page to insert into the JSP.	Yes	No
role	Specifies the role the currently authenticated user must have for the specified attribute to be inserted. If the user is not in the specified role, the attribute will not be inserted.	Yes	No
template	Deprecated. Originally for compatibility with the now-defunct Template Tag Library. Use the page attribute instead.	Yes	No

Example Usage

The following example illustrates the basic usage of the insert tag:

<tiles:insert attribute="header"/>

This example inserts an attribute named "header" into a JSP.

To insert a definition, you use the definition attribute, as shown next:

<tiles:insert definition="tabLayout"/>

This example inserts an entire definition into a JSP.

As mentioned, you can also use the insert tag to create and insert a definition:

<tiles:insert page="/layouts/tabLayout.jsp">   <tiles:put name="header" value="/tabHeader.jsp"/>   <tiles:put name="body" value="/search.jsp"/>   <tiles:put name="footer" value="/tabFooter.jsp"/> </tiles:insert>

This type of insertion is useful for declaring the attributes that get passed to a layout JSP from inside the JSP instead of in a Tiles configuration file.

The put Tag

The put tag is used to define an attribute for a definition. There are two ways that the value for the attribute can be specified. The value can be specified with the value attribute, or the value can be placed between opening and closing put tags, as shown next:

<tiles:put name="header">value goes here</tiles:put> 

Attributes

Attribute	Description	Accepts JSP Expression	Required
beanName	Specifies the name of an object whose value will be used for this attribute. If the property attribute is also specified, one of the fields of the object defined by this attribute will have its getter method called to return the object whose value will be used for this attribute.	Yes	No
beanProperty	Specifies the field of the object specified by the name attribute whose value will be used for this attribute.	Yes	No
beanScope	Specifies the scope (application, page, request, or session) to look in for the object specified by the name attribute. If not specified, each scope will be searched, in this order: page, request, session, and then application.	No	No
content	Deprecated. Originally for compatibility with the now-defunct Template Tag Library. Use the value attribute instead.	Yes	No
direct	Deprecated. Originally for compatibility with the now-defunct Template Tag Library. Use the value attribute instead.	No	No
name	Specifies the name for the attribute.	No	No
role	Specifies the role the currently authenticated user must have for this attribute to be created. If the user is not in the role, this attribute will not be created.	Yes	No
type	Specifies the type (string, page, or definition) of the value. If present, it indicates how the value specified with the value attribute is treated.	No	No
value	Specifies the value for the attribute.	Yes	No

Example Usage

The following example illustrates the basic usage of the put tag:

<tiles:definition name="mainLayout"                   page="/layouts/main.jsp">   <tiles:put name="header" value="/layouts/header.jsp"/>   <tiles:put name="footer" value="/layouts/footer.jsp"/> </tiles:definition>

Defining attributes with the put tag is as simple as specifying their names and values.

The putList Tag

The putList tag is used to define a list attribute (of java.util.List type) containing an ordered collection of individual attributes. The elements of the list are set by nesting instances of the add tag or instances of this tag. This tag must be nested inside either the definition tag or the insert tag.

Attribute

Attribute	Description	Accepts JSP Expression	Required
name	Specifies the name of the attribute.	No	Yes

Example Usage

The following example illustrates how to use the putList tag:

<tiles:insert page="/mainLayout.jsp">   <tiles:putList name="menu">     <tiles:add value="Home"/>     <tiles:add value="Products"/>     <tiles:add value="Search"/>   </tiles:putList> </tiles:insert> 

This example creates a java.util.List-based Tiles attribute named menu containing the values specified with the nested add tags.

You can also create hierarchical structures with the putList tag by nesting instances of the putList tag inside itself, as shown next:

 <tiles:putList name="menu">   <tiles:add value="Home"/>   <tiles:putList name="Products">     <tiles:add value="Products Menu Item 1"/>     <tiles:add value="Products Menu Item 2"/>   </tiles:putList>   <tiles:add value="Search"/> </tiles:putList> 

Tiles allows you to nest the putList tags to any level for whatever hierarchal structure you need.

The useAttribute Tag

The useAttribute tag is used to store the value of a Tiles attribute in a JSP scripting variable. Additionally, this tag allows you to specify which scope the JSP scripting variable should be placed in.

Attributes

Attribute	Description	Accepts JSP Expression	Required
classname	Deprecated. This attribute is no longer used.	No	No
id	Specifies the name of the JSP variable that will hold the specified attribute's value.	No	No
ignore	Accepts true or false to specify whether this tag should return without error if the specified Tiles attribute does not exist. Defaults to false, which will cause a run-time exception to be thrown if the attribute does not exist.	Yes	No
name	Specifies the name of a Tiles attribute whose value should be stored.	Yes	Yes
scope	Specifies the scope (application, page, request, or session) in which the JSP scripting variable defined by the id attribute will be stored. If not specified, the JSP scripting variable will be stored in page scope.	No	No

Example Usage

The following example illustrates how to use the useAttribute tag:

<tiles:useAttribute name="title"/>

This example stores the value of the Tiles attribute named title in a JSP scripting variable with the same name.

If you want to store the value in a JSP scripting variable with a different name, you must use the id attribute, as shown next:

<tiles:useAttribute  name="title"/>

Additionally, you can specify the scope of the JSP scripting variable that the attribute value will be stored in with the scope attribute:

<tiles:useAttribute  name="title" scope="session"/>