4 Creating the Source Files for an ADF Skin

This chapter describes how to create the source files for an ADF skin in the ADF Skin Editor and in JDeveloper.

This chapter includes the following sections:

4.1 About Creating an ADF Skin

An ADF skin defines the properties for the selectors that ADF Faces and ADF Data Visualization components expose. Using the visual editor in JDeveloper or the ADF Skin Editor, you can create a source file for an ADF skin. As a source file for an ADF skin is a type of CSS file, you could create it without using an editor. However, when you use the editor, associated configuration files get created (the first time that you create an ADF skin) or modified (when you create subsequent ADF skins). For more information about these configuration files, see Section 11.3, "Configuration Files for an ADF Skin."

4.2 Creating ADF Skin Applications and ADF Skin Projects

New ADF skin applications and ADF skin projects can be created in the ADF Skin Editor.

4.2.1 How to Create an ADF Skin Application

This section describes how to create an ADF skin application and a project within it in the ADF Skin Editor.

To create a new ADF skin application:

  1. Open the Create ADF Skin Application dialog by choosing File > New > ADF Skin Application.

  2. In the Create ADF Skin Application dialog, enter application details like the name and directory. For help with the wizard, press F1.

  3. Click Next to open the ADF Skin Project page where you specify the name of your ADF skin project and the directory to store it.

  4. In the Target Application Release list, select the release of Oracle ADF that the application you want to skin uses.

    The ADF Skin Editor configures your ADF skin project appropriately for the release you specify. For example, the ADF Skin Editor filters the list of ADF skins that you can extend from, as described in Section 4.4.1, "How to Create an ADF Skin in the ADF Skin Editor." The ADF Skin Editor also filters the list of skin selectors to display only those that the release you target supports. It will not display a skin selector introduced in a later release if you target your ADF skin project at an earlier release.

  5. When you are done, click Finish.

4.2.2 How to Create a New ADF Skin Project

You use the Application Navigator to keep track of the ADF skin projects (collections of source files for ADF skins, images, and related files) you use while developing your ADF skin application.

You can create a new empty ADF skin project in an ADF skin application.

All ADF skin projects inherit the settings specified in the Default Project Properties dialog. As soon as you create the ADF skin project, it is added to the active ADF skin application.

To create a new ADF skin project:

  1. In the Application Navigator, select the ADF skin application within which the project will appear.

  2. Open the Create ADF Skin Project dialog by choosing File > New > ADF Skin Project.

  3. In the Create ADF Skin Project dialog, enter project details like the name and directory.

  4. In the Target Application Release list, select the release of Oracle ADF that the application you want to skin uses.

    The ADF Skin Editor configures your ADF skin project appropriately for the release you specify. For example, the ADF Skin Editor filters the list of ADF skins that you can extend from, as described in Section 4.4.1, "How to Create an ADF Skin in the ADF Skin Editor." The ADF Skin Editor also filters the list of skin selectors to display only those that the release you target supports. It will not display a skin selector introduced in a later release if you target your ADF skin project at an earlier release.

  5. When you are done, click Finish.

The new ADF skin project appears in the Application Navigator. It inherits whatever default properties you've already set. To alter project properties for this project, either double-click the filename or right-click and choose Project Properties.

4.3 Opening an Application Created Outside of the ADF Skin Editor

When you open an application or project that was created in a prior release of JDeveloper, the ADF Skin Editor will prompt you to migrate the project to JDeveloper 11g format. Depending on the content of the project, the ADF Skin Editor may display additional prompts to migrate some specific source files as well. Oracle recommends that you make a backup copy of your projects before you open them in the ADF Skin Editor or migrate them using the ADF Skin Editor.

4.4 Creating an ADF Skin File

You can create an ADF skin file in the ADF Skin Editor or in JDeveloper that defines how ADF Faces and ADF Data Visualization components render at runtime. The ADF skin that you create must extend either one of the ADF skins that Oracle ADF provides or from an existing ADF skin that you created. The ADF skins that Oracle ADF provides vary in the level of customization that they define for ADF Faces and ADF Data Visualization components. For information about the inheritance relationship between the ADF skins that Oracle ADF provides, see Section 1.4, "Inheritance Relationship of the ADF Skins Provided by Oracle ADF." For information about the levels of customization in the ADF skins provided by Oracle ADF and for a recommendation about the ADF skin to extend, see Section 11.4, "ADF Skins Provided by Oracle ADF."

The visual editor of the ADF Skin Editor and in JDeveloper supports the creation of ADF skins for the org.apache.myfaces.trinidad.desktop render kit.

