ONJava.com -- The Independent Source for Enterprise Java
oreilly.comSafari Books Online.Conferences.

advertisement

AddThis Social Bookmark Button O'Reilly Book Excerpts: Programming Jakarta Struts

Programming Jakarta Struts: Using Tiles, Part 3

Related Reading

Programming Jakarta Struts
By Chuck Cavaness

by Chuck Cavaness

In part 3 in this series of book excerpts on using tiles from Programming Jakarta Struts, learn how to use the tile tag library (which contains the following tags: insert, definition, put, putList, add, get, getAsString, useAttribute, importAttribute, and initComponentDefinitions).

Also In This Series

Programming Jakarta Struts: Using Tiles, Part 4
We conclude this book excerpt series on using tiles from Programming Jakarta Struts by showing you how to use definitions. You'll also find coverage on support for internationalization of tiles.

Programming Jakarta Struts: Using Tiles, Part 2
In part two in this series of book excerpts on using tiles from Programming Jakarta Struts, learn how to install and configure tiles, as well as get an overview on tiles.

Programming Jakarta Struts: Using Tiles, Part 1
In part one in this series of book excerpts on using tiles from Programming Jakarta Struts, learn how to use tiles, and gain an understanding of templates.


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.

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.

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 "Declaring Definitions in a JSP Page" of this chapter.

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.

TIP: 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.

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.

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

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.

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.

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

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

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.

In the next installment, learn about tile and tile tag definitions.

Chuck Cavaness is a graduate from Georgia Tech with degrees in computer engineering and computer science. He has built Java-based enterprise systems in the healthcare, banking, and B2B sectors. He is also the author of two O'Reilly books, Programming Jakarta Struts and Jakarta Struts Pocket Reference.


Return to ONJava.com.