Developing a Custom Component with JDeveloper

Creating Custom ADF Faces Components 30-7 orderBy=alpha partialTriggers=tagCountLabel Because the tagPane component must be used with other ADF Faces components, it must use the same skins. Therefore, any styling is achieved through the use of cascading style sheets CSS and corresponding skin selectors. For example, the tagPane component needs skin selectors to specify the root element, and to define the style for the container of the links and the way the hyperlinks are displayed. Example 30–2 shows a sample set of style selectors in the CSS file for the tagPane component. Example 30–2 CSS Style Selectors for the Sample Custom Component acme|tagPane - root element acme|tagPane::content - container for the links acme|tagPane::tag - tag hyperlink You may need to specify the HTML code required for the custom component on the server side. Example 30–3 shows HTML server-side code used for the tagPane component. Example 30–3 HTML Code for the Server Side div class= acme|tagPane span class= acme|tagPane::content a class= acme|tagPane::tag href= style=font-size:9px;Tag1a a class= acme|tagPane::tag href= style=font-size:10px;Tag2a span div On the client side, the component requires a JavaScript component counterpart and a component peer that defines client-side behavior. All DOM interaction goes through the peer for more information, see Chapter 3, Using ADF Faces Architecture . The component peer listens for the user clicking over the hyperlinks that surround the tag names. When the links are clicked, the peer raises a custom event on the client side, which propagates the event to the server side for further processing. Table 30–2 lists the client-side and server-side artifacts for the tagPane component. Referencing the naming conventions in Table 30–1 , the component_package is com.adfdemo.acme and the prefix is Acme. 30-8 Web User Interface Developers Guide for Oracle Application Development Framework Table 30–2 Client-Side and Server-Side Artifacts for the tagPane Custom Component Client Server Component : com.adfdemo.acme.js.component. AcmeTagPane.js Extends : oracle.adf.view.js.component. AdfUIObject.js Component com.adfdemo.acme.faces.component.TagPane. java Extends : org.apache.myfaces.trinidad.component. UIXObject.java Event : com.adfdemo.acme.js.event. AcmeTagSelectEvent.js Extends : oracle.adf.view.js.component. AdfComponentEvent.js Event : com.adfdemo.acme.faces.event. TagSelectEvent.java Extends : javax.faces.event.FacesEvent.java Event Listener : com.adfdemo.acme.faces.event. SelectListener Extends : com.faces.event.FacesListener Component Peer : com.adfdemo.acme.js.component. AcmeTagPanePeer.js Extends : oracle.adf.view.js.laf.rich. AdfRichUIPeer.js Component Renderer : com.adfdemo.acme.faces.render. TagPaneRenderer.java Extends : oracle.adf.view.rich.render.RichRenderer. java Component JSP Tag : oracle.adfdemo.acme.faces.taglib. TagPaneTag.java Extends : javax.faces.webapp.UIComponentELTag.java Creating Custom ADF Faces Components 30-9

30.2 Setting Up the Workspace and Starter Files

Use JDeveloper to set up an application and a project to develop the custom component. After your skeleton project is created, you can add a deployment profile for packaging the component into a JAR file. During the early stages of development, you create starter configuration and support files to enable development. You may add to and edit these files during the process. You create the following configuration files: ■ META-INFfaces-config.xml: The configuration file required for any JSF-based application. While the component will use the faces-config.xml file in the application into which it is eventually imported, you will need this configuration file for development purposes. ■ META-INFtrinidad-skins.xml: The configuration information for the skins that the component can use. Extend the simple skin provided by ADF Faces to include the new component. ■ META-INFpackage_directorystylesskinName.css: The style metadata needed to skin the component. ■ META-INFservletsresourcesname.resources: The render kit resource loader that loads style sheets and images from the component JAR file. The resource loader is aggregated by a resource servlet in the web application, and is used to configure the resource servlet. In order for the servlet to locate the resource loader file, it must be placed in the META-INFservletsresources directory. ■ META-INFadf-js-features.xml: The configuration file used to define a feature. The definition usually includes a component name or description of functionality that a component provides, and the files used to implement the client-side component. Composite Resource Loader : oracle.adfdemo.acme.faces.resource. AcmeResourceLoader.java Extends : org.myfaces.trinidad.resource. RegxResourceLoader.java JavaScript Resource Loader : oracle.adfdemo.acme.faces.resource. ScriptsResourceLoader.java Extends : org.myfaces.trinidad.resource. AggregateingResourceLoader.java Resource Bundle : oracle.adfdemo.acme.faces.resource. AcmeSimpleDesktopBundle.java Extends : java.util.ListResouceBundle.java Table 30–2 Cont. Client-Side and Server-Side Artifacts for the tagPane Custom Component Client Server 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.