12 Applying the Finished ADF Skin to Your Web Application

This chapter describes how to complete tasks that you need to do once you finish your ADF skin. Information is provided on how to test your ADF skin, package the completed ADF skin in an ADF Library JAR, and configure a web application so that it uses the completed ADF skin.

This chapter includes the following sections:

12.1 About Applying a Finalized ADF Skin to an Application

After you create an ADF skin where you define style properties for one or more ADF skin selectors, you may want to test the changes that you make in the ADF skin. Once you complete testing the changes in your ADF skin and are satisfied with the final ADF skin, you can package the ADF skin and associated files (resource bundle, images, and configuration files) into an ADF Library JAR to distribute for inclusion to the application projects that use the final ADF skin. Once you have distributed the final ADF skin, you configure the application to apply the ADF skin to it.

12.2 Testing Changes in Your ADF Skin

Once you have created an ADF skin and defined style properties that you want for one or more selectors, you may want to test how these style properties render at runtime in a browser. To do this, you apply the ADF skin to your application and run a page that renders the ADF Faces component which exposed the selector.

Consider using tools, such as Firebug for the Mozilla Firefox browser (or similar for your particular browser), when you run your application. These tools provide useful information that can help you as you iteratively develop your ADF skin. For example, in addition to inspecting changes that you have already made, these tools can help you identify the ADF skin selectors that correspond to a particular DOM element.

You can also configure context initialization parameters in the web.xml file of your application that allow you to:

View changes in an ADF skin without having to restart the application

Set the value of the following context initialization parameter to true:

org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION
Display the full uncompressed CSS style class name at runtime

Set the value of the following context initialization parameter to true:

org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION

Note that not all changes that you make to an ADF skin in your web application appear immediately if you set the CHECK_FILE_MODIFICATION to true. You must restart the web application to view changes that you make to icon and ADF skin properties.

For more information about context initialization parameters, see the "ADF Faces Configuration" appendix in Developing Web User Interfaces with Oracle ADF Faces.

Figure 12-1 demonstrates how the name of a component selector (for the ADF Faces button component) is suppressed. In Figure 12-1, the style class (fndGlobalSearchCategory) that is defined in an ADF skin is applied to the button component using the component's styleClass attribute.

Figure 12-1 Compressed CSS from an ADF Skin

This image is described in the surrounding text

Figure 12-2 shows how the browser renders the full uncompressed name of the ADF Faces component when you set the DISABLE_CONTENT_COMPRESSION parameter to true. In Figure 12-2, the uncompressed style class af_button corresponds to the af|button selector documented in the Tag Reference for Oracle ADF Faces Skin Selectors.

The uncompressed style classes that correspond to the pseudo-elements that an ADF skin selector exposes can also be identified. For example, the tab-end pseudo-element exposed by the af|panelTabbed selector (af|panelTabbed::tab-end) translates to the uncompressed af_panelTabbed_tab-end style class at runtime.

Similarly, changes that you make to the appearance of a component when it is in a specific state can also be identified or inspected using browser tools. For example, the following entry in the source file of an ADF skin allows you to define the style for the ADF Faces panelTabbed component when a user selects the right-hand side of the component:

af|panelTabbed::tab:selected af|panelTabbed::tab-end

At runtime, the uncompressed style class name translates to the following:

.af_panelTabbed_tab.p_AFSelected .af_panelTabbed_tab-end

Note that :selected translates to p_AFSelected although sometimes the generated CSS does not have a p_AFSelected equivalent because some browsers have built-in support for that particular state, as is the case for other pseudo-classes like :hover.

It is recommended that you only customize the ADF skin selectors, pseudo-elements, and pseudo-classes documented in the Tag Reference for Oracle ADF Faces Skin Selectors and the Tag Reference for Oracle ADF Data Visualization Tools Skin Selectors. Customizing other ADF skin selectors may result in unexpected or inconsistent behavior for your application.

Figure 12-2 Uncompressed CSS from an ADF Skin

12.2.1 How to Set Parameters for Testing Your ADF Skin

You set the CHECK_FILE_MODIFICATION and DISABLE_CONTENT_COMPRESSION context initialization parameters to true in the web.xml file of your application.

To set parameters for testing your ADF skin:

