The Jade Layout tag library allows a clean separation between the layout of a JSP page and the information that is shown on it. The layout is a "template" that is used by the main page to determine how elements on the page are placed.

Consider cascading style sheets. They allow the developer to parameterize styles in the HTML documents. This library allows the JSP programmer to parameterize the layout of the HTML document. The developer can now parameterize both styles and page organization.

Definitions

Fragment

Some text that will be placed in a specific location on an HTML page. The source of the text can be a body of a JSP tag, a String, or a String representation of an object.

Layout

A set of fragments.

Layout Class

The class in the Layout Tag Library that contains fragments and the means of manipulating them.

Template

A specification of how fragments should be arranged on a page.

Template File

A JSP file containing a template.

JSP Page

The page containing fragment definitions. This is the page that is served by the JSP container and viewed by the user.

Tags

A template is specified using the TemplateTag and the DisplayTag. The TemplateTag demarcates the template contents and the DisplayTag indicates where the fragment should be displayed in the template.

The JSP page uses the LayoutTag and the DefineTag. The LayoutTag specifies the template file to use for the upcoming fragments, and the DefineTag specifies those fragments.

Naming Fragments

Fragments can be specified using names (i.e. Strings), id's (i.e. Integers) or both, providing flexibility for naming conventions or other requirements. The three naming methods reside in different name spaces, so it is possible to have a fragment named "Header", a fragment with id 1, and a fragment named "Header" and id 1 all in the same layout without collisions.

When defining the fragment, the name and/or id are specified as attributes to the DefineTag. These attributes can be compile-time or run-time expressions.

• Compile-time names and ids should be used when the number of fragments is known and fixed.
• Run-time names and ids allow an insertion of an arbitrary number of fragments into the layout.

When displaying a fragment, the name and/or id are required as attributes on the DisplayTag. This tag, too, takes both compile-time and run-time values. As before, In cases when the compile-time values were used, it is likely that these attributes will be known and

• Compile-time names and ids should be used when the number of fragments is known and fixed.
• Run-time names and ids allow displaying an arbitrary number of fragments in the template. You can combine this functionality with the scripting variables (see below) to create truly dynamic templates.

You can define more fragments in the JSP page than are used in the template file. The extra fragments are ignored. You can also define fewer fragments than are used in the template file. The missing fragments are omitted silently. This behavior permits greatest flexibility.

Scripting Variables

The TemplateTag exposes the underlying Layout Class instance as a scripting variable. Methods are available to retrieve the names or the ids of all the fragments that have been inserted into the layout as a Collection. It is therefore easy to either pass the collection to an iterative tag of your choice (for example, the Strut's Iterate Tag), or to iterate through it using embedded Java in the usual manner. The body of the loop can then contain the DisplayTag, displaying as many fragments as needed.

Moreover, the DisplayTag exposes the fragment as a scripting variable as well. A layout fragment can either be a JSP Body Content or any other Java Object. It is therefore possible to pass in an arbitrary object into the template and make custom calls on it, in the usual JSP manner.

Examples

See Usage to learn how to use the tags or Examples to learn how to deploy the JSP examples.