The Tiles Tag Library Tags

 < Day Day Up > 



Table 7-1 lists each of the tags in the Tiles Tag Library and provides a short description of each tag’s purpose.

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 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 (or parameter) 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 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 Required and Accepts Scriptlet columns.

The Required column simply denotes whether or not the given attribute is required when using the tag. 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 Scriptlet column denotes whether or not the given attribute’s value can be specified with a JSP scriptlet. If a JSP scriptlet is used to specify an attribute value, the scriptlet 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 scriptlet. This is invalid because there are extra characters between the end of the scriptlet 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 scriptlet and the scriptlet 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 Scriptlet

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

DeprecatedOriginally for compatibility with the now defunct Template Tag Library.Use the value attribute instead.

Yes

No

direct

DeprecatedOriginally 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 Scriptlet

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

DeprecatedOriginally 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 Scriptlet

Required

ignore

Accepts “true” or “false” to denote whether or not 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 Scriptlet

Required

ignore

Accepts “true” or “false” to denote whether or not 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 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 Scriptlet

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 Scriptlet

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

DeprecatedUse 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” to denote that the JSP’s output stream should be flushed before this definition is inserted.

No

No

ignore

Accepts “true” or “false” to denote whether or not 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

DeprecatedOriginally 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 (or parameter) 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 Scriptlet

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

DeprecatedOriginally for compatibility with the now defunct Template Tag Library.Use the value attribute instead.

Yes

No

direct

DeprecatedOriginally 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 Scriptlet

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 what scope the JSP scripting variable should be placed in.

Attributes

Attribute

Description

Accepts Scriptlet

Required

classname

DeprecatedThis 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 denote whether or not 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"/>



 < Day Day Up > 



Struts. The Complete Reference
Struts: The Complete Reference, 2nd Edition
ISBN: 0072263865
EAN: 2147483647
Year: 2003
Pages: 134
Authors: James Holmes

Similar book on Amazon

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net