In the Applications window, double-click the web.xml file.
In the source editor, add the following context initialization parameter entries and set to true:
- org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION
- org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION
Save and close the web.xml file.

12.2.2 What Happens When You Set Parameters for Testing Your ADF Skin

Entries appear in the web.xml file for your application, as illustrated in the following example.

<context-param>
  <param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION</param-name>
  <param-value>true</param-value>
</context-param>
<context-param>
  <param-name>org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION</param-name>
  <param-value>true</param-value>
</context-param>

Changes that you make to a selector for an ADF Faces component (other than changes to icon and skin properties) render immediately when you refresh a web application's page that renders the ADF Faces component. Using Firebug if your browser is Mozilla Firefox or Google Chrome's developer tools, you can see the uncompressed style class names that render at runtime and establish what ADF skin selector it corresponds to. Remember that setting org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION to true incurs a performance cost for your web application so set it to false when you finish testing your changes.

12.3 Packaging an ADF Skin into an ADF Library JAR

You can deploy an ADF skin and associated files (for example, image files, configuration files, and resource bundles) in an ADF Library JAR. This enables you to package files required to apply an ADF skin to an application. The benefits of packaging ADF skins into an ADF Library JAR as compared to bundling them into the application are the following:

An ADF skin can be deployed and developed separately from the application. This also helps to reduce the number of files to be checked in case some changes must be applied to the ADF skin.
The source files for an ADF skin and images can be separated into their own ADF Library JARs. Therefore, you can partition the image base into separate ADF Library JARs, so that not all files have to be deployed with all applications.
An ADF skin in an ADF Library JAR can be applied to an application that is running without requiring a restart, as described in Applying an ADF Skin to a Running Web Application .

12.3.1 How to Package an ADF Skin into an ADF Library JAR

Create an ADF Library JAR file deployment profile to package the ADF skin into an ADF Library JAR.

To create an ADF Library JAR file deployment profile:

In the Applications window, right-click the project that contains the ADF skins and choose Deploy > New Deployment Profile.
In the Create Deployment Profile dialog, choose ADF Library JAR File in the Profile Type dropdown list.
Enter a name for the deployment profile in the Deployment Profile Name input field and click OK.
Review the options in the Edit ADF Library JAR Deployment Profile Properties dialog that appears. For more information at any time, click Help.
Click OK.

To package an ADF skin into an ADF Library JAR:

In the Applications window, right-click the project that contains the ADF skin and choose Deploy > deployment, where deployment is the name of the ADF Library JAR file deployment profile.
In the Deploy dialog Deployment Action page, click Deploy to ADF Library JAR file, click Next and then click Finish.

12.3.2 What Happens When You Package an ADF Skin into an ADF Library JAR

An ADF Library JAR file is written to the directory specified by the deployment profile. This ADF Library JAR contains the source file for the ADF skin, the trinidad-skins.xml file, image files, and any resource bundles that you created to define resource strings or to override the default strings defined for ADF Faces components. The ADF Library JAR file also contains other files from the ADF skin's project not related to skinning.

Example 12-1 shows the directory structure for a project that contains the following items for an ADF skin:

The trinidad-skins.xml file
An image file (sort_des_ena.png) copied into the JDeveloper project
The source file for an ADF skin (skin1.css)
An .sva file (oracle.adf.common.services.ResourceService.sva) that is used to inspect the content of the ADF Library JAR when you import it into a project, as described in Adding ADF Skins from an ADF Library JAR.
A resource bundle (skinBundle.properties) that contains string values to override strings from the default resource bundle

For information about how to specify resource bundles that contain string values you define, see How to Specify an Additional Resource Bundle for an ADF Skin.

The directory paths for images in the ADF skin that appear in the ADF Library JAR are modified to include the directory path from the JDeveloper project. Example 12-2 demonstrates an example of the changes that occur:

Example 12-1 Directory Structure for an ADF Library JAR Containing an ADF Skin

ADFLibraryJARRootDirectory
+---META-INF
|   |   MANIFEST.MF
|   |   oracle.adf.common.services.ResourceService.sva
|   |   trinidad-skins.xml
|   |
|   +---adf
|   |   \---skins
|   |       \---skin1
|   |           \---images
|   |               \---af_column
|   |                       colSort_des_ena.png
|   |
|   \---skins
|       \---skin1
|               skin1.css
|
\---resources
        skinBundle.properties

