What Happens When You Use a Template to Create a Page

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. Creating and Reusing Fragments, Page Templates, and Components 19-21 Figure 19–2 Declarative Component in the Visual Editor When a page developer drops a declarative component that contains required attributes or methods onto the page, a dialog opens asking for values. If the developer set values where only the first two buttons would render, and then added a panelGroupLayout component with output text, the page would render as shown in Figure 19–3 . Figure 19–3 Displayed Declarative Component If your declarative component requires resources such as custom styles defined in CSS or JavaScript, then you need to include these using the af:resource tag on the consuming page. For more information, see Section 19.5, Adding Resources to Pages.

19.4.1 How to Create a Declarative Component

JDeveloper simplifies creating declarative component definitions by providing the Create JSF Declarative Component wizard, which lets you create facets, and define attributes and methods for the declarative component. The wizard also creates metadata in the component-extension tile that describes tag library information for the declarative component. The tag library metadata is used to create the JSP tag library for the declarative component. First you add the template component metadata for facets and attributes inside the xmlContent section of the componentDef tag. After you have added all the necessary component metadata for facets and attributes, then you add the components that define the actual layout of the declarative component in the section outside of the xmlContent section. Note: You cannot use fragments or ADF databound components in the component layout of a declarative component. If you think some of the components will need to be bound to the ADF Model layer, then create attributes for those component attributes that need to be bound. The user of the declarative component can then manually bind those attributes to the ADF Model layer. Additionally, because declarative components are delivered in external JAR files, the components cannot use the jsp:include tag because it will not be able to find the referenced files.