Apache Struts, Tiles and ADF

Written By Duncan Mills, Oracle Corporation
July 2004

Introduction

Tiles is a technology that is widely used in conjunction with the Apache Struts Page flow controller used by the Oracle ADF framework. Tiles provides a way of defining Page fragments or "tiles" which can be assembled into a complete page at runtime. This allows you to define the common part of your applications such as page headers and menus just once as reusable tiles, rather than repeating such common information in every page definition. Tiles is, in principle, similar to technologies such as JSP or JSTL include files.

Tiles can be assembled into a template page using conventional JSP tags from the Struts <tiles> tag library or by using an XML definition of a page which offers a more manageable reuse model with capabilities for reusing and extending definitions throughout the application.
This paper assumes the reader already has a working knowledge of Tiles, however, if you are not yet familiar with Tiles and would like to learn more then the following articles will provide a good introduction.

• The Tiles Developer Guide on the Struts Web Site
• Programming Jakarta Struts by Chuck Cavaness - Chapter 14
• Tiles Advanced Features by Cedric Dumoulin.

Tiles and ADF Working Together

Tiles can be successfully integrated with ADF data bound pages, but care must be taken to make sure that events such as page submissions go to the correct place. A common problem is using a DataPage with a Form on it as a tile. When the Form is submitted the submission goes to the DataPage itself rather than the while Tile set, so the chrome provided by the surrounding tiles is lost. The best approach when using tiles is to let the DataPage action be the top level entry point to a tile set, this has the advantage of removing the requirement to edit the JSP pages to redirect links and Form Actions, and also means that the DataPage can also be used to prepare data for binding onto any of the Tiles in the tile set.

Creating a DataPage for Use in a Tile Set.

1. First of all, create your DataPage (e.g. /deptEdit.do) as normal on the page flow diagram, drill into it and define the JSP that will be displayed by the DataPage.
2. In the JSP create the data bindings that you require for this screen as you would for a non-Tiles application.
3. Test your page at this point to make sure that you are seeing the data that you expect and that the functionality exposed by the page works correctly.
4. Now edit your tiles definition and nominate the JSP file name defined for the DataPage as the Tile content. For instance:

   <tiles-definitions xmlns="http://jakarta.apache.org/struts/dtds/tiles-config_1_1">
     <definition name="base.page" path="/templates/template.jsp">
       <put name="title" value="Not Used Directly"/>
       <put name="header" value="/tiles/header.jsp"/>
       <put name="footer" value="/tiles/footer.jsp"/>
       <put name="content" value=""/>
     </definition>
        ...
     <definition name="departments.edit" extends="base.page">
       <put name="title" value="Edit Department- Databound Screen"/>
       <put name="content" value="/deptEdit.jsp"/>
     </definition>
   </tiles-definitions>

5. Now switch to the Struts page flow and select the DataPage that you've just created in the structure pane.
6. In the property inspector, change the parameter attribute of the DataPage to point to the tiles definition (in this case "departments.edit") rather than the original JSP.
   So the action definition of:

       <action path="/deptEdit"
               className="oracle.adf.controller.struts.actions.DataActionMapping"
               type="oracle.adf.controller.struts.actions.DataForwardAction"
               name="DataForm"
              parameter="/deptEdit.jsp">
         <set-property property="modelReference" value="deptEditUIModel"/>
         <forward name="Submit" path="/deptView.do"/>
       </action>

   
   Is changed to:

       <action path="/deptEdit"
               className="oracle.adf.controller.struts.actions.DataActionMapping"
               type="oracle.adf.controller.struts.actions.DataForwardAction"
               name="DataForm"
               parameter="departments.edit">
         <set-property property="modelReference" value="deptEditUIModel"/>
         <forward name="Submit" path="/deptView.do"/>
       </action>

Now when you run or submit to the DataPage, the model integration will take place, and the required data placed on the request, after which the DataPage will forward to display the entire tiles set rather than just the original data bound JSP. This also means that you can use JSTL expressions on other tiles within the set to bind to data that the DataPage is preparing.

Simplifying the Editing of Tiles Definition Files

To help you in editing the tiles definition XML file you can register an XML schema with JDeveloper and associate this with your tiles definition. This will provide support for the tiles definition in the Structure Pane, Property Inspector and the XML editor itself with code insight and completion. An XML schema is not provided in the basic Struts distribution from Apache (it only comes with a DTD file). However, a XSD, created from the DTD is available on OTN for you to use. The figure below shows an extract from the XSD file shown in the JDeveloper XSD editor.

Installing the Schema in JDeveloper

To install the XSD file you will need to carry out the following steps

1. Download the XSD from OTN (here) and save it into the %JDeveloperHome%/jakarta-struts/lib directory.
2. From to Tools > Preferences menu, select the XML Schema option in the preference navigator and add a new schema:
   
   
3. Finally when you create a tiles-def.xml file, the only additional step you have to take is to add the XML namespace definition to the normal <tiles-definitions> top level element, so that it reads: <tiles-definitions xmlns="http://jakarta.apache.org/struts/dtds/tiles-config_1_1">. Once you reopen the XML document JDeveloper will provide full property inspector support and XML code insight to help with the creation and validation of your Tiles definitions.

Restrictions in 9.0.5.n of Oracle JDeveloper 10g

With the current release of JDeveloper, the page flow diagram is not set up to handle Tiles (XML) definition references directly. Thus an Action definition such as:

  <action path="/logon" forward="logon.view"/>

Will not display correctly on the diagram and the Action will show with the following icon , indicating that the Struts Diagram cannot find the underlying page.

Additionally if you try and create a Forward which uses an XML Tiles definition as the path attribute then additional "phantom" pages will be created on the diagram .
To avoid this problem you can either choose to work without the diagram enabled (see the technical tip "Suppressing the Struts Page Flow Diagram" on OTN) or you can define ActionForwards for each Tiles definition you will need as Forward targets in the flow. If you choose this technique then the flow will be correctly represented in the diagram, however, the ActionForwards will still be shown with the warning icon. Future versions of JDeveloper will recognize Tiles definitions as valid forward targets.

drmills v1.0 28/July/2004