Example 12-2 Modified Directory Path for Images in a Deployed ADF Skin

// Reference to an image in an ADF skin prior to deployment to an ADF Library JAR
af|column::sorted-descending-icon-style
{
  background-image: url("images/af_column/colSort_des_ena.png"); 
}

// Reference to an image in an ADF skin after deployment to an ADF Library JAR
af|column::sorted-descending-icon-style
{
  background-image: url("/adf/skins/skin1/images/af_column/colSort_des_ena.png"); 
}

12.4 Applying an ADF Skin to Your Web Application

You configure an application to use an ADF skin by specifying values in the application's trinidad-config.xml file. You specify a value for the <skin-family> element that identifies the ADF skin family the application uses at runtime. If you created more than one ADF skin in the ADF skin family, you can version these ADF skins. If you versioned multiple ADF skins in the same ADF skin family, use the <skin-version> element in the trinidad-config.xml file to identify the specific version that you want the application to use.

If you do not identify a specific ADF skin from an ADF skin family by entering a value for the <skin-version> element in the trinidad-config.xml file or using the <default>true</default> element in the trinidad-skins.xml file, the application uses the last skin defined in the trinidad-skins.xml file. For more information about versioning ADF skins and how this can determine the ADF skin that your application chooses, see Versioning ADF Skins.

Note that you can configure an application page for your end users to dynamically select the ADF skin that they want the application to use. For more information, see Developing Web User Interfaces with Oracle ADF Faces.

12.4.1 How to Apply an ADF Skin to an Application

You apply an ADF skin to an application by modifying the application's trinidad-config.xml file. You do this by editing the application's trinidad-config.xml file to specify the ADF skin family to use. Alternatively, you can select the ADF skin family from a list in the ADF View options of JDeveloper's Project Properties dialog.

To apply an ADF skin to an application:

In the Applications window, double-click the trinidad-config.xml file. By default, this file is in the Web Content/WEB-INF node.
In the source editor, write entries to specify the value of the <skin-family> element and, optionally, the <skin-version> element as shown in Example 12-3.

12.4.2 What Happens When You Apply an ADF Skin to an Application

The values that you specify for the <skin-family> element and, optionally, the <skin-version> element in the trinidad-config.xml file determine the ADF skin that the web application uses at runtime, as shown in Example 12-3.

Example 12-3 trinidad-config.xml File

<?xml version="1.0" encoding="windows-1252"?>
<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
    <skin-family>skyros</skin-family>
      <skin-version>v1</skin-version>
</trinidad-config>

12.5 Applying an ADF Skin to a Running Web Application

Using Java Management Extensions (JMX), you can apply an ADF skin that is packaged in an ADF Library JAR to a web application without having to restart the application. To do this, you must configure the web application's source files, as described in How to Configure your Web Application to Accept an Updated ADF Skin. You then use JDeveloper to connect to the MBean server and deploy the ADF Library JAR containing the ADF skin(s). For more information, see How to Deploy an ADF Library JAR to an MBean Server. This makes all ADF skins contained in the ADF Library JAR available to the web application.

12.5.1 How to Configure your Web Application to Accept an Updated ADF Skin

You make the following changes to the web application's ViewController project in JDeveloper so that the application can apply a new ADF skin deployed by a MBean server without requiring a restart of the web application:

Select the Enable Runtime Skin Updates checkbox in the ADF View page of the application's ViewController project
Add ADF Faces JMX Runtime 11 to the application's classpath
(Optional) Add a context initialization parameter to the application's web.xml file

The context initialization parameter enables you to specify a user friendly name to identify the web application rather than use the application's context root.

Note:

The web application must be deployed in an exploded format, as is the case when you run the application in the Integrated WebLogic Server.

To configure your web application to accept an updated ADF skin:

