Create and Use a JSF Declarative Component

You can work in JDeveloper's IDE to create JSF declarative component definitions in a project, deploy the project that contains the definitions, and then use the declarative components on JSF pages in another project.

Create New Applications: Use the Create Application wizard to create one ADF web application and one generic application.

Create a Declarative Component Definition in a Project: Use the Create JSF Declarative Component dialog to create declarative component metadata, and then use ADF Faces components to create the declarative component layout.

Deploy the Project that Contains Declarative Component Definitions: Create a deployment profile for an ADF Library JAR and deploy the project.

Load the ADF Library JAR in a Project: Use the Resource Palette to add the ADF Library JAR to a project that will make use of the declarative components.

Create a Page and Add the Declarative Component: Use the Create JSF Page dialog to add a new page, and then insert the declarative component on the page just like you would with any other ADF Faces component.

Use the Declarative Component: Use the Property Inspector to add a label. Use the Create Managed Bean dialog to add and attach a managed bean method.

Use the Source Editor to Add Java Code: In the source editor, add event code to the bean method.

Create New Applications

1. Open the Create Application wizard [ File > New > General > Applications]  .
2. To follow along with the example, enter the application name MyWebApp.
3. Select Fusion Web Application (ADF) in the Applica tion Template list, and click Finish .
   

   Application Templates

   Application templates provide you with a quick way to create the project structure for standard applications with the appropriate combination of technologies already specified. The new application created from the template appears in the Application Navigator already partitioned into tiered projects, with the associated technology scopes set in each project.   [ tell me more...]

   
   
   
4. Open the Create Application wizard [ File > New > General > Applications]  again.
5. Enter the application name as DeclarativeComponents. Select Generic Application in the Applica tion Template list, and click Next .
6. Enter the project name DeclarativeComponents, and click Finish .
7. In the Application Navigator, select the project you just created and open the Project Properties dialog, JSP Tag Libraries Page. [ Application > Project Properties] 
8. Select the Distributed Libraries folder, then click Add .
9. In the Choose Tag Libraries dialog, select ADF Faces Components 11 and click OK.
   

   JSP Tag Libraries

   Libraries are provided for the various APIs and technologies installed with JDeveloper. These libraries are categorized as extension libraries, which are shared by all users of an install.   [ tell me more...]

   
   
   
10. Click OK to close the Project Properties dialog.
11. Click Save All to save your work.
    

    In the IDE

    When you complete the steps for creating applications, the Projects panel in the DeclarativeComponents application in the Application Navigator should look like this:  [ tell me more...]

    
    
    

Create the Metadata for a JSF Declarative Component

1. If necessary, select DeclarativeComponents from the dropdown list in the Application Navigator to switch to the DeclarativeComponents application.
2. In the Application Navigator, select the DeclarativeComponents project and open the Create JSF Declarative Component dialog [ File > New > Web Tier > JSF > JSF Declarative Component] .
3. Enter myMenubar as the declarative component name. Click Add Ta g Library to open the Create Declarative Component Tag Library dialog. To follow along with the example, use MyDeclComponents for the tag library name, /mycomponents for the tag library URI, and mc for the tag library prefix. Then click OK.
   

   Declarative Component Name and Tag Library

   The declarative component name you specify in the Create JSF Declarative Component dialog will be used as the display name of the declarative component in the Component Palette, as well as the name of the Java class generated for the component tag. Only alphanumeric characters are allowed in the name for the declarative component, for example, SampleName or SampleName1.  [ tell me more...]

   
   
   
4. In the Create JSF Declarative Component dialog, with the Facet Definitions tab in front, click Add to add a placeholder for future content. Enter moreMenus in the Name field.
   

   Facet Definitions, Attributes, and Methods

   Declarative components can have facets, attributes, and methods that enable page authors to configure how the declarative component is used on different pages or different portions of a page. For instance, you might add attributes to allow page authors to change the labels of the individual buttons in the declarative component.   [ tell me more...]

   
   
   
5. Click Attributes to bring the tab to the front, then click Add to add an attribute for setting on the declarative component later. Enter menuLabel in the Name field. Accept java.lang.String as the default type.
6. Click Methods to bring the tab to the front, then click Add to add a method for registering on the declarative component later. Accept method1 as the default method name. Enter void method(javax.faces.event.ActionEvent) in the Method Signature field. Click OK.
7. Click Save All to save your work.
   

   In the IDE

   When you complete the steps for creating the metadata for your declarative component, the visual editor displays the declarative component definition file as a blank page in the visual editor. In the Structure window, you should see something like this, if the af:componentDef node is expanded   [ tell me more...]

   
   
   

Define the Layout of the Declarative Component

