As Published In July/August 2008

TAGS frameworks, All

By Steve Muench

Easily enforce consistent look and feel with page templates.

When creating a professional-looking presentation, you define a consistent layout and style for all your slides by editing the "master slide." You can concentrate on the content and easily change the look later. Using an analogous new feature in the upcoming Oracle JDeveloper/Oracle Application Development Framework (Oracle ADF) 11g release, you design a "master page" to enforce a consistent layout and style for all the pages in your Web application. In this column, we define a page template including common UI elements—or "chrome," as Web designers call it—and then create a JavaServer Faces (JSF) page based on this template. After testing the template-based page, we'll change the template and see it reflected in the page automatically.

To continue, download the starter workspace and ensure that you're using the Oracle JDeveloper 11.1.1.0 Technology Preview 4 release, available as a free download on the Oracle Technology Network at otn.oracle.com/products/jdev/11. Start by extracting the contents of the o48frame.zip file and opening the FrameworksJulAug2008.jws workspace in Oracle JDeveloper. Note that the Model project in the workspace defines a Dept entity object, a DeptView view object, and an HRModule application module. Also, adjust the properties of the scott connection in the Application Resources zone of the Application Navigator until you can successfully test a connection to a SCOTT schema. If you need to create the tables, use the provided CreateDeptEmpTables.sql.

Creating the Page Template

The page template will include UI components to achieve the base layout and will include one or more pluggable content zones at appropriate places. These content zones are represented by JSF facets, which we'll define here. When we create a page based on the template, we will use the visual editor to populate the appropriate template facets with page-specific content.

In the Application Navigator, right-click the ViewController project and choose New. When the New Gallery dialog box appears, select the JSF category under the Web Tier node in the tree at the left; then in the Items list at the right, select JSF Page Template, and click OK. When the Create JSF Page Template dialog box appears, change the default value of Page Template Name to MainTemplate. Note that the File Name field updates automatically to assign a corresponding name to the JSPX file that will represent the template. Also note the Create Associated ADFm Page Definition check box. When designing your own templates, you should check this box if you plan to include data-bound content, such as user profile information you have queried from a UserProfileInfo view object, in the page template. However, for our simple example, you can leave this unchecked.