You can create ADF skins for other render kits using the source editor in JDeveloper and in the ADF Skin Editor. For more information, see Section 11.2, "ADF Skinning Framework and Supported Render Kits."

After you create an ADF skin, you set values for the selectors that the ADF Faces and ADF Data Visualization components expose. Otherwise, the ADF skin that you create defines the same appearance as the ADF skin from which it extends. For more information, see Chapter 5, "Working with Component-Specific Selectors."

4.4.1 How to Create an ADF Skin in the ADF Skin Editor

You can create an ADF skin in the ADF Skin Editor.

To create an ADF skin in the ADF Skin Editor:

  1. In the Application Navigator, right-click the project where you want to create the new ADF skin and choose New > ADF Skin File.

  2. In the Create ADF Skin File dialog, enter the following:

    • File Name: Enter a file name for the new ADF skin.

    • Directory: Enter the path to the directory where you store the CSS source file for the ADF skin or accept the default directory proposed by the editor.

    • Family: Enter a value for the family name of your skin.

      You can define a new family or select an existing family by entering a value in the input field. A family groups together ADF skins for an application. You configure an application to use a particular family of ADF skin.

      The value you enter must be unique. You can use an EL expression to select an ADF skin for your application at runtime by referencing this value. For more information about using EL expressions to select an ADF skin for your application, see the "Enabling End Users to Change an Application's ADF Skin" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

    • Use as the default skin family for this project: Deselect this checkbox if you do not want to make the ADF skin the default for your project immediately.

    • Extends: Select the ADF skin that you want to extend. ADF Faces provides a number of ADF skins that you can extend. For more information and a recommendation on the ADF skin to extend, see Section 11.4, "ADF Skins Provided by Oracle ADF."

      Note:

      The value you select for Target Application Release, as described in Section 4.2, "Creating ADF Skin Applications and ADF Skin Projects," determines the list of ADF skins from which you can extend.
    • Skin Id: A read-only field that displays a concatenation of the value you enter in File Name and the ID of the render kit (desktop) for which you create your ADF skin. You select this value from the Extends list if you want to create another ADF skin that extends from this one.

      The ADF Skin Editor writes the value to the <id> element in the trinidad-skins.xml file.

  3. Click OK.

4.4.2 How to Create an ADF Skin in JDeveloper

You can create an ADF skin in JDeveloper.

To create an ADF skin in JDeveloper:

  1. In the Application Navigator, right-click the project that contains the code for the user interface and choose New.

  2. In the New Gallery, expand Web Tier, select JSF/Facelets and then ADF Skin, and click OK.

  3. In the Create ADF Skin File dialog, enter the following:

    • File Name: Enter a file name for the new ADF skin.

    • Directory: Enter the path to the directory where you store the CSS source file for the ADF skin or accept the default directory proposed by the editor.

    • Family: Enter a value for the family name of your skin.

      You can define a new family or select an existing family by entering a value in the input field. A family groups together ADF skins for an application. You configure an application to use a particular family of ADF skin.

      The value you enter must be unique. You can use an EL expression to select an ADF skin for your application at runtime by referencing this value. For more information about using EL expressions to select an ADF skin for your application, see the "Enabling End Users to Change an Application's ADF Skin" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

    • Use as the default skin family for this project: Deselect this checkbox if you do not want to make the ADF skin the default for your project immediately. If you select the checkbox, the trinidad-config.xml file is updated, as described in Section 4.4.3, "What Happens When You Create an ADF Skin."

    • Extends: Select the ADF skin that you want to extend. ADF Faces provides a number of ADF skins that you can extend. For more information and a recommendation on the ADF skin to extend, as described in Section 11.4, "ADF Skins Provided by Oracle ADF."

    • Skin Id: A read-only field that displays a concatenation of the value you enter in File Name and the ID of the render kit (desktop) for which you create your ADF skin. You select this value from the Extends list if you want to create another ADF skin that extends from this one.

      JDeveloper writes the value to the <id> element in the trinidad-skins.xml file.

  4. Click OK.

4.4.3 What Happens When You Create an ADF Skin

If you accepted the default value proposed for the Directory field, a file with the extension .css is generated in a subdirectory of the skins directory in your project. This file is opened in the visual editor for the ADF skin, as illustrated in Figure 4-1.

Figure 4-1 Newly-Created ADF Skin

ADF Skin File in JDeveloper

The trinidad-skins.xml file is modified to include metadata for the ADF skin that you create, as illustrated in Example 4-1.

Example 4-1 trinidad-skins.xml File

