How to Create a Page Template

19-14 Web User Interface Developers Guide for Oracle Application Development Framework Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework. 11. Within those components in the layout section where content can eventually be inserted by page authors using the template, drag FacetRef from the Component Palette and drop it in the desired location on the page. For example, if you have defined a main facet for the main content area on a page template, you might add the facetRef tag as a child in the center facet of panelStretchLayout component to reference the main facet. At design time, when the page author drops content into the main facet, the content is placed in the correct location on the page as defined in the template. When you use the facetRef tag to reference the appropriate named facet, JDeveloper displays the Insert FacetRef dialog. In that dialog, select a facet name from the dropdown list, or enter a facet name. If you enter a facet name that is not already defined in the component metadata of the page template definition file, JDeveloper automatically adds an entry for the new facet definition in the component metadata within the xmlContent tag. 12. To specify where attributes should be used in the page template, use the page template’s var attribute value to reference the relevant attributes on the appropriate components in the layout section. The var attribute of the pageTemplateDef tag specifies the EL variable name that is used to access the page template’s own attributes. As shown in Example 19–10 , the default value of var used by JDeveloper is attrs. For example, if you have defined a title attribute and added the panelHeader component, you might use the EL expression {attrs.title} in the text value of the panelHeader component, as shown in the following code, to reference the value of title: af:panelHeader text={attrs.title} 13. To include another file in the template layout, use the jsp:include tag wrapped inside the subview tag to reference a fragment file, as shown in the following code: f:subview id=secondaryDecoration jsp:include page=fileExplorerSecondaryDecoration.jspx f:subview The included fragment file must also be an XML document, containing only jsp:root at the top of the hierarchy. For more information about using fragments, see Section 19.2.3, How to Use a Page Fragment in a JSF Page. By creating a few fragment files for the components that define the template layout, and then including the fragment files in the page template definition, you can split up an otherwise large template file into smaller files for easier maintenance. Note: Each facet can be referenced only once in the layout section of the page template definition. That is, you cannot use multiple facetRef tags referencing the same facetName value in the same template definition. Creating and Reusing Fragments, Page Templates, and Components 19-15

19.3.2 What Happens When You Create a Page Template

The first time you use the wizard to create a JSF page template in a project, JDeveloper automatically creates the pagetemplate-metadata.xml file, which is placed in the ViewControllersrcMETA-INF directory in the file system. For each page template that you define using the wizard, JDeveloper creates a page template definition file for example, sampleTemplateDef1.jspx, and adds an entry to the pagetemplate-metadata.xml file. Example 19–11 shows an example of the pagetemplate-metadata.xml file. Example 19–11 Sample pagetemplate-metadata.xml File pageTemplateDefs xmlns=http:xmlns.oracle.comadffacesrichpagetemplate pagetemplate-jsp-ui-defsampleTemplateDef1.jspxpagetemplate-jsp-ui-def pagetemplate-jsp-ui-defsampleTemplateDef2.jspxpagetemplate-jsp-ui-def pageTemplateDefs The pagetemplate-metadata.xml file contains the names and paths of all the page templates that you create in a project. This file is used to determine which page templates are available when you use a wizard to create template-based JSF pages, and when you deploy a project containing page template definitions.

19.3.3 How to Create JSF Pages Based on Page Templates

Typically, you create JSF pages in the same project where page template definitions are created and stored. If the page templates are not in the same project as where you are going to create template-based pages, first deploy the page templates project to an ADF Library JAR. For information about deploying a project, see the Reusing Application Components chapter of the Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework. Deploying a page template project also allows you to share page templates with other developers working on the application. Note: If components in your page template use ADF Model data binding, or if you chose to associate an ADF page definition when you created the template, JDeveloper automatically creates files and folders related to ADF Model. For information about the files used with page templates and ADF Model data binding, the Using Page Templates section of the Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework. Note: When you rename or delete a page template in the Application Navigator, JDeveloper renames or deletes the page template definition file in the file system, but you must manually change or delete the page template entry in the pagetemplate-metadata.xml file, and update or remove any JSF pages that use the template. Note: If the template uses jsp:include tags, then it cannot be deployed to an ADF Library to be reused in other applications. 19-16 Web User Interface Developers Guide for Oracle Application Development Framework You can use page templates to build JSF pages or page fragments. If you modify the layout section of a page template later, all pages or page fragments that use the template are automatically updated with the layout changes. In the page that consumes a template, you can add content before and after the pageTemplate tag. In general, you would use only one pageTemplate tag in a page, but there are no restrictions for using more than one. JDeveloper simplifies the creation of JSF pages based on page templates by providing a template selection option in the Create JSF Page or Create JSF Page Fragment wizard. To create a JSF page or page fragment based on a page template: 1. Follow the instructions in Section 2.4.1, How to Create JSF JSP Pages to open the Create JSF Page dialog. In the dialog, select a page template to use from the Use Page Template dropdown list. By default, JDeveloper displays the new page or page fragment in the visual editor. The facets defined in the page template appear as named boxes in the visual editor. If the page template contains any default values, you should see the values in the Property Inspector, and if the default values have some visual representation for example, size, that will be reflected in the visual editor, along with any content that is rendered by components defined in the layout section of the page template definition.