1. In the Component Palette, ADF Faces page, Common Components panel, drag Panel Menu Bar and drop it on the blank page in the visual editor.
2. Drag and drop Menu into the panel menu bar you just added. (You should see a target rectangle with the name Panel Menu Bar on the page; this means the component you are dragging will be inserted inside that target component.)
3. In the Property Inspector, Common section, change the Text property value to File.
4. In the Component Palette, Common Components panel, drag and drop Menu Item into the menu component you just added. In the Property Inspector, Common section, change the Text property to Delete.
5. In the Property Inspector, Appearance section, choose Edit from the dropdown menu next to the Icon field. Then use the dialog to locate and select an image (for example, delete.png) for the menu item component. When prompted, click Yes to add the icon image under the document root and then click Save.
   

   Adding Images

   You can add any image by navigating to it and selecting it. To choose an image from the JDeveloper images library, in the Edit Property dialog locate the <jdev_home>/jdeveloper/ide/lib/ folder and double-click oicons.jar to open it. Then navigate to oracle/javatools/icons and select an icon, such as delete.png and click OK.   [ tell me more...]

   
   
   
6. In the Component Palette, Common Components panel, drag and drop Menu Item into the af:menu - File element in the Structure window.
7. In the Property Inspector, Appearance section, choose Edit from the dropdown menu next to the Icon field. Then use the dialog to locate and select another image (for example, user.png) for the menu item component you just added. When prompted, click Yes to add the icon image under the document root and then click Save.
8. In the Property Inspector, Text field, delete the default property value, then choose Expression Builder from the dropdown menu. In the Expression Builder, expand JSP Objects, then expand attrs. Click menuLabel to create the expression #{attrs.menuLabel}. Click OK. You should see the expression you created in the Text field in the Property Inspector.
   

   Expression Language

   Expression Language (EL) allows you to use simple expressions in JSF pages to access data stored in objects or reference and invoke methods.   [ tell me more...]

   
   
   
9. In the Property Inspector, Common section, under Menu Action, choose Edit from the dropdown menu next to the ActionListener field.
10. In the Edit Property dialog, select Declarative Component Methods . Make sure method1 is selected in the dropdown list. Click OK. You should see the expression #{component.handleMethod1}in the ActionListener field in the Property Inspector.
11. In the Component Palette, Common Components panel, drag and drop Facet Ref into the af:menuBar element in the Structure window. In the Insert Facet Ref dialog, select moreMenus from the dropdown list. Then click OK.
12. Click Save All to save your work.
    

    In the IDE

    When you complete the steps for defining the layout of your declarative component, the visual editor should look similar to this:  [ tell me more...]

    
    
    

Deploy the Definition Project to an ADF Library JAR

1. In the Application Navigator, select the DeclarativeComponents project. From the main menu choose Build Deplo y New Deployment Profile . In the New Gallery, make sure ADF Library Jar File is selected, then click OK.
2. Accept adflibDeclarativeComponents1 as the deployment profile name. Click OK.
   

   Default Values for Deployment Profile Name and ADF Library JAR File Name

   JDeveloper uses the following format to create a default deployment profile name for you:   [ tell me more...]

   
   
   
3. Click OK to close the Edit ADF Library JAR Deployment Profile Properties dialog, accepting all the default values.
4. In the Project Properties dialog, Deployment page, you should see that adflibDeclarativeComponents1 (ADF Library JAR File) has been added to the list. Click OK.
5. Click Save All to save your work.
6. In the Application Navigator, right-click the DeclarativeComponents project and choose Deplo y adflibDeclarativeComponents1. In the Deploy wizard, make sure Deploy to ADF Library JAR file is selected. Click Finish to start deployment.
   

   ADF Library JAR Files

   When you deploy a declarative component definition project to an ADF Library JAR, JDeveloper compiles the project, creates the necessary artifacts and control files, and packages the relevant project files (such as any image files) into a JAR. The JAR also includes the tag library descriptor file ( .tld file), and component and tag classes created for the declarative component.  [ tell me more...]

   
   
   
7. In the Deployment Log window, note the location of the deploy folder that contains the ADF Library JAR file.
   

   In the IDE

   When you finish deploying the declarative component definition project to an ADF Library JAR file, the Deployment Log window should look something like this:  [ tell me more...]

   
   
   

Create a File System Connection and Add the ADF Library JAR to a Project

1. If not already open, choose View Resource Palette from the main menu to open the Resource Palette.
2. In the Resource Palette, IDE Connections panel, open the Create File System Connection dialog [ File > New > General > Connections > File System Connection] .
   

   Resource Palette

   The Resource Palette provides an easy and efficient way to distribute and use ADF Library JAR files. Once an ADF Library JAR is added to the Resource Palette, other developers will be able to search for it and add it to their projects.  [ tell me more...]

   
   
   
3. In the Create File System Connection dialog, confirm that IDE Connections is selected.
4. Enter DeclarativeComponents as the connection name.
5. Click Browse next to Directory Path to locate and select the deploy folder that was created when you deployed the declarative component definition project.
6. Click Test Connection to test the connection. When you see the message Success!, click OK.
7. In the Resource Palette, expand File System | DeclarativeComponents to show the deployed ADF Library JAR file, adflibDeclarativeComponents1.jar.
8. In the Application Navigator, select MyWebApp from the dropdown list to switch to the application that will consume the declarative component. In the application, select the ViewController project that will contain your JSF pages.
9. In the Resource Palette, right-click adflibDeclarativeComponents1.jar and choose Add to Project . In the Confirm Add ADF Library dialog, click Add Library.
   

   Projects with the Added ADF Library JAR

   When you add the ADF Library JAR to a consuming project, JDeveloper adds the tag library that contains the declarative component to the project's list of JSP tag libraries.   [ tell me more...]

   
   
   
   

   In the IDE

   When you finish creating a File System connection for the ADF Library JAR, the Resource Palette should look something like this:  [ tell me more...]

   
   
   