<?xml version="1.0" encoding="windows-1252"?>
<skins xmlns="http://myfaces.apache.org/trinidad/skin">
  ....
  <skin>
    <id>skin2.desktop</id>
    <family>skin2</family>
    <extends>fusionFx-v1.desktop</extends>
    <render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
    <style-sheet-name>skins/skin2/skin2.css</style-sheet-name>
  </skin>
</skins>

If you select the Use as the default skin family for this project check box in the Create New ADF Skin file dialog, the trinidad-config.xml file is modified to make the new ADF skin the default skin for your application. Example 4-2 shows a trinidad-config.xml file that makes the ADF skin in Example 4-1 the default for an application.

Example 4-2 trinidad-config.xml File

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

The source file for the ADF skin contains a comment and namespace references, as illustrated in Example 4-3. These entries in the source file for the ADF skin distinguish the file from non-ADF skin files with the .css file extension. A source file for an ADF skin requires these entries in order to open in the visual editor for the ADF skin.

Example 4-3 Default Entries for a Newly Created ADF Skin File

/**ADFFaces_Skin_File / DO NOT REMOVE**/
@namespace af "http://xmlns.oracle.com/adf/faces/rich";
@namespace dvt "http://xmlns.oracle.com/dss/adf/faces";

The first time that you create an ADF skin in your project, a resource bundle file (skinBundle.properties) is generated, as illustrated in Figure 4-1. For more information about using resource bundles, see Chapter 7, "Working With Text in an ADF Skin."

4.5 Versioning ADF Skins

You can specify version numbers for your ADF skins in the trinidad-skins.xml file using the <version> element. Use this capability if you want to distinguish between ADF skins that have the same value for the <family> element in the trinidad-skins.xml file. Note that when you configure an application to use a particular ADF skin, you do so by specifying values in the trinidad-config.xml file, as described in section Section 10.4, "Applying an ADF Skin to Your Web Application."

4.5.1 How to Version an ADF Skin

You specify a version for your ADF skin by entering a value for the <version> element in the trinidad-skins.xml file.

To version an ADF skin:

  1. In the Application Navigator, double-click the trinidad-skins.xml file. By default, this is in the Web Content/WEB-INF node.

  2. In the Structure window, right-click the skin node for the ADF skin that you want to version and choose Insert inside skin > version.

  3. In the Insert version dialog, select true from the default list if you want your application to use this version of the ADF skin when no value is specified in the <skin-version> element of the trinidad-config.xml file, as described in Section 10.4, "Applying an ADF Skin to Your Web Application."

  4. Enter a value in the name field. For example, enter v1 if this is the first version of the ADF skin.

  5. Click OK.

4.5.2 What Happens When You Version ADF Skins

Example 4-4 shows an example trinidad-skins.xml that references three source files for ADF skins (skin1.css, skin2.css, and skin3.css). Each of these ADF skins have the same value for the <family> element (test). The values for the child elements of the <version> elements distinguish between each of these ADF skins. At runtime, an application that specifies test as the value for the <skin-family> element in the application's trinidad-config.xml file uses skin3 because this ADF skin is configured as the default skin in the trinidad-skins.xml file (<default>true</default>). You can override this behavior by specifying a value for the <skin-version> element in the trinidad-config.xml file, as described in Section 10.4, "Applying an ADF Skin to Your Web Application."

Example 4-4 trinidad-skins.xml with versioned ADF skin files

<?xml version="1.0" encoding="windows-1252"?>
<skins xmlns="http://myfaces.apache.org/trinidad/skin">
  <skin>
    <id>skin1.desktop</id>
    <family>test</family>
    <extends>fusionFx-simple-v1.desktop</extends>
    <render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
    <style-sheet-name>skins/skin1/skin1.css</style-sheet-name>
    <version>
      <name>v1</name>
    </version>
  </skin>
  <skin>
    <id>skin2.desktop</id>
    <family>test</family>
    <extends>skin1.desktop</extends>
    <render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
    <style-sheet-name>skins/skin2/skin2.css</style-sheet-name>
    <version>
      <name>v2</name>
    </version>
  </skin>
  <skin>
    <id>skin3.desktop</id>
    <family>test</family>
    <extends>skin2.desktop</extends>
    <render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
    <style-sheet-name>skins/skin3/skin3.css</style-sheet-name>
    <version>
      <default>true</default>
      <name>v3</name>
    </version>
  </skin>
</skins>

4.6 Managing Working Sets

Working sets allow you to configure the Application Navigator to show you a subset of files from your project. This is particularly useful when working with large projects. Before you define your own working sets the only one available is Default, and it is a working set which includes all the files in the current application.

You can define a working set by selecting from files or containers in the Application Navigator, or by providing include and exclude filter patterns through the Manage Working Sets dialog.

