Page History

Table of Contents

Related Documents

• Control Servlet Guide (need to move this to wiki)
• JSP Tag Library Guide (need to move this to wiki)

Introduction

The Regions Tool, or Framework, is an implementation of the Composite View pattern as described in various works on Enterprise Architecture Patterns and is based on the implementation presented in the book Advanced Java Server Pages by David Geary. You can get more information about this book on the Docs & Books page on the ofbiz.apache.org/ website.

...

Regions can also be declared in JSP files, and included in JSP files, using the regions taglib described in the regions.tld tag library descriptor file. These tags are also used in the Region templates to include named Sections in specific locations in the template.

Defining Regions

...

A Basic Region Definition

First let's look at an actual region definition that would go in the WEB-INF/regions.xml file:

...

Note that if a section is included in a template, but no content is specified for it in the region definition then nothing will be inserted there when the template is rendered.

An Inheritance Region

Here is an example of a region definition that inherits from another definition:

    <define id='login' region='MAIN_REGION'>
        <put section='title'>Login Page</put>
        <put section='content' content='/login.jsp'/>
    </define>

This definition does not use the template attribute of the define tag. Instead it uses the region attribute and specifies the region that this region will inherit its base definition from. The same template as the parent region will be used and all of the put settings for assigning content to sections will be inherited. Any put tags specified in the inheriting region will override the section content assignments of the parent region.

...

This login region has the same layout as the MAIN_REGION, but the "content" section is overriden so that the login.jsp page will be rendered in the main content area. It also overrides the title to specify a custom title for the page.

A Region within a Region

Here is an example of a region that is meant to be used as content for a section in the main region. In order to use this a region that inherits from the main region is defined for this new style of page. Also included below is an example of a region that inherits from this new style of page and overrides the main content area and the title section so that it can be used as a real world view.

    <define id='LEFTBAR_REGION' template='/templates/leftbar_template.jsp'>
        <put section='first' content='/catalog/choosecatalog.jsp'/>
        <put section='second' content='/catalog/keywordsearchbox.jsp'/>
        <put section='third' content='/catalog/sidedeepcategory.jsp'/>
        <!-- <put section='fourth' content='http://www.yahoo.com' type="http"/> -->
        <put section='fourth' content='/catalog/minireorderprods.jsp' type="resource"/>
        <!-- <put section='fifth' content='/fifth.jsp'/> -->
    </define>

    <define id='LEFT_ONLY_REGION' region='MAIN_REGION'>
        <put section='leftbar' content='LEFTBAR_REGION'/>
    </define>

    <define id='showcart' region='LEFT_ONLY_REGION'>
        <put section='title'>Show Cart</put>
        <put section='content' content='/cart/showcart.jsp'/>
    </define> 

Different Types of Sections

There are just a few types of sections that are always available. In addition to these types you can also use any type of Control Servlet View defined in the controller.xml file. Examples include http, velocity, etc.

The section types that are always available are: default, region, resource, and direct.

The direct type is the most simple. With this type the value of the content attribute of the put tag or the string in the body of the put tag will be directly inserted into the template.

The region type is used to allow content from rendered regions to be included as section content in another region.

The resource type is used to specify that the value of the content attribute refers to a resource (a JSP, Servlet or other webapp resource) in the current webapp.

The default type is the only one that does not have a direct meaning. When default is specified (or when no type is specified) the content attribute value is looked up in the list of region names and if found that region will be used for the section content. If the content attribute value is not a region name then it is assumed to be a resource and the regions framework will look up the named resource in the current webapp.

Creating Region Templates

Introduction

The simplest way to create a region template is to create a JSP that uses the region taglib to render sections within the region. The template JSPs can be used just like any other JSP, but it is best to keep them simple and put the more complex content into webapp resources that can be included as section content.

Just as a side note, the region "stack" is stored in a request attribute and with it you could in theory create a servlet that can be used as a template, or a tool could be developed for velocity or other templating mechanisms to be used as region templates.

The Tags

The first step for using the region render tag is to declare the use of the region taglib as follows in the JSP:

	<%@ taglib uri='regions' prefix='region' %>

The "regions" uri comes from a declaration in the web.xml file, which is done in the standard way.

That done you can specify where each section content will be inserted, or rendered, using the region:render tag as follows:

	<region:render section='header'/>

There are other tags in the region taglib that can be used just like the XML elements in the regions.xml file to define regions and the content that is assigned to each section in the region.