14.4 The Tiles Tag Library

This section introduces the JSP custom tags used by the Tiles framework. Table 14-1 lists the tags available to the framework. The tags are very similar to the ones provided in any template-based framework, but Tiles contains more functionality.

Table 14-1. Tags within the Tiles tag library
Tag name	Description
add	Add an element to the surrounding list.
definition	Create a tile component definition.
get	Get the content from request scope that was put there by a put tag.
getAsString	Render the value of the specified tile/component/template attribute to the current JspWriter.
importAttribute	Import a tile's attribute into the specified context.
initComponentDefinitions	Initialize a tile definitions factory.
insert	Insert a tiles component.
put	Put an attribute into a tile context.
putList	Declare a list that will be passed as an attribute.
useAttribute	Use an attribute value inside a page.

14.4.1 The insert Tag

The insert tag is responsible for inserting content into a page. In a layout tile, the insert tag prescribes where the content will go using attribute values. In a regular, non-layout tile, the insert tag is used to retrieve a layout and allow content to be passed to the layout using put tags. Table 14-2 lists the attributes for the insert tag.

Table 14-2. Attributes for the insert tag
Attribute name	Description
attribute	The name of an attribute in the current tile/component context. The value of this attribute is passed to the name attribute.
beanName	The name of the bean used as a value. The bean is retrieved from the specified context, if any. Otherwise, the pageContext.findAttribute( ) method is used. If the beanProperty attribute is also specified, retrieve the value from the corresponding bean property. If the bean (or bean property value) is an instance of one of the Attribute classes (Direct, Instance, etc.), the insertion is done according to the class type. Otherwise, the toString( ) method is called on the bean, and the returned String is passed to the name attribute.
beanProperty	The name of the bean property. If specified, the value is retrieved from this property.
beanScope	The context scope the bean can be found within. If not specified, the pageContext.findAttribute( )method is used. The scope can be any JSP scope, component, or template. In the two latter cases, the bean is searched in the tile/component/template context.
component	A string representing the URI of a tile or template. The template, page, and component attributes have exactly the same behavior.
controllerUrl	The URL of a controller called immediately before the page is inserted. The URL usually denotes a Struts action. The controller (action) is used to prepare data to be rendered by the inserted tile. Only one of controllerUrl or controllerClass should be used.
controllerClass	The class type of a controller called immediately before the page is inserted. The controller is used to prepare data to be rendered by the inserted tile. Only one of controllerUrl or controllerClass should be used. The class must implement or extend one of the following: org.apache.struts.tiles.Controller, org.apache.struts.tiles.ControllerSupport, or org.apache.struts.action.Action.
definition	The name of the definition to insert. Definitions are defined in a centralized file. For now, only definitions from a factory can be inserted with this attribute. To insert a definition defined with the definition tag, use beanName="".
flush	true or false. If true, the current page output stream is flushed before tile insertion.
ignore	If this attribute is set to true and the attribute specified by the name does not exist, simply return without writing anything. The default value is false, which will cause a runtime exception to be thrown.
name	The name of an entity to insert. The search is done in this order: definition, attribute, then page.
page	A string representing the URI of a tile or template. The template, page, and component attributes have exactly the same behavior.
role	If the user is in the specified role, the tag is taken into account; otherwise, the tag is skipped and the content is not written out.
template	A string representing the URI of a tile or template. The template, page, and component attributes have exactly the same behavior.

Several examples of the insert tag were shown earlier in this chapter.

14.4.2 The definition Tag

The definition tag is used to create a tile (template) definition as a bean. The newly created bean will be saved under the specified id, in the requested scope. The definition tag has the same syntax as the insert tag. The new definition can extend a definition described in the definition factory (XML file) and may overload any previously defined parameters. Table 14-3 lists the attributes supported by the definition tag.

Table 14-3. Attributes for the definition tag
Attribute name	Description
extends	The name of a parent definition that is used to initialize this new definition.The parent definition is searched in the definitions factory.
id	The name under which the newly created definition bean will be saved. This attribute is required.
page	URL of the template/component to insert. Same as template.
role	The role to check before inserting this definition. If the role is not defined for the current user, the definition is not inserted. Checking is done at insertion time, not during the definition process.
scope	The variable scope in which the newly defined bean will be created. If not specified, the bean will be created in page scope.
template	A string representing the URL of a tile/component/template (a JSP page).

The following fragment illustrates how to use the definition tag in a JSP page:

<tiles:definition 
  id="storefront.default" 
  page="/layouts/storefrontDefaultLayout.jsp" 
  scope="request">
    <tiles:put name="header" value="/common/header.jsp" />
    <tiles:put name="menubar" value="/common/menubar.jsp" />
    <tiles:put name="copyright" value="/common/copyright.jsp" />  
</tiles:definition>

A complete example is shown later, in Section 14.5.1 of this chapter.

14.4.3 The put Tag

The put tag is used to pass attributes to a tile component. This tag can be used only inside the insert or definition tags. The value (or content) of the put tag is specified using the value attribute or the tag body. It is also possible to specify the type of the value:

string

Content is literally translated.

page or template

Content is included from specified URL. Name is used as URL.

definition

Content comes from specified definition (from factory). Name is used as definition name.

If the type attribute is used, it is taken into account by the get or insert tags inside the inserted tile. If the type attribute is not specified, the content is untyped, unless it comes from a typed bean.

Setting direct="true" is equivalent to setting type="string".

Table 14-4 lists the attributes for the put tag.

