What Happens When You Create a 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. Creating and Reusing Fragments, Page Templates, and Components 19-29 3. Add components by dragging and dropping components from the Component Palette in the facets of the template. In the Structure window, expand the structure until you see the element for the declarative component, for example, dc:myPanelBox, where dc is the tag library prefix and myPanelBox is the declarative component name. Under that are the facets for example, f:facet - content that have been defined in the declarative component definition. You add components to these facets. You cannot add content directly into the declarative component; you can drop content into the named facets only. The types of components you can drop into a facet may be dependent on the location of the facetRef tag in the declarative component definition. For example, if you have defined facetRef to be a child of table in the declarative component definition, then only column components can be dropped into the facet because table accepts column children only. 4. In the Structure window, again select the declarative component element, for example, dc:myPanelBox. The Property Inspector displays all the attributes and methods that have been predefined in the declarative component definition for example, title. The attributes might have default values. You can assign static values to the attributes, or you can use EL expressions for example, {myBean.somevalue}. For any of the methods, you must bind to a method that uses the same signature as the declared method defined on the declarative component. At runtime, the attribute value will be displayed in the appropriate location as specified in the declarative component definition by the EL expression that bears the name of the attribute for example, {attrs.someAttributeName}. 5. If you need to include resources such as CSS or JavaScript, then you need to include these using the af:resource tag. For more information, see Section 19.5, Adding Resources to Pages.

19.4.5 What Happens When You Use a Declarative Component on a JSF Page

After adding a declarative component to the page, the visual editor displays the component’s defined facets as named boxes, along with any content that is rendered by components defined in the component layout section of the declarative component definition. Like other UI components, JDeveloper adds the declarative component tag library namespace and prefix to the jsp:root tag in the page when you first add a declarative component to a page, for example: jsp:root xmlns:dc=dcomponentLib1: .. Note: If you want to use ADF Model layer bindings as values for the attributes, then to create these bindings manually by using the Expression Builder to locate the needed binding property. Note: You cannot place any components as direct children of a declarative component. All content to appear within a declarative component must be placed within a facet of that component. 19-30 Web User Interface Developers Guide for Oracle Application Development Framework In this example, dc is the tag library prefix, and dcomponentLib1 is the namespace. JDeveloper adds the tag for the declarative component onto the page. The tag includes values for the component’s attributes as set in the dialog when adding the component. Example 19–16 shows the code for the MyPanelBox declarative component to which a user has added a panelGroupLayout component that contains three outputFormatted components. Example 19–16 JSF Code for a Declarative Component that Contains Content dc:myPanelBox title=My Panel Box buttonText1=Button 1 display1=true display2=true buttonText2=Button 2 display3=false f:facet name=Content af:panelGroupLayout layout=scroll af:outputFormatted value=outputFormatted1 styleUsage=instruction af:outputFormatted value=outputFormatted2 styleUsage=instruction af:outputFormatted value=outputFormatted3 styleUsage=instruction af:panelGroupLayout f:facet dc:myPanelBox

19.4.6 What Happens at Runtime

When a JSF page that consumes a declarative component is executed: ■ The declarative component tag in the consuming page locates the declarative component tag class and definition file that contains the declarative component metadata and layout. ■ The component subtree defined in the layout section of the componentDef tag is instantiated and inserted into the consuming page’s component tree at the location identified by the declarative component tag in the page. ■ The componentDef tag sets the value of the var attribute so that the declarative component can internally reference its own attributes. The declarative component just sets the attribute values; the runtime maps those values into the attributes defined in the componentDef tag. ■ Using declarative component metadata, the declarative component applies any default values to its attributes and checks for required values. ■ The consuming page passes facet contents into the declarative component by using the facet tag. The facet contents of each facet tag are inserted into the appropriate location on the declarative component as specified by the corresponding facetRef tag in the layout section of the componentDef tag.

19.5 Adding Resources to Pages

You should use the af:resource tag to add CSS or JavaScript to pages, page templates, or declarative components. This tag is especially useful for page templates and declarative components because resources can only be added to the page in the HTML head element. When you can use this tag in page templates and declarative components, the resources will be added to the consuming page during JSP execution. If this tag is not used, browsers may need to re-layout pages that use page templates and declarative components whenever it encounters a style or link tag. The resources