Now let's define two facets, one for the main content area of the page and another for a button bar of "actions." First, we'll simply define the facet names. (In the next step—when designing the layout of the page template—we'll add placeholders that represent these facets in the precise location on the page where we want their content to appear.) To define a facet, click the Facet Definitions tab in the Create JSF Page Template dialog box and then click Add to create a new facet. An empty row appears in the table, with a default facet name of facet1. Edit the name to be MainContentArea, and provide a description for the region, such as The main area for content. Click Add again to define a second facet, name it ActionButtonBar, and enter Buttons to perform actions go here as the description. Finally, click OK to define the new page template. After a moment, the MainTemplate.jspx page will open in the visual editor.

Designing the Page Template

We'll start by adding the standard layout elements that we want to appear on every page of our application. Before starting, ensure that the Component Palette and the Property Inspector are visible. If the contents of either or both are hidden, select the appropriate option(s) in the View menu to show them. Ensure also that the list at the top of the Component Palette displays the ADF Faces category of components. If the contents of the Layout section of the Component Palette are hidden, drag the section heading up to reveal the layout components.

From Component Palette -> ADF Faces -> Layout, drag a Panel Stretch Layout component and drop it into the middle of the empty page. In the Property Inspector, select the Style page, click the Background tab, and select Aqua from the Color list. Move your cursor over the different areas in the Panel Stretch Layout component labeled start, end, top, bottom, and center, and note how this component divides the space on the page into zones, known as facets. Next, from Component Palette -> ADF Faces -> Layout, drag a Spacer component and drop it into the start facet. Drag and drop another Spacer component into the end facet, and then drag and drop one more Spacer component into the bottom facet. These will cause a border to appear around the left, right, and bottom edges of the page.

Next, from Component Palette -> ADF Faces -> Layout, drop a Panel Group Layout component into the top facet to contain a text component for the application name and the button bar and drop another Panel Stretch Layout component into the center facet to contain the main content area. In the Common page of the Property Inspector, set the StartWidth, TopHeight, EndWidth, and BottomHeight of this inner Panel Stretch Layout component to 0 (zero), and in the Style page, click the Background tab and select White from the Color list. From the Common Components section of the Component Palette, drag an OutputText component and drop it inside the Panel Group Layout component in the upper left corner of the top facet. (You can drop it either onto the visual editor or onto that component in the Structure Window.) On the Common page of the Property Inspector, enter My Application in the Value field, and on the Style page's Text tab, select large from the Size menu. Drag and drop another Spacer component (Component Palette -> ADF Faces -> Layout) after this OutputText component, and then drag and drop another Panel Group Layout component after that to contain the action buttons.

Finally, we'll add in the references to the two placeholder facets we defined when we created the template. In the Common Components section of the Component Palette, drag a Facet Ref component and drop it into the center of the page. When the Insert Facet Ref dialog box appears, choose the MainContentArea facet from the Facet Name list and click OK. Repeat the process to drag and drop a second Facet Ref component inside the Panel Group Layout component you dropped to the right of the My Application OutputText component. Note how the user-defined facets in the template appear as named boxes with a dotted line around them. As we'll see shortly, when you build a page based on a template, these will be the only areas where custom content can be created. When the Insert Facet Ref dialog box appears, choose the ActionButtonBar facet from the Facet Name list and click OK. We're done with the page template, so save all your work.

Using the Page Template

Next, we'll create a JSF page that's based on our new page template. Right-click the ViewController project and choose New. Select the JSF category, the JSF Page item in that category, and then click OK. Enter Departments. as the JSF page File Name, and from the Use Page Template list, choose MainTemplate to use the page template we created above. Then click OK to create the page.

Next Steps READ more Frameworks READ more about Oracle JDeveloper and Oracle ADF otn.oracle.com/products/jdev otn.oracle.com/products/jdev/tips/muench/designpatterns Oracle ADF Developer's Guide DOWNLOAD Oracle JDeveloper 11g Technology Preview Starter workspace for this column

In the visual editor, note that the layout inherited from the page template appears but looks disabled to remind you that it cannot be changed. In a page based on a template, you can add content only to the outlined facets, such as MainContentArea and ActionButtonBar in our example. Expand the Data Controls zone of the Application Navigator, and expand the HRModuleDataControl node. Drag the Departments data collection, and drop it into the MainContentArea facet. When the Create menu appears, select Forms -> ADF Read-only Form. When the Edit Form Fields dialog box appears, click OK to accept the defaults. Next, expand the Departments data collection in the Data Controls zone of the Application Navigator and expand the Operations folder it contains. Drag the Next operation, and drop it into the ActionButtonBar facet. When the Create menu appears, select ADF Button. Now drag the Previous operation (from Data Controls -> Departments -> Operations), and drop it as a second ADF Button to the left of the Next button you just created.

Test your creation by right-clicking the Departments.jspx page in the Application Navigator and choosing Run. When the page appears in your default browser, you'll see the inherited page template "chrome" and the page-specific content merged together. Click the action buttons to verify that they work.

Changing the Template

Let's say your UI design staff comes back months after the application is already in production and demands that the standard template border be changed from aqua to lime to keep up with the times. With a page template in place, making such visual changes after the fact is easy. To see it in action, open MainTemplate.jspx in the visual editor, and in the Structure Window, select the topmost panelStretchLayout that is the first child element under the pageTemplateDef element. Select the Style page in the Property Inspector, select the Background tab, and select Lime from the Color list. Save the template, and then rerun the Departments.jspx page to see the effect of your change.

We've explored only a very simple example here, but hopefully you can appreciate how powerful this highly requested feature will be in your future Oracle ADF development efforts.