How to Create a Declarative Component

19-24 Web User Interface Developers Guide for Oracle Application Development Framework 12. Within those components in the layout section where content can eventually be inserted by page authors using the component, use the facetRef tag to reference the appropriate named facet. For example, if you have defined a content facet for the main content area, you might add the facetRef tag as a child in the panelBox component to reference the content facet. At design time, when the page developer drops components into the content facet, the components are placed in the panelBox component. When you drag FacetRef from the Component Palette and drop it in the desired location on the page, 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 definition file, JDeveloper automatically adds an entry for the new facet definition in the component metadata within the xmlContent tag. 13. To specify where attributes should be used in the declarative component, use the Property Inspector and the Expression Builder to bind component attribute values to the created attributes. For example, if you have defined a title attribute and added a panelBox as a component, you might use the dropdown menu next to the text attribute in the Property Inspector to open the Expression Builder, as shown in Figure 19–4 . Figure 19–4 Opening the Expression Builder for an Attribute in the Property Inspector In the Expression Builder, you can expand the JSP Objects attrs node to select the created attribute that should be used for the value of the attribute in the Property Inspector. For example, Figure 19–5 shows the title attribute selected in the Expression Builder. Click the Insert Into Expression button and then click OK to add the expression as the value for the attribute. Note: Each facet can be referenced only once. That is, you cannot use multiple facetRef tags referencing the same facetName value in the same declarative component definition. Creating and Reusing Fragments, Page Templates, and Components 19-25 Figure 19–5 Expression Builder Displays Created Attributes 14. To specify the methods that command buttons in the declarative component should invoke, use the dropdown menu next to that component’s actionListener attribute and choose Edit to open the Edit Property dialog. This dialog allows you to choose one of the declarative methods you created for the declarative component. In the dialog, select Declarative Component Methods, select the declarative method from the dropdown list, and click OK.

19.4.2 What Happens When You Create a Declarative Component

When you first use the Create JSF Declarative Component wizard, JDeveloper creates the metadata file using the name you entered in the wizard. The entire definition for the component is contained in the componentDef tag. This tag uses two attributes. The first is var, which is a variable used by the individual components to access the attribute values. By default, the value of var is attrs. The second attribute is componentVar, which is a variable used by the individual components to access the methods. By default the value of componentVar is component. The metadata describing the facets, attributes, and methods is contained in the xmlContent tag. Facet information is contained within the facet tag, attribute information is contained within the attribute tag, and method information is contained within the component-extension tag, as is library information. Example 19–13 shows abbreviated code for the declarative component shown in Figure 19–2 . Example 19–13 Declarative Component Metadata in the xmlContent Tag af:xmlContent component xmlns=http:xmlns.oracle.comadffacesrichcomponent display-namemyPanelBoxdisplay-name facet descriptionHolds the content in the panel boxdescription facet-nameContentfacet-name facet attribute attribute-nametitleattribute-name 19-26 Web User Interface Developers Guide for Oracle Application Development Framework attribute-classjava.lang.Stringattribute-class requiredtruerequired attribute attribute attribute-namebuttonText1attribute-name attribute-classjava.lang.Stringattribute-class attribute . . . component-extension component-tag-namespacecomponentcomponent-tag-namespace component-taglib-uricomponentLib1component-taglib-uri method-attribute attribute-namemethod1attribute-name method-signature void methodjavax.faces.event.ActionEvent method-signature method-attribute method-attribute attribute-namemethod2attribute-name method-signature void methodjavax.faces.event.ActionEvent method-signature method-attribute . . . component-extension component af:xmlContent Metadata for the included components is contained after the xmlContent tag. The code for these components is the same as it might be in a standard JSF page, including any attribute values you set directly on the components. Any bindings you created to the attributes or methods use the component’s variables in the bindings. Example 19–14 shows the code for the panelBox component with the three buttons in the toolbar. Notice that the facetRef tag appears as a child to the panelBox component, as any content a page developer will add will then be a child to the panelBox component. Example 19–14 Components in a Declarative Component af:panelBox text={attrs.title} inlineStyle=width:25; f:facet name=toolbar af:group af:toolbar af:commandToolbarButton text={attrs.buttonText1} actionListener={component.handleMethod1} rendered={attrs.display1} af:commandToolbarButton text={attrs.buttonText2} rendered={attrs.display2} actionListener={component.handleMethod2} af:commandToolbarButton text={attrs.buttonText3} rendered={attrs.display3} actionListener={component.handleMethod3} af:toolbar af:group f:facet af:facetRef facetName=Content af:panelBox Creating and Reusing Fragments, Page Templates, and Components 19-27 The first time you use the wizard to create a declarative component in a project, JDeveloper automatically creates the declarativecomp-metadata.xml file, which is placed in the ViewControllersrcMETA-INF directory in the file system. For each declarative component that you define using the wizard, JDeveloper creates a declarative component definition file for example, componentDef1.jspx, and adds an entry to the declarativecomp-metadata.xml file. Example 19–15 shows an example of the declarativecomp-metadata.xml file. Example 19–15 Sample declarativecomp-metadata.xml File declarativeCompDefs xmlns=http:xmlns.oracle.comadffacesrichdeclarativecomp declarativecomp-jsp-ui-def componentDef1.jspx declarativecomp-jsp-ui-def declarativecomp-taglib taglib-name dCompLib1 taglib-name taglib-uri dcomponentLib1 taglib-uri taglib-prefix dc taglib-prefix declarativecomp-taglib declarativeCompDefs The declarativecomp-metadata.xml file contains the names, paths, and tag library information of all the declarative components you create in the project. When you deploy the project, the metadata is used by JDeveloper to create the JSP tag libraries and Java classes for the declarative components.

