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|
|
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 |
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|
|
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.
- 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|
|
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 valuecan 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|
|
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|
|
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|
|
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|
|
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|
|
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|
|
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|
|
classname |
If specified, the classname attribute of the
factory to create and initialize. | |
file |
The definition file's name. This attribute is
required. |
|