An Example Custom Component

30-10 Web User Interface Developers Guide for Oracle Application Development Framework ■ META-INFprefix_name.tld for JSP: The tag definition library for the component. If the consuming web application is using JSP, the custom component requires a defined TLD. The TLD file will be located in the META-INF folder along with the faces-config.xml and trinidad-skins.xml files. ■ META-INFprefix_name.taglib.xml for Facelets: The tag library definition for the component when the consuming application uses Facelets. This file defines the handler for the component. For example, for the tagPane component, the following configuration files are needed: ■ META-INFfaces-config.xml ■ META-INFtrinidad-skins.xml ■ META-INFacmestylesacme-simple-desktop.css ■ META-INFservletsresourcesacme.resources ■ META-INFacme.tld ■ META-INFacme.taglib.xml ■ META-INFadf-js-features.xml After the files are set up in JDeveloper, you add content to them. Then, you create the client-side files nd server-side files. For more information, see Section 30.3, Client-Side Development, and Section 30.4, Server-Side Development.

30.2.1 How to Set Up the JDeveloper Custom Component Environment

This chapter assumes you have experience using JDeveloper and are familiar with the steps involved in creating and deploying an application. For more information about using JDeveloper to create applications, see Chapter 2, Getting Started with ADF Faces. For more information about deployment, see the Deploying Fusion Web Applications chapter of the Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework. To set up the custom component development environment in JDeveloper: 1. Create an application to serve as a development container for the component. Use JDeveloper to create a workspace and project. For procedures on creating an application, see Section 2.2, Creating an Application Workspace. When selecting an application template, select the Generic Application template.

2. Prepare the project to be deployed as a JAR file by creating a new deployment

profile.

a. In the Application Navigator, right-click the project and choose New.

b. In the New Gallery, select Deployment Profile and then ADF Library JAR

File , and click OK. Note: Do not select any other application template, or add any technologies to your application. Because the custom component will be packaged into a JAR file, you do not need to create unnecessary folders such as public_html that JDeveloper creates by default when you use a template specifically for web applications, or add web technologies. Instead, create the starter configuration file from the XML schemas. Creating Custom ADF Faces Components 30-11 c. In the Create Deployment Profile dialog, enter a name for the Deployment Profile name. For example, the tagPane component might use adf-richclient-demo-acme.

d. In the Edit JAR Deployment Profile Properties dialog, click OK.

3. In the Project Properties dialog, add library dependencies.

a. Select Libraries and Classpath in the left pane.

b. Click Add Library.

c. In the Add Library dialog, select ADF Faces Runtime 11, Facelets Runtime if

using Facelets, JSF 1.2, and JSP Runtime, and click OK. d. Click OK to close the Project Properties dialog. 4. Register XML schemas. The custom component requires several XML configuration files. You can use JDeveloper to register the XML schemas associated with these configuration files. You must add schemas for three configuration files: faces-config.xml, trinidad-skins.xml, and trinidad-config.xml. By preregistering these schemas, you can create a template XML configuration file without having to know the specifics about the markup structure. The names and locations of the schemas are assumed by the base installation of JDeveloper.

a. Select Tools Preferences. In the Preferences dialog, select XML Schemas in

the left pane, and click Add. b. In the Add Schema dialog, click Browse to navigate to the XML schemas included in your JDeveloper build, as shown in Table 30–3 . Note: In the Add Schema dialog, make sure Extension is set to .xml. If you change it to XSD, when you later create XML files, you will not be able to use the XML schema you have created. Table 30–3 XML Schema Locations XML Configuration File Schema Location META-INFfaces-config.xml JDeveloper_Homejdevelopermodules oracle.jsf_1.2.9glassfish.jsf_1.2.9jar comsunfacesweb-facesconfig_1_2.xsd META-INFtrinidad-skins.x ml JDeveloper_ Home jdevelopermodulesoralce.adf.view_ 11.1.1trinidad-impl.jarorgapache myfacestrinidadinternaluilafxmlschemas skintrinidad-skins.xsd META-INFtrinidad-config. xml JDeveloper_Home jdevelopermodules oracle.adf.view_11.1.1 trinidad-api.jartrinidad-config.xsd META-INFadf-js-features. xml JDeveloper_Homejdevelopermodules oracle.adf.view_11.1.1 adf-richclient-api-ll.jar adf-js-features.xsd 30-12 Web User Interface Developers Guide for Oracle Application Development Framework

30.2.2 How to Add a Faces Configuration File

Although the custom component will be registered in the consuming application’s faces-config.xml file, during development, the workspace requires a faces-config.xml file. To create a faces-config.xml file for the custom component: 1. In the Application Navigator, right-click the project and select New. 2. In the New Gallery, expand General, select XML, and then Select XML Document from XML Schema , and click OK. 3. In the Create XML from XML Schema dialog: ■ XML File : Enter faces-config.xml. ■ Directory : Append \src\META-INF to the end of the directory entry. ■ Select Use Registered Schemas and click Next. 4. Enter the following: ■ Target Namespace : Select http:java.sun.comxmlnsjavaee. ■ Root Element : Select faces-config. Leave the defaults for the other fields, and click Finish. The new file will automatically open in the XML editor.

