This chapter describes how to use Oracle JDeveloper to create and manage skins for your WebCenter Portal Framework applications.
This chapter includes the following topics:
Skins help you define the colors, fonts, images, and some dimensional details like the height and width of your application components to represent your company's preferred look and feel.
Skins are based on the Cascading Style Sheet (CSS) specification. A skin is a CSS file containing various skin selectors that define the styles of your application components. You can adjust the look and feel of any component by changing its style-related properties. Use of a skin in an application helps you to avoid specifying styles for each component individually or inserting a style sheet on each page. Every component automatically uses the styles defined in the skin. Skins help you to change an application's appearance without changing the portal pages themselves.
ADF Faces skins drive the look and feel of Portal Framework applications. For more information about ADF Faces skins, see the "ADF Faces Skins" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.
When you create a Portal Framework application, a seeded skin, portal-skin.css, is added to your application.
You can edit this seeded skin to meet your particular requirements, or you can create your own. If you choose to create your own skin, the seeded skin is still a useful tool for you to discover the different things you can achieve in your own skin.
Portal Framework applications support the runtime administration of skins to help users continue developing a portal even after it has been deployed. With runtime administration, authorized users can manage an application's skins, and create new ones, in a browser-based environment, with no requirement to install or understand JDeveloper. For more information, see Section 9.5, "Working with Portal Resources at Runtime."
You can bring skins that have been created or modified at runtime back into JDeveloper, to ensure that any changes are not lost if the portal is redeployed. You can also edit these skins to further enhance them if necessary, and upload them back into the deployed portal. For more information, see Section 9.6, "Working with Round-Trip Development."
By default, Portal Framework applications use the portal skin, which is defined in the portal-skin.css file. You can easily edit this file to suit your requirements. However, if you want to use a custom skin in your application, you must create a CSS file and define the required skin selectors.
This section includes the following topics:
For information about creating an ADF Faces skin, see the "How to Add a Custom Skin to an Application" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.
Note:
When you create a CSS file, by default, JDeveloper places it under theApplication_Root/Portal/public_html/css folder.
However, skins created at this default location are not included on the Assets page of the runtime administration console, and thus cannot be managed at runtime.
To enable authorized users to manage a skin at runtime, you must create it in the following directory:
Application_Root/Portal/public_html/oracle/webcenter/portalapp
By default, Portal Framework applications include a separate skins directory.
For more information, see Section 9.5.1.2, "How to Include a Portal Resource on the Assets Page."
After creating the CSS file, you must define the required ADF Faces skin selectors for the components in your application. For example, you can use the .AFDefaultFontFamily:alias selector to specify the font family for your application as follows:
.AFDefaultFontFamily:alias {
font-family: Tahoma, Verdana, Helvetica, sans-serif;
}
For information about:
ADF Faces skin selectors in general, refer to the "Skin Style Selectors" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework. Also refer to Oracle JDeveloper's online help for information about the selectors that you can use in a skin. These are documented in the "Skin Selectors for Fusion's ADF Faces Components" and "Skin Selectors for Fusion's Data Visualization Tools Components" topics in JDeveloper's online help.
Defining ADF Faces component style selectors, see the "Defining Skin Style Properties" and "Changing the Style Properties of a Component" sections in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.
Oracle recommends that you store asset-related artifacts, such as images and icons, on your content server and that you create a folder structure on your content server specifically for asset artifacts so that content is easy to identify and move, if required.
You can make changes to your skin after its initial creation by editing the CSS file to edit or add style selectors. You can also edit the seeded portal skin by editing the portal-skin.css file.
To edit a skin:
In the Application Navigator, right-click the skin that you want to edit, for example portal-skin.css, and choose Open.
In the source code for the skin, define the required ADF Faces skin selectors for the components in your application. For example, to set a font size of 16px for your application content, you can use the .AFDefaultFont:alias skin selector as follows:
For more information, see Section 13.2.2, "How to Define Skin Style Selectors."
Save the CSS file.
Every Portal Framework application defines a default skin that determines the appearance of all the pages within the application.
When you first create a Portal Framework application, the seeded skin, portal, is set as the application's default skin. If you subsequently create your own skin, you can set it as the default instead.
You can set the default skin for a Portal Framework application by editing the oracle.webcenter.portalapp.skin preference in the adf-config.xml file.
Note:
If runtime administration is enabled, authorized users can change the skin at runtime. For information, see the "Changing the Skin for a Portal" section in Oracle Fusion Middleware Building Portals with Oracle WebCenter Portal.To apply a skin to your application:
In the Application Resources pane of the Application Navigator, right-click the adf-config.xml file, and choose Open.
Tip:
To locate theadf-config.xml file, expand the Descriptors node, and then the ADF META-INF node.Click the Source tab.
Locate the ADF preference with the following ID:
oracle.webcenter.portalapp.skin
Set the value attribute to the family name of the skin that you want to apply to your application, for example:
value="portal"
This value must be same as the value specified for the Skin Family attribute in the Create Portal Resource or Update Portal Resource dialog of the skin.
Optionally, in the desc property, specify a description of the skin you want to apply. At runtime, this value shows up as the display name of the skin.
The display property specifies whether the skin is listed in the skin picker at runtime. Example 13-1 shows an example of the complete preference element.
Save the adf-config.xml file.
Note:
If you want to apply a skin created at a location other thanApplication_Root/Portal/public_html/oracle/webcenter/portalapp/skins, you must register the skin in the trinidad-skins.xml file and configure your application to use the skin. For information, see the "How to Register a Custom Skin" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.You can assign different skins per user, page, application, and so on, without impacting the actual application logic. To conditionally set a skin, you use the <skin-family> entry in the trinidad-config.xml file.
You can use EL expressions that can be evaluated dynamically to determine the skin to display. For example, if you want to use the German skin when the user's browser is set to the German locale, and to use the English skin otherwise, use the following <skin-family> entry in the trinidad-config.xml file:
<skin-family>#{facesContext.viewRoot.locale.language=='de' ? 'german' : 'english'}</skin-family>
For more information, see the "How to Configure a Component for Changing Skins Dynamically" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.
Note:
The default value of<skin-family> is #{preferenceBean.defaultTrinidadSkin}. If you change the default value, your application users cannot set skins at runtime in the Resource Manager.You can also use the SkinSetting API to set the skin for a user conditionally. Refer to the API for information about the calls you can use. The API is available here:
Oracle WebCenter Portal provides various default skins. All Oracle WebCenter Portal skin artifacts are available in the shared library, oracle.webcenter.skin. The shared library is packaged as an EAR, and includes several skin JARs that contain the following types of files:
.css file, the skin selector file
.png, the image files
.js, the javascript file
trinidad-skins.xml, the skin definition file
By default, the oracle.webcenter.skin shared library is referenced by all Portal Framework applications and Portlet Producer applications. Therefore, all skins are available through the classpath. When you use a portlet in your Portal Framework application, the portlet is rendered using the skin defined for your application. Therefore, to achieve skin sharing, the same skin must be accessible through the shared library, to both the Portal Framework application and the Portlet Producer application.
However, there may be a case where you modified portal-skin.css in your Portal Framework application. So, the skin available in the shared library is not the same as the updated version available in the Portal Framework application. If the skin's version in the Portal Framework application is not identical to the skin in the shared library, skin sharing between Portal Framework application and Portlet Producer application will fail because the portlet producer can access only the original version of the skin packaged in the shared library, while the Portal Framework application uses the modified skin. The Portal Framework application renders with the latest skin changes, while the portlet within the same application renders with the original skin from the shared library. This behavior is called skin coordination.
Instead of using the default skin, you may create a new custom skin in your Portal Framework application, either as a portal resource or define it in the trinidad-skins.xml with a unique skin family ID. If your application uses a portlet, the portlet producer will not be able to find the custom skin in the shared library. This causes a skin mismatch problem, and the portlet is rendered with a bare bone, simple skin rather than the custom skin used by the Portal Framework application.
Therefore, whenever you modify a skin or create a custom skin for your Portal Framework applications, you must deploy the new or modified skin as a shared library.
To deploy a skin as a shared library:
Ensure that a copy of trinidad-skins.xml is available in the WEB-INF folder of your Portal Framework application. If not, create a new one.
Update trinidad-skins.xml to point to the newly created skin CSS file.
Create a new MANIFEST.MF file in the project and provide the details for the new shared library.
The following is a sample code in a MANIFEST.MF file:
Manifest-Version: 1.0 Ant-Version: Apache Ant 1.7.1 Created-By: 1.6.0 (Sun Microsystems, Inc.) Extension-Name: oracle.webcenter.customskin Implementation-Title: oracle.webcenter.customskin Implementation-Version: 11.1.1 Implementation-Vendor: Oracle Specification-Title: Custom WebCenter shared library Specification-Version: 11.1.1
Create a new deployment profile:
Right-click the Portal project, then choose New.
In the New Gallery dialog, choose General > Deployment Profile > Shared Library JAR File, and click OK.
In the Create Deployment Profile dialog, in the Deployment Profile Name field, enter the profile name and click OK.
In the Edit JAR Deployment Profile Properties dialog, ensure that Include Manifest File check box is selected.
In the Additional Manifest Files to Merge into MANIFEST.MF section, use the Add button to add trinidad-skins.xml and the desired skin CSS file in the shared library.
Click OK.
In the Project Properties dialog, click OK.
Right-click the Portal project, choose Deploy, then select the JAR shared library deployment profile name.
In the Deploy dialog, select Deploy to a Weblogic Application Server, and click Next.
Select the WebLogic Server that hosts your portlet producer, and click Next.
Ensure that Deploy as a Shared Library is selected, then click Finish.
Update /META-INF/weblogic-application.xml for both the Portal Framework application and the Portlet Producer application to reference the custom skin shared library.
<library-ref>
<library-name>Custom_Library_Name</library-name>
<specification-version>Library_Version</specification-versi on>
</library-ref>
Redeploy both the Portal Framework application and the Portlet Producer application.
The custom skin can now be shared between these applications.
Note:
The custom skin shared library must be deployed, and must appear as "Active" on the WebLogic Server console before true skin sharing can be achieved. If there is any issue with the shared library JAR (like incorrect manifest or incorrect version), the deployed shared library will not show up in the WebLogic Server console as "Active".Note:
If you have multiple skin files, you can put all skin artifacts into one shared library JAR, and merge the twotrinidad-skins.xml files into a single file. You can keep using this shared library for all your custom skins development.This section provides information to assist you in troubleshooting problems you may encounter while using skins.
Your application does not reflect skin changes made at design time.
During development, after you make changes to a skin, you can see your CSS changes without restarting the server. The CHECK_FILE_MODIFICATION context parameter requires the server to check the timestamp on a skin and reload it if the skin has changed. This setting is automatically set to true if iterative development is enabled for your application. If iterative development is not enabled, ensure that CHECK_FILE_MODIFICATION is set to true in WEB-INF/web.xml, as shown in the following example:
<context-param> <param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION</param-name> <param-value>true</param-value> </context-param>
Skin selectors appear encoded and compressed when you open a skin's CSS file in a browser.
By default, class names in a CSS file are compressed to reduce the overall size of the file. So, the skin selectors you see, for example in the Firebug extension of Firefox, are encoded values bearing little relationship to the original names. For example, a CSS file may contain an entry that looks like:
.x123 {color: #534741}
It is easier to examine a CSS file when the compression is turned off. You can disable compression by setting the value of DISABLE_CONTENT_COMPRESSION context parameter to true in WEB-INF/web.xml, as shown in the following code:
<context-param> <param-name>org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION</param-name> <param-value>true</param-value> </context-param>
With the compression turned off, the entry may look like:
.af_panelFormLayout_label-cell
{
color: #534741
}
For better performance, it is recommended that you turn on CSS compression in a production environment. If you turn off CSS compression, it may lead to skin mismatching, as described in the next problem scenario.
When you run a page containing a portlet, the portlet is rendered without any styles or formatting.
When your application consumes a portlet based on an ADF application, the portlet producer tries to match the skin of your application. If the skins match, the producer uses your application's skin.
Skin compression is not taken into account during skin matching. If the skin compression settings differ but the skins match, the producer returns IDs like ".x123" and expects to find these values in your application; whereas your application may return values like ".af_panelFormLayout_label-cell". Therefore, no styles are found and the portlet rendering fails.
Your application and portlet producers must use the same skin compression settings. If your application uses an uncompressed skin, your portlet producer also must use an uncompressed skin.
Style sheet files (CSS) within the MDS folder structure (oracle/webcenter/portalapp) do not take effect as specified in trinidad-skins.xml.
For style sheet files (CSS) within the MDS folder structure, prefix "mds:" to the path in trinidad-skins.xml, as shown in the following example:
<skin>
<id>myskin2.desktop</id>
<family>myskin2</family>
<render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
<style-sheet-name>mds:/oracle/webcenter/portalapp/css/skin.css</style-sheet-name>
<extends>fusion.desktop</extends>
</skin>
The weblogic log output includes the following message:
<SkinFactoryImpl> <getSkin> Cannot find a skin that matches family portal and version 1.1. We will use the skin portal.desktop
Edit your application's trinidad-config.xml file and remove the <skin-version> element.
<?xml version="1.0" encoding="UTF-8"?>
<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
<skin-family>#{preferenceBean.defaultTrinidadSkin}</skin-family>
<skin-version)v1.1</skin-version>
</trinidad-config>