2. In the Structure window, expand jsp:root until you see af:pageTemplate which

should be under af:form. Within the form tag, you can drop content before and after the pageTemplate tag. 3. Add components by dragging and dropping components from the Component Palette in the facets of the template. In the Structure window, within af:pageTemplate , the facets for example, f:facet - main that have been predefined in the component metadata section of the page template definition are shown. The type of components you can drop into a facet may be dependent on the location of the facetRef tag in the page template definition. For example, if you’ve defined a facetRef tag to be inside a table component in the page template definition, then only column components can be dropped into the facet because the table component accepts only column components as children.

4. In the Structure window, select af:pageTemplate. Then, in the Property Inspector,

you can see all the attributes that are predefined in the page template definition. Predefined attributes might have default values. Tip: Only page templates that have been created using the template wizard in JDeveloper are available for selection. If the Use Page Template dropdown list is disabled, this means no page templates are available in the project where you are creating new pages. Tip: The content you drop into the template facets may contain ADF Model data binding. In other words, you can drag and drop items from the Data Controls panel. For more information about using ADF Model data binding, see Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework. Creating and Reusing Fragments, Page Templates, and Components 19-17 You can assign static values to the predefined attributes, or you can use EL expressions for example, {myBean.somevalue}. When you enter a value for an attribute, JDeveloper adds the f:attribute tag to the code, and replaces the attribute’s default value if any with the value you assign see Example 19–12 . At runtime, the default or assigned attribute value is used or displayed in the appropriate part of the template, as specified in the page template definition by the EL expression that bears the name of the attribute such as {attrs.someAttributeName}. 5. To include resources, such as CSS or JavaScript, you need to use the af:resource tag. For more information, see Section 19.5, Adding Resources to Pages.

19.3.4 What Happens When You Use a Template to Create a Page

When you create a page using a template, JDeveloper inserts the pageTemplate tag, which references the page template definition, as shown in Example 19–12 . Any components added inside the template’s facets use the f:facet tag to reference the facet. Any attribute values you specified are shown in the f:attribute tag. Example 19–12 JSF Page that References a Page Template ?xml version=1.0 encoding=windows-1252? jsp:root xmlns:jsp=http:java.sun.comJSPPage version=2.0 xmlns:f=http:java.sun.comjsfcore xmlns:af=http:xmlns.oracle.comadffacesrich jsp:directive.page contentType=texthtml;charset=windows-1252 f:view af:document af:form . . . af:pageTemplate viewId=sampleTemplateDef1.jspx id=template1 f:attribute name=title value=Some Value f:facet name=main -- add contents here -- f:facet af:pageTemplate . . . af:form af:document Note: In addition to predefined template definition attributes, the Property Inspector also shows other attributes of the pageTemplate tag such as Id, Value, and ViewId. The ViewId attribute of the pageTemplate tag specifies the page template definition file to use in the consuming page at runtime. JDeveloper automatically assigns the ViewId attribute with the appropriate value when you use the wizard to create a template-based JSF page. The ViewId attribute value cannot be removed, otherwise a runtime error will occur, and the parts of the page that are based on the template will not render. 19-18 Web User Interface Developers Guide for Oracle Application Development Framework f:view jsp:root

19.3.5 What Happens at Runtime: How Page Templates Are Resolved

When a JSF page that consumes a page template is executed: ■ The pageTemplate component in the consuming page, using the viewId attribute for example, af:pageTemplate viewId=sampleTemplateDef1.jspx, locates the page template definition file that contains the template component metadata and layout. ■ The component subtree defined in the layout section of the pageTemplateDef tag is instantiated and inserted into the consuming page’s component tree at the location identified by the pageTemplate tag in the page. ■ The consuming page passes facet contents into the template using the facet tag. The facet contents of each facet tag are inserted into the appropriate location on the template as specified by the corresponding facetRef tag in the layout section of the pageTemplateDef tag. ■ The consuming page passes values into the template by using the attribute tag. The pageTemplateDef tag sets the value of the var attribute so that the pageTemplate tag can internally reference its own parameters. The pageTemplate tag just sets the parameters; the runtime maps those parameters into the attributes defined in the pageTemplateDef tag. ■ Using template component metadata, the pageTemplate tag applies any default values to its attributes and checks for required values. For information about what happens when the page template uses ADF Model data binding, see the Using Page Templates section of the Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework.

19.3.6 What You May Need to Know About Page Templates and Naming Containers

The pageTemplate component acts as a naming container for all content in the template whether it is direct content in the template definition, or fragment content included using the jsp:include action. When working with client-side events in template-based pages, you must include the template’s ID when using code to locate a component. For more details, see Section 5.3.7, What You May Need to Know About Using Naming Containers.

19.4 Using Declarative Components

Declarative components are reusable, composite UI components that are made up of other existing ADF Faces components. Suppose you are reusing the same components consistently in multiple circumstances. Instead of copying and pasting the commonly Note: Page templates are processed during JSP execution, not during JSF processing that is, component tree creation. This means that fragments built from page templates cannot be used within tags that require the component tree creation. For example, you could not include a fragment based on a template within an iterator tag and expect it to be included in a loop.