To group objects in the Application Navigator into a working set:

  1. In the Application Navigator, select the objects that you want to include in a new working set.

  2. In the Application Navigator, click the Working Sets icon and select New from Selection.

    This opens a Save As dialog. For more information at any time, press F1 or click Help from within the Save As dialog.

  3. Enter a name for the working set, then click OK.

To create a working set by defining file and directory filters:

  1. In the Application Navigator, click the Working Sets icon and select Manage Working Sets.

    This opens the Working Sets dialog. Use the tree on the left to select the projects to include. In the right panel, select which files in the current project to include. For more information at any time, press F1 or click Help from within the Working Sets dialog.

  2. Click Save As to save the working set.

To create a working set from the results of a search in the Log window:

  1. In the Log window, right-click and choose Save as Working Set from the context menu.

  2. In the Create Working Set dialog, enter a name for the working set.

To see which working set you are currently using:

  • In the Application Navigator, hover the mouse over the Working Sets icon. The name of the current working set is displayed as a tooltip. Alternatively, click the Working Sets icon to bring up a menu in which the active working set is checked.

To change the active working set:

  • In the Application Navigator, click the Working Sets icon and select the working set you want to open.

    Files not belonging to the working set are removed from view.

To edit files and projects in a working set:

  1. In the Application Navigator, click the Working Sets icon and select Manage Working Sets.

    This opens the Working Sets dialog. For more information at any time, press F1 or click Help from within the Working Sets dialog.

  2. Select the working set that you want to change from the Working Set drop-down list.

  3. Make the changes as required.

To restore the view in the Application Navigator to show all files:

  • In the Application Navigator, click the Working Sets icon and select (All Files).

4.7 Importing ADF Skins from an ADF Library JAR

You can import ADF skins into your project that have been packaged in a JAR file. When you import an ADF skin into your project, the imported ADF skin is available to extend from when you create a new ADF skin, as described in Section 4.4, "Creating an ADF Skin File."

The recommended type of JAR file to use to package an ADF skin is an ADF Library JAR file. For information about how to package an ADF skin into this type of JAR file, see Section 10.3, "Packaging an ADF Skin into an ADF Library JAR."

You can import an ADF skin that you have packaged in other types of JAR file. For these ADF skins to appear in the user interface as a choice to extend from when you create a new ADF skin, your JAR file must have the same directory structure shown in Example 4-5. Your JAR file must also include an oracle.adf.common.services.ResourceService.sva file. You can generate this file by following the instructions in Section 10.3, "Packaging an ADF Skin into an ADF Library JAR."

Images referenced by the ADF skin you want to import must appear under a directory named adf, as shown in Example 4-5.

Example 4-5 Required Directory Structure and Files for a non-ADF Library JAR File

META-INF
|   MANIFEST.MF
|   oracle.adf.common.services.ResourceService.sva
|   trinidad-skins.xml
|
+---adf
|   \---skins
|       \---jarredskin
|           \---images
|               \---af_column
|                       sort_des_selected.png
|
\---skins
    \---jarredskin
            jarredskin.css

4.7.1 How to Import an ADF Skin from an ADF Library JAR

You can import ADF skins into your project that have been packaged in a JAR file.

To import an ADF skin from an ADF Library JAR:

  1. From the main menu, choose Application > Project Properties.

  2. In the Project Properties dialog, select the Libraries and Classpath page and click Add JAR/Directory.

  3. In the Add Archive or Directory dialog, navigate to the JAR file that contains the ADF skin you want to import and click Select.

    The JAR file appears in the Classpath Entries list.

  4. When finished, click OK.

4.7.2 What Happens When You Import an ADF Skin from an ADF Library JAR

The ADF skin(s) that you import from the JAR file appear in the Extends list when you create a new ADF skin, as described in Section 4.4, "Creating an ADF Skin File." After you create a new ADF skin by extending an ADF skin that you imported from a JAR file, the Extended Skins list in the Preview Pane displays the name of the ADF skin that you imported. For example, in Figure 4-2 the skin2.css ADF skin has been created by extending the ADF skin, jarredskin.css, that was imported into the project from a JAR file.

Figure 4-2 Imported ADF Skin in the Extended Skins List

Imported ADF Skin in the Extended Skins List

Properties that have been defined in the ADF skin that you imported appear with a blue upward pointing arrow in the Property Inspector. An information tip about the inheritance relationship displays when you hover the mouse over the property, as illustrated in Figure 4-3.

Figure 4-3 Property Inherited from an Imported ADF Skin

Property Inherited from an Imported ADF Skin