Create a Page and Add the Declarative Component

1. In the ViewController project in the Application Navigator, double-click adfc-config.xml to open the default page flow diagram.
   

   adfc-config.xml

   The adfc-config.xml file is the default page flow diagram JDeveloper provided when you created an application based on the Fusion Web Application template. adfc-config.xml is the default file name for an unbounded task flow. On this diagram, you can define the activities and control flow rules that interact to allow a user to complete a task. In the example, you will define one view activity on the diagram to represent the page you will create.   [ tell me more...]

   
   
   
2. In the Component Palette, ADF Task Flow page, Components panel, click View and then click on the diagram to add a page icon to the diagram. Change the default page name to myPage.
3. On the page flow diagram, double-click the page icon to open the Create JSF Page dialog.
4. Under Initial Page Layout and Content, confirm that Blan k Page is selected. Make sure Page Implementation shows UI Components are not exposed in managed bean. Then click OK.
5. In the Component Palette, ADF Faces page, Layout panel, drag Panel Group Layout and drop it on the blank page in the visual editor.
6. In the Property Inspector, Common section, change the Layout property value to scroll.
7. In the Component Palette, select MyDeclComponents (the tag library you created previously) from the dropdown list. Drag and drop the declarative component MyMenubar into the panel group layout component on the page.
   

   Declarative Components on a Page

   Adding declarative components on a page is the same as adding any other ADF Faces components. You select a declarative component from the Component Palette and drop it on the desired location on the page.  [ tell me more...]

   
   
   
8. Click Save All to save your work.
   

   In the IDE

   When you complete the steps for creating a page and adding the declarative component, the visual editor should look something like this:  [ tell me more...]

   
   
   

Modify the Declarative Component on the Page

1. In the Structure window, select the declarative component mc:myMenubar.
2. In the Property Inspector, Other section, enter Hello as the MenuLabel property.
3. From the dropdown menu next to the Method1 field, choose Edit. In the Edit Property dialog, click New next to the Managed Bean dropdown list to open the Create Managed Bean dialog.
   

   JSF Managed Beans

   While JSF allows you to bind a component in the user interface directly to any JavaBean, the best choice is to use JSF managed beans.   [ tell me more...]

   
   
   
4. Enter myBean in the Bea n Name field, and MyBean in the Class Name field. Accept java.lang.Object in the Extends field, and request as the Scope value. Make sure the Generate Class If It Does Not Exist box is selected. Click OK.
5. In the Edit Property dialog, click N ew next to the Me thod dropdown list to open the Create Method dialog. Enter myMethod in the Method Name field. Click OK.
6. Click OK to close the Edit Property dialog. You should see the expression #{myBean.myMethod} in the Method1 field in the Property Inspector.
7. In the editor window, click the MyBean.java document tab at the top to bring the source editor forward. Add code to the method automatically generated by JDeveloper.
   Use sample code
8. In the editor window, click the myPage.jspx document tab to bring the visual editor forward. (If necessary, click the Design tab at the bottom of the editor window to switch to the visual editor. )
9. In the Structure window, right-click the declarative component mc:myMenubar and choose Facets - My Menubar More Menus .
10. In the Component Palette, ADF Faces page, Common Components panel, drag and drop Menu into the moreMenus facet in the Structure window.
    

    Restriction on Using Groups

    Typically, you can put separators between menus by grouping menu components within af:group. For example:  [ tell me more...]

    
    
    
11. In the Property Inspector, Common section, enter Edit as the Text property and press Enter.
12. In the Component Palette, ADF Faces page, Common Components panel, drag and drop Menu Item into the menu component you just added. In the Property Inspector, Common section, enter Cut as the Text property.
13. Drag and drop another Menu Item into the af:menu - Edit element in the Structure window. In the Property Inspector, Common section, enter Copy as the Text property value for the menu item and press Enter.
14. In the editor window, click the adfc-config.xml document tab to bring the page flow diagram forward. On the diagram, right-click the myPage page icon and choose R un . (If the Set Run Configuration dialog displays, click OK.)
    

    Running an ADF Application

    By default, JDeveloper automatically configures an integrated server named Integrated WebLogic Server that references a user-specific instance of Oracle WebLogic Server bundled with the IDE. Integrated WebLogic Server is a Java EE runtime service for packaged archive deployment. Based on zero-copy deployment, Integrated WebLogic Server lets you run and test an application and its projects as a Java EE application in a Java EE container. No special connection setup is required to use Integrated WebLogic Server. You can run the entire application, a project, or individual JSF pages.  [ tell me more...]

    
    
    
    

    In the IDE

    When you complete the steps for modifying the declarative component on the page, the visual editor should look something like this:  [ tell me more...]

    
    
    

Copyright © 1997, 2009, Oracle. All rights reserved.