A P P E N D I X C ■ S T R U T S T A G R E F E R E N C E
Common Attributes
Unlike the other Struts tag libraries, Tiles has no real common attribute sets. However, there are a number of common attributes. These are described in Table C-14.
Table C-14.Commonly Used Attributes in the Tiles Tag Library
Attribute
Description
template/component/page
These are synonymous, and they all refer to a JSP page
containing layout information.
beanName/beanProperty/beanScope
These attributes are used to locate a JavaBean instance
(using beanName and optionally beanProperty) on a spec-
ified JSP scope (application, session, request, page) or
on the Tile’s ComponentContext (in which case you use
beanScope=tile/component/template—these are all
synonymous). If beanScope isn’t specified, then all scopes
(first the ComponentContext and then all JSP scopes) are
searched for the named JavaBean instance.
role
An authentication role (see the discussion on authenti-
cation roles in the entry for <logic:present>) that the
remote user must have in order for the enclosing tag
to be processed. If the remote user does not have the
specified role, the enclosing tag is skipped.
ignore
If true (the default is false), then if data for the enclosing
tag (which is determined using the name attribute for the
tag; this name attribute will have interpretations that vary
by tag) is not found, simply skip further processing for
the enclosing tag. The default value of ignore is false,
which means that an exception is thrown if the tag’s data
can’t be found.
flush
If true, causes the OutputStream to be flushed before the
tag is processed. This attribute is needed to fix problems
with some servlet containers. The default is false.
A Note on Equivalent Tags
You should note that there are no pure JSF (or JSTL) equivalents for Tiles. So, I’ve omitted the “Equivalents” section on all entries.
Struts-EL Tags for the Tiles Tag Library
All Tiles tags have EL-enabled versions.
■Note EL-enabled tags are those that allow you to use EL expressions. Refer to Chapter 10 for examples.
A P P E N D I X C ■ S T R U T S T A G R E F E R E N C E
459
insert
This tag inserts a page or Tiles layout or controller into the enclosing page. You can customize a layout using nested <tiles:put> tags.
Usage Restrictions
You must specify what to insert. You do this using either the template/component/page synonyms or definition or attribute or name attributes.
Attributes
Besides the commonly used role, flush, and ignore attributes (see Table C-14), the following attributes specify what to insert:
•template/component/page: The name of the JSP page to insert.
•definition: The name of the Tiles definition to insert.
•attribute: The defined property referring to a JSP page or Tiles definition to insert. The use of this property assumes that you’ve defined the attribute elsewhere using <tiles:put>. Refer to Listings 14-3 and 14-4 to see how to use this attribute.
•name: The name of the JSP page, Tiles definition, or <tiles:put> defined property to insert.
•beanName/beanProperty/beanScope: These attributes are used to locate an object (see C-14 on how this is done). The located object is used in one of two ways:
(1) If the object is an instance of org.apache.struts.tiles.AttributeDefinition or org.apache.struts.tiles.ComponentDefinition, then these represent a JSP page or Tiles definition to insert. Frankly, it is difficult to see when this option might be useful. (2) Otherwise, the object’s toString() is called, and this is used as the name of the JSP page, Tiles definition, or <tiles:put> defined property to insert.
You can also call controller code to prepare data or display messages before the insert is performed. To do this, you can specify one of these attributes:
•controllerUrl: This can be a form handler’s name or a URL.
•controllerClass: Any class that implements the org.apache.struts.tiles. Controller interface. This interface has a single execute() method, as described in Listing 14-9.
Examples
This code inserts a layout using template/component/page. Note the leading slash:
460
A P P E N D I X C ■ S T R U T S T A G R E F E R E N C E
<tiles:insert page="/mypage.jsp" />
You can also similarly insert a Tiles definition:
<tiles:insert definition=".basic" />
For more examples using <tiles:insert>, refer to Chapter 14.
definition
This tag declares a layout, or a customization of it, enabling it to be reused. You call the definition from a <tiles:insert> to actually use it.
Usually, you first declare the definition in a shared JSP page, then use <%@ include file="..." %> to include that JSP in your pages that utilize that definition.
<tiles:definition> also allows you to customize an existing layout or existing definition, then reuse that customized version in one or more JSP pages of your own. You perform customization using <tiles:put> and related tags.
Notice that I haven’t discussed the use of the <tiles:defiinition> tag in Chapter 14 because a much better alternative is to declare your definitions in the tiles-defs.xmlfile instead. This makes maintenance of your definitions easier to track, and obviates the need to use shared JSP pages.
Usage Restrictions
The id attribute is required.
Attributes
•id: Specifies a unique name for this definition.
•scope: Specifies the JSP scope of the definition, once it is created. The default scope is page. Setting the value to a scope with a longer lifetime (say session) would allow you to access that definition with <tiles:insert> throughout the user session.
Of course, used unwisely, this freedom leads to “high maintenance” webapps.
•template/page: The name of the JSP page that holds the actual layout. Remember that definitions only declare a layout. The actual layout itself is contained in a JSP page. This page usually contains <tiles:insert attribute="..."/> tags to dictate placement of named items. Refer to Listing 14-3 for an example of this.
•role: A role that must match any one of the remote user’s roles in order for this definition to be processed. For a brief discussion on roles, refer to the entry for
<logic:present>.
•extends: The name of a “parent” definition that you want to further customize. See Listing 14-7 to see how this works.
A P P E N D I X C ■ S T R U T S T A G R E F E R E N C E
461
Examples
Consider the layout page (mylayout.jsp) fragment here:
This layout specifies the relative placement of three elements: header, body, and footer. To use this layout, you can declare a <tiles:definition> like so, in a shared JSP page (shared-layouts.jsp):
This declares the page as it is, with no customizations made. Usually, however, it makes sense to customize a layout when you declare it. In the previous example, we might want to specify the content for the elements header and footer:
In this snippet, the header now points to navbar.jsp and the footer to terms-of-use.jsp. So, the remaining element, body, is undefined. To use the declared definition, you’d include the shared JSP and then use <tiles:insert>:
<%@ include file="shared-layouts.jsp" %> <tiles:insert definition=".basic">
Note that the body is now defined to point to hello-world.jsp.
put
put defines a named attribute in a layout. This allows you to customize a layout for display.
Usage Restrictions
The put tag must be nested within a <tiles:insert> or <tiles:definition>. You must also specify name, which refers to the attribute in the layout, and content for that attribute.
462
A P P E N D I X C ■ S T R U T S T A G R E F E R E N C E
Attributes
•name: The name of the attribute that the put defines.
•value/content: A URL or String representing the content for an attribute. value and content are synonymous.
•beanName/beanProperty/beanScope: Used to locate the object that is interrogated in order to determine the value for this put. Refer to Table C-14 for details. These attributes can be used instead of value or content.
•type: Indicates the meaning of the value for this put—is it a URL to a JSP page (type="page" or type="template") or a Tiles definition (type="definition" or type="instance") or a String (type="string")? If unspecified, implies type="page", unless direct="true", in which case, type="string".
•direct: If set to true, causes value to be interpreted as a literal String instead of a reference (URL to a JSP page or Tiles definition) to be evaluated. The default is false.
•role: A role that must match any one of the remote user’s roles in order for this put to be processed. For a brief discussion on roles, refer to the entry for <logic:present>.
Examples
Refer to the examples in the entry for <tiles:definition> to see how put is typically used. You may also specify the value of a put in its body like so:
<tiles:put name="myPageTitle">Here's looking at you!</tiles:put>
This form is useful when you need to specify text that doesn’t conform to XML’s attribute format.
putList and add
putList creates a list of items, and specifies a name for that list. One or more add tags are nested within a putList, and are used to add elements to the list.
Usage Restrictions
You must specify the name attribute for the putList.
Attributes
putList has just one attribute, name, which is the name of the list. The add tag has exactly the same attributes as <tiles:put>, except that for the name attribute.
A P P E N D I X C ■ S T R U T S T A G R E F E R E N C E
463
Examples
You should understand that putList and add can’t be used to easily customize layout, as you could with <tiles:put>. For example, you’d expect to be able to define a customization of a layout like so:
This won’t work: you can’t nest <tiles:insert> inside a <logic:iterate> (a ServletException is thrown). You’d have to resort to using scriptlets that loop through the items:
get reads the name attribute from the ComponentContext for the Tile (placed there using <tiles:put> or <tiles:putList>), interprets the value as a JSP page or a Tiles definition, and writes the output of either to the response stream.
Usage Restrictions
You need to specify what to display, so the name attribute is required.
464
A P P E N D I X C ■ S T R U T S T A G R E F E R E N C E
Attributes
•name: The name of the Tiles attribute to include.
•ignore: If the attribute specified by name can’t be found, ignore="true" causes a silent failure. Otherwise, an exception is thrown, which is the default behavior.
•flush: This has its usual meaning (see Table C-14).
•role: This has its usual meaning (see Table C-14).
This will cause the contents of two.jsp to be displayed after the contents of one.jsp.
getAsString
This tag is similar to <tiles:get>, but the Tiles attribute is interpreted as a literal string. This is useful to display static text (used for example, in <title> sections of web pages).
Usage Restrictions
You need to specify what to display, so the name attribute is required.
Attributes
•name: The name of the Tiles attribute to display. If this isn’t found, an exception is thrown.
•flush: This has its usual meaning (see Table C-14).
•role: This has its usual meaning (see Table C-14).
A P P E N D I X C ■ S T R U T S T A G R E F E R E N C E
<tiles:useAttribute name="myTilesAttr" id="x"/> <%= x %>
Here, we’ve exposed the Tiles attribute myTilesAttr as a scripting variable named x.
466
A P P E N D I X C ■ S T R U T S T A G R E F E R E N C E
importAttribute
importAttribute copies specified Tiles attributes (declared with <tiles:put> or <tiles:putList>) into the specified scope. Recall that each Tile stores its attributes into a ComponentContext instance, and not directly on the request, session, page, or application scope. Because of this, you need to copy attributes from the ComponentContext into the request, session, page, or application scope in order for non-Tiles tags to read the attributes. importAttribute does just this.
Usage Restrictions
importAttribute needs a ComponentContext to read from, and if an instance isn’t found, an exception is thrown. This means that you must place <tiles:importAttribute> after a <tiles:insert> or within a page called by a <tiles:insert>, to ensure that the
ComponentContext has been created.
Attributes
•name: Specifies the name of the attribute to copy over. If omitted, all attributes of the ComponentContext are copied to the prescribed scope.
•scope: Specifies a scope (request, session, page, or application) to copy attributes to. If omitted, the page scope is used.
•ignore: If the named attribute can’t be found, an exception is thrown by default. Setting ignore="true" causes importAttribute to fail silently.
A P P E N D I X C ■ S T R U T S T A G R E F E R E N C E
467
initComponentDefinitions
This tag is used to initialize the Tiles subsystem. Recall that Tiles was originally not part of Struts, and can actually be used by itself. So, this tag is only useful if you’re using Tiles outside of Struts. For example, if you write your own servlets, this tag is useful because it allows you to initialize the Tiles subsystem without having to rely on Struts to do it for you. Frankly, Tiles is now so much integrated with Struts that this tag is no longer very practical.