5. Add the following schema information after the first line in the file:

?xml version=1.0 encoding=US-ASCII? faces-config version=1.2 xmlns=http:java.sun.comxmlnsjavaee Adding a schema provides better WYSIWYG tool support.

30.2.3 How to Add a MyFaces Trinidad Skins Configuration File

Add a MyFaces Trinidad skins file to register the component’s CSS file, which is used to define the component’s styles. To create a trinidad-skins.xml file for the custom component: 1. In the Application Navigator, right-click the project and select New. 2. In the New Gallery, expand General and select XML. 3. Select XML Document from XML Schema and click OK. 4. In the Create XML from XML Schema dialog: ■ XML File : Enter trinidad-skins.xml. ■ Directory : Append \src\META-INF to the end of the Directory entry. ■ Select Use Registered Schemas, and click Next. 5. Enter the following: Note: Do not use any of JDeveloper’s declarative wizards or dialogs to create the faces-config.xml file. These declarative methods assume you are creating a web application, and will add uneccessary artifacts to your custom component application. Creating Custom ADF Faces Components 30-13 ■ Target Namespace : Select http:myfaces.apache.orgtrinidadskin. ■ Root Element : Select skins. ■ Click Finish. The new file will automatically open in the XML editor.

30.2.4 How to Add a Cascading Style Sheet

Add a cascading style sheet to define component’s style. To create a cascading style sheet for the custom component: 1. In the Application Navigator, right-click the project and select New. 2. In the New Gallery, expand General, select File and click OK. 3. In the Create File dialog: ■ Enter a file name, for example, acme-simple-desktop.css. ■ Append \src\META-INF\component_prefix\styles to the end of the Directory entry, where component_prefix is the prefix that will be used in the component library. For example, for the tagPane component, acme is the prefix, therefore, the string to append would be \META-INF\acme\styles.

30.2.5 How to Add a Resource Kit Loader

Create an empty file and add the fully qualified classpath to the custom resource loader. To create a resource loader for the custom component: 1. In the Application Navigator, right-click the project and select New. 2. In the New Gallery, expand General and then File, and click OK. 3. In the Create File dialog: ■ Enter component_prefix.resources for File Name, where component_ prefix will be the prefix used in the component library. For example, for the tagPane component, acme is the prefix, therefore, the string to enter is acme.resources. ■ Append \src\META-INF\sevlets\resources\ to the end of the Directory entry.

30.2.6 How to Add a JavaServer Pages Tag Library Descriptor File

You need a JSP TLD file to work with JSF pages. To create a JavaServer Pages TLD file for the custom component: 1. In the Application Navigator, right-click the project and select New. 2. In the New Gallery, expand Web Tier and select JSP. 3. Select JSP Tag Library and click OK. 4. In the Create JavaServer Page Tag Library dialog, select Deployable and click Next . 5. Enter the following: ■ Tag Library Descriptor Version: Select 2.1. 30-14 Web User Interface Developers Guide for Oracle Application Development Framework ■ Short Name : A name. For example, for the tagPane component, you would enter acme. ■ Tag Library URI : A URI for the tag library. For example, for the tagPane component, you would enter http:oracle.adfdemo.acme.

6. Click Next and optionally enter additional tag library information, then click

Finish .

30.2.7 How to Add a JavaScript Library Feature Configuration File

Add a features file to define the JavaScript files associated with the custom component, including the files for the client component, the client peer, and the client events. To create an adf-js-features.xml file for the custom component: 1. In the Application Navigator, right-click the project and select New. 2. In the New Gallery, expand General and select XML. 3. In the right pane, select XML Document from XML Schema and click OK. 4. In the Create XML from XML Schema dialog: ■ XML File : Enter adf-js-features.xml. ■ Directory : Append \src\META-INF to the end of the Directory entry. ■ Select Use Registered Schemas, and click Next. 5. Do the following: ■ Target Namespace : Select http:xmlns.oracle.comadffacesfeature. ■ Root Element : Select features. ■ Click Finish. The new file will automatically open in the XML editor.

30.2.8 How to Add a Facelets Tag Library Configuration File

If a consuming application uses Facelets, then you must define the handler for the component. To create a Facelets tag library file: 1. In the Application Navigator, right-click the project and select New. 2. In the New Gallery, expand General and select XML. 3. In the right pane, select XML Document and click OK. 4. In the Create XML file dialog, enter the following: ■ File Name : Enter prefix_name.taglib.xml ■ Directory : Append \src\META-INF to the end of the Directory entry. 5. Copy and paste the code shown in Example 30–4 : Example 30–4 Code for Facelets Tag Library Configuration File ?xml version=1.0 encoding=utf-8? DOCTYPE facelet-taglib PUBLIC -Sun Microsystems, Inc.DTD Facelet Taglib 1.0EN