|
|
|
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 www.ofbiz.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.
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.
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.
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.