In JDeveloper's Applications window, select the ViewController project.
From the main menu, choose Application > Project Properties.
In the Project Properties dialog, select the ADF View page and then select the Enable Runtime Skin Updates checkbox.
Select the Libraries and Classpath page and verify that ADF Faces JMX Runtime 11 appears in the Classpath Entries list. If it is not, click Add Library.
In the Add Library dialog, select ADF Faces JMX Runtime 11 and click OK.
Click OK.
Optionally, in the Applications window, double-click the web.xml file located in the WEB-INF directory and add a context initialization parameter where you can specify an easy to remember name for your application. Otherwise, the default behavior is to use the context root of the application.
In the overview editor, click the Application navigation tab and then click the Add icon next to the Context Initialization Parameters table to add an entry for the oracle.adf.view.rich.SKINNING_MBEAN_NAME parameter and set its value to a name that you will use to identify the web application to the MBean server.

12.5.2 How to Deploy an ADF Library JAR to an MBean Server

You deploy the ADF Library JAR that packages the ADF skin(s) to the MBean server. For information about how to create an ADF Library JAR file deployment profile to package the ADF skin(s), see How to Package an ADF Skin into an ADF Library JAR.

To deploy an ADF Library JAR to an MBean Server:

In the Applications window, right-click the project that contains the ADF skin(s) and choose Deploy > deployment, where deployment is the name of the ADF Library JAR file deployment profile.
In the Deployment Action page, select Deploy to ADF Skin Managed Bean and then click Next.
In the Skin Connection page, choose the appropriate option:
- Click Add to create a new connection to the MBean server and go to Step 4.
- Choose an existing connection from the Connection dropdown list and go to Step 5.
In the Create JMX Connection dialog, complete the fields to connect to the MBean server:
- Connection Name: Enter a name for the connection. The connection name must be a valid Java identifier, and as the name and connection are global across your installation, choose an appropriate and unique name.
- Server Type: The default of Weblogic Server is preselected for connections where you deploy to an ADF Skin Managed Bean.
- Username: Enter the user name to be authorized for access to the MBean server.
- Password: Enter the password to be associated with the specified user name. An asterisk (*) appears for each character you type in this field.
- Protocol: JDeveloper uses the t3 protocol to communicate with the MBean server.
- Hostname: Enter a value to identify the machine running the MBean server. Use an IP address or a host name that can be resolved by TCP/IP, for example if the MBean server is on the local machine, use localhost, or 127.0.0.1.
- Port: Enter the listen port for the MBean server. The default is whatever the default port number of the Integrated Weblogic Server is (often 7101).
- URL Provider Path: Enter the absolute JNDI name of the MBean server. It must start with /jndi/ and be followed by one of:
  - weblogic.management.mbeanservers.domainruntime
  - weblogic.management.mbeanservers.runtime
  - weblogic.management.mbeanservers.edit
- Server Install Location: Displays the server install location.
- Test Connection: Click to test the connection.
- Status: A Success! message indicates that JDeveloper has been able to connect to the MBean server. Any other message indicates that the connection has failed. Amongst the things you should check before trying Test Connection again are:
  - Whether the network is working correctly when the MBean server is not local.
  - The values entered in this dialog.
In the Application Name field, select the name of the web application that you want to deploy the ADF Library JAR containing the ADF skin(s) to. Click Find Running Applications to retrieve the list of available applications and to make sure that the application is running.

The name of the application's root context appears unless you specified the name of the application to be the value that you entered for the oracle.adf.view.rich.SKINNING_MBEAN_NAME parameter, as described in How to Configure your Web Application to Accept an Updated ADF Skin.
Click Next and then click Finish.

12.5.3 What Happens When You Apply an ADF Skin to a Running Application

JDeveloper deploys the ADF Library JAR containing the ADF skin(s) to the web application. This ADF Library JAR contains the ADF skin and other associated files (for example, any images that the ADF skin requires). For more information about the contents of the ADF Library JAR, see What Happens When You Package an ADF Skin into an ADF Library JAR. The ADF skins are installed in the root directory of the web application. The trinidad-skins.xml file of the web application is updated to reference the newly-added ADF skins.

To make the web application use the newly-available ADF skin, you need to update the value that the trinidad-config.xml file's <skin-family> element references. You can do this manually, as described in How to Apply an ADF Skin to an Application, or you can specify an EL expression for the element that updates the value programmatically. For more information about this latter option, see the "Customizing the Appearance Using Styles and Skins" chapter in Developing Web User Interfaces with Oracle ADF Faces.