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 are large content areas made up of named Sections that are inserted into a template for the regions. Regions and sections are configured in the WEB-INF/regions.xml file in each webapp. Regions can be incorporated into an OFBiz Control Servlet based web application using a view with the type region.

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:

    <define id='MAIN_REGION' template='/templates/main_template.jsp'>
        <put section='title'>Application Page</put> <!-- this is a default and is meant to overridden -->
        <put section='header' content='/includes/header.jsp'/>
        <put section='error' content='/includes/errormsg.jsp'/>
        <put section='content' content='/main.jsp'/> <!-- this is a default and is meant to overridden -->
        <put section='footer' content='/includes/footer.jsp'/>
        <put section='remote' content='http://www.yahoo.com' type="http"/>
    </define>

The define tag is used to declare a named region. The region name is specified in the id attribute. This is a basic region that uses a JSP template. You can also define regions that inherit from other regions, and that will be covered in the next section. The full path of the template is specified in the template attribute and should be specified as a webapp resource relative to the root of the webapp, just like any JSP or Serlvet in a webapp.

Template files have general text as would be expected and can have content, or other text, inserted at different locations. The content inserted in a region is referred to as a section. Sections are referred to by name in the region template and when configuring a region the content that goes into each section is defined using the put tag.

The name of the section is specified using the section attribute of the put tag. The content to insert into the section is located using the the information in the content attribute. Content can also be inlined in the body of the put tag, as demonstrated in the title section above. This is referred to as direct content. By default the location specified in the content attribute is used to refer to a resource in the current webapp.

The type of the section is specified in the type attribute, and the default type is called default. These types are discussed below.

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.

In this case the login region inherits from the MAIN_REGION. The name of the MAIN_REGION is formatted the way it is because it is meant to be inherited from and not used directly, just another convention we find useful.

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.