19.4.3 How to Deploy Declarative Components

Declarative components require a tag library definition TLD in order to be displayed. JDeveloper automatically generates the TLD when you deploy the project. Because of this, you must first deploy the project that contains your declarative components before you can use them. This means before you can use declarative components in a project, or before you can share declarative components with other developers, you must deploy the declarative component definitions project to an ADF Library JAR. For instructions on how to deploy a project to an ADF Library JAR, see the Reusing Application Components chapter of the Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework. Briefly, when you deploy a project that contains declarative component definitions, JDeveloper adds the following for you to the ADF Library JAR: Note: When you rename or delete a declarative component in the Application Navigator, JDeveloper renames or deletes the declarative component definition file in the file system, but you must manually change or delete the declarative component entry in the declarativecomp-metadata.xml file, and update or remove any JSF pages that use the declarative component. 19-28 Web User Interface Developers Guide for Oracle Application Development Framework ■ A component tag class for example, the componentDef1Tag.class for each declarative component definition that is, for each componentDef component ■ One or more JSP TLD files for the declarative components, using information from the project’s declarativecomp-metadata.xml file To use declarative components in a consuming project, you add the deployed ADF Library JAR to the project’s properties. For instructions on how to add an ADF Library JAR, see the Reusing Application Components chapter of the Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework. By adding the deployed JAR, JDeveloper automatically inserts the JSP tag library or libraries which contain the reusable declarative components into the project’s properties, and also displays them in the Component Palette.

19.4.4 How to Use Declarative Components in JSF Pages

In JDeveloper, you add declarative components to a JSF page just like any other UI components, by selecting and dragging the components from the Component Palette, and dropping them into the desired locations on the page. Your declarative components appear in a page of the palette just for your tag library. Figure 19–6 shows the page in the Component Palette for a library with a declarative component. Figure 19–6 Component Palette with a Declarative Component When you drag a declarative component that contains required attributes onto a page, a dialog opens where you enter values for any defined attributes. Once the declarative component is added to the page, you must manually bind the declarative methods to actual methods on managed beans. Before proceeding with the following procedure, you must already have added the ADF Library JAR that contains the declarative components to the project where you are creating JSF pages that are to consume the declarative components. For instructions on how to add an ADF Library JAR, see the Reusing Application Components chapter of the Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework. To use declarative components in a JSF page: 1. In the Application Navigator, double-click the JSF page or JSF page template to open it in the visual editor. 2. In the Component Palette, select the declarative components tag library name from the dropdown list. Drag and drop the desired declarative component onto the page. You can add the same declarative component more than once on the same page. If the declarative component definition contains any required attributes, JDeveloper opens a dialog for you to enter the required values for the declarative component that you are inserting.