Table 14-4. Attributes for the put tag
Attribute name	Description
beanName	The name of the bean used to retrieve the value. The bean is retrieved from the specified context, if any. Otherwise, the pageContext.findAttribute( )method is used. If beanProperty is specified, retrieve the value from the corresponding bean property.
beanProperty	The property name in the bean. If specified, the value is retrieved from this property.
beanScope	The scope used to search for the bean. If not specified, the pageContext.findAttribute( ) method is used. The scope can be any JSP scope, "tile", "component", or "template". In the three later cases, the bean is searched in the tile/component/template context.
content	Content that's put into tile scope. This attribute is equivalent to the value attribute and was added for compatibility with the JSP template tags.
direct	How the content is handled: true means content is printed directly; false means content is included. false is the default. This is another way to specify content type. If direct="true", content is "string"; if direct="false", content is "page". This attribute was added for compatibility with the JSP template tags.
name	The name of the attribute.
role	If the user is in the specified role, the tag is taken into account. Otherwise, the tag is skipped and the content is not written out.
type	The content type. Valid values are "string", "page", "template", or "definition".
value	The attribute value—can be a String or an Object. The value can come from a direct assignment (value="aValue") or from a bean. One of value, content, or beanName must be present.

14.4.4 The putList Tag

The putList tag creates a list that will be passed as an attribute to a tile. The list elements are added using the add tag. This tag can be used only inside the insert or definition tag. Table 14-5 lists the attribute for the putList tag.

Table 14-5. Attribute for the putList tag
Attribute name	Description
name	The name of the List. This attribute is required.

14.4.5 The add Tag

The add tag adds an element to the surrounding list. This tag can be used only inside the putList tag. The value can come from a direct assignment (value="aValue") or from a bean. One of value or beanName must be specified. Table 14-6 lists the attributes for the add tag.

Table 14-6. Attributes for the add tag
Attribute name	Description
beanName	The name of the bean used to retrieve the value. The bean is retrieved from the specified context, if any. Otherwise, the pageContext.findAttribute( ) method is used. If beanProperty is specified, retrieve the value from the corresponding bean property.
beanProperty	The bean property name. If specified, the value is retrieved from this property.
beanScope	The scope used to search for the bean. If not specified, the pageContext.findAttribute( ) method is used. The scope can be any JSP scope, "component", or "template". In the two latter cases, the bean is searched in the tile/component/template context.
content	The value is the same as the value attribute. This attribute was added for compatibility with the JSP template tags.
direct	How the content is handled: true means content is printed directly; false means content is included. false is the default.
role	If the user is in the specified role, the tag is taken into account; otherwise, the tag is ignored (skipped). The role isn't taken into account if the add tag is used in a definition.
type	The content type: "string", "page", "template", or "definition". If the type attribute is not specified, content is untyped, unless it comes from a typed bean.
value	The value to be added. Can be a String or Object.

14.4.6 The get Tag

The get tag retrieves content from the tile context and includes it in the page. Table 14-7 lists the attributes for the get tag.

Table 14-7. Attributes for the get tag
Attribute name	Description
flush	true or false. If true, the current page output stream is flushed before tile insertion.
ignore	If this attribute is set to true and the attribute specified by the name does not exist, simply return without writing anything. The default value is false, which will cause a runtime exception to be thrown.
name	The name of the content to get from the tile scope. This attribute is required.
role	If the user is in the specified role, the tag is taken into account; otherwise, the tag is ignored.

14.4.7 The getAsString Tag

The getAsString tag retrieves the value of the specified tile attribute property and renders it to the current JspWriter as a String. The usual toString( ) conversion is applied to the value. If the named value is not found, a JSPException will be thrown. Table 14-8 lists the attributes for the getAsString tag.

Table 14-8. Attributes for the getAsString tag
Attribute name	Description
ignore	If this attribute is set to true and the attribute specified by the name does not exist, simply return without writing anything. The default value is false, which will cause a runtime exception to be thrown.
name	The attribute name. This attribute is required.
role	If the user is in the specified role, the tag is taken into account; otherwise, the tag is ignored.

14.4.8 The useAttribute Tag

The useAttribute tag declares a Java variable and an attribute in the specified scope, using the tile's attribute value. The variable and attribute will have the name specified by id, or the original name if not specified. Table 14-9 lists the attributes for the useAttribute tag.

Table 14-9. Attributes for the useAttribute tag
Attribute name	Description
classname	The class of the declared variable.
id	The declared attribute and variable name.
ignore	If this attribute is set to true and the attribute specified by the name does not exist, simply return without error. The default value is false, which will cause a runtime exception to be thrown.
name	The tile's attribute name. This attribute is required.
scope	The scope of the declared attribute. Defaults to "page".

14.4.9 The importAttribute Tag

The importAttribute tag imports the attribute from the tile to the requested scope. The name and scope attributes are optional. If not specified, all tile attributes are imported in page scope. Once imported, an attribute can be used like any other bean from the JSP context. Table 14-10 lists the attributes for the importAttribute tag.

Table 14-10. Attributes for the importAttribute tag
Attribute name	Description
ignore	If this attribute is set to true and the attribute specified by the name does not exist, simply return without error. The default value is false, which will cause a runtime exception to be thrown.
name	The tile's attribute name. If not specified, all attributes are imported.
scope	The scope into which the attribute is imported. Defaults to "page".

14.4.10 The initComponentDefinitions Tag

The initComponentDefinitions tag initializes the definitions factory. Table 14-11 lists the attributes for the tag.

Table 14-11. Attributes for the initComponentDefinitions tag
Attribute name	Description
classname	If specified, the classname attribute of the factory to create and initialize.
file	The definition file's name. This attribute is required .