How to Create JSF Pages Based on Page Templates

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. Creating and Reusing Fragments, Page Templates, and Components 19-19 used UI elements repeatedly, you can define a declarative component that comprises those components, and then reuse that composite declarative component in multiple places or pages. To use declarative components in an application, you first create an XML-based declarative component definition, which is a JSF document written in XML syntax with a file extension of .jspx. Declarative component JSF files do not contain the f:view and document tags, and they must have componentDef as the root tag. The entire description of a declarative component is defined within two sections. One section is xmlContent, which contains all the page template component metadata that describes the declarative component’s supported content areas. A declarative component’s metadata includes the following: ■ Facets: Facets act as placeholders for the content that will eventually be placed in the individual components that make up the declarative component. Each component references one facet. When page designers use a declarative component, they insert content into the facet, which in turn, allows the content to be inserted into the component. ■ Attributes: You define attributes whose values can be used to populate attributes on the individual components. For example, if your declarative component uses a panelHeader component, you may decide to create an attribute named Title. You may then design the declarative component so that the value of the Title attribute is used as the value for the text attribute of the panelHeader component. You can provide default values for attributes that the user can then override. ■ Methods: You can define a method to which you can bind a property on one of the included components. For example, if your declarative component contains a button, you can declare a method name and signature and then bind the Note: The view parts of a page fragments, declarative components, and the main page all share the same request scope. This may result in a collision when you use the same fragment or declarative component multiple times on a page, and when they share a backing bean. For more information about scopes, see Section 4.6, Object Scope Lifecycles. Tip: Facets are the only area within a declarative component that can contain content. That is, when used on a JSF page, a declarative component may not have any children. Create facets for all areas where content may be needed. Tip: Because users of a declarative component will not be able to directly set attributes on the individual components, you must be sure to create attributes for all attributes that you want users to be able to set or override the default value. Additionally, if you want the declarative component to be able to use client-side attributes for example, attributeDragSource, you must create that attribute and be sure to include it as a child to the appropriate component used in the declarative component. For more information, see Section 19.4.1, How to Create a Declarative Component. 19-20 Web User Interface Developers Guide for Oracle Application Development Framework actionListener attribute to the declared method. When page developers use the declarative component, they rebind to a method on a managed bean that contains the logic required by the component. For example, say your declarative component contains a button that you knew always had to invoke an actionEvent method. You might create a declarative method named method1 that used the signature void methodjavax.faces.event.ActionEvent. You might then bind the actionListener attribute on the button to the declared method. When page developers use the declarative component, JDeveloper will ask them to provide a method on a backing bean that uses the same signature. ■ Tag library: All declarative components must be contained within a tag library that you import into the applications that will use them. The second section anything outside of the xmlContent tag is where all the components that make up the declarative component are defined. Each component contains a reference back to the facet that will be used to add content to the component. To use declarative components in a project, you first must deploy the library that contains the declarative component as an ADF Library. You can then add the deployed ADF Library JAR to the project’s properties, which automatically inserts the JSP tag library or libraries into the project’s properties. Doing so allows the components to be displayed in the Component Palette so that you can drag and drop them onto a JSF page. For example, say you want to create a declarative component that uses a panelBox component. In the panelBox component’s toolbar, you want to include three buttons that can be used to invoke actionEvent methods on a backing bean. To do this, create the following: ■ One facet named Content to hold the content of the panelBox component. ■ One attribute named Title to determine the text to display as the panelBox component’s title. ■ Three attributes one for each button, named buttonText1, buttonText2, and buttonText3 to determine the text to display on each button. ■ Three attributes one for each button, named display1, display2, display3 to determine whether or not the button will render, because you do not expect all three buttons will be needed every time the component is used. ■ Three declarative methods one for each button, named method1, method2, and method3 that each use the actionEvent method signature. ■ One panelBox component whose text attribute is bound to the created Title attribute, and references the Content facet. ■ Three toolbarButton components. The text attribute for each would be bound to the corresponding buttonText attribute, the render attribute would be bound to the corresponding display attribute, and the actionListener attribute would be bound to the corresponding method name. Figure 19–2 shows how such a declarative component would look in the visual editor.