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 with 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        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.


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.




Programming Jakarta Struts
Programming Jakarta Struts, 2nd Edition
ISBN: 0596006519
EAN: 2147483647
Year: 2003
Pages: 180

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