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 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."
When skinning WebCenter Portal, you can look at it from coarse-grain and fine-grain standpoint. At the coarse-grain level many large elements on the page, such as the background and the center of the page, can use very basic styling techniques to impart a look and feel to particular corporate brand with very little effort. At the fine-grain level you can apply the styling to specific components and controls within the page. The most efficient way to develop your skin is to start by defining the coarse-grain elements and then use fine-grain styling to tune your overall look and feel to be inline with your corporate brand.
In many cases a hybrid model of styling works very well. Taking the coarse-grained elements (page background, main portion of the body, and so on) and using traditional CSS approaches with those, but then getting specific using the ADF skinning, will work together to generate the overall appearance for WebCenter Portal.
An example of a hybrid approach would be using technology in WebCenter Portal to generate a menu that uses unordered lists and list items, then applying traditional CSS to them. Even though you are benefiting from WebCenter Portal's navigation models, you are not doing traditional ADF skinning – but instead using standard CSS.
Expression Language (EL) allows you to access the various objects for navigation within your template design. Looping in EL is simple and coding is done inline with the page template. You can mix regular HTML directly into the looping markup.
When using coarse-grained techniques in addition to ADF styling, it is often helpful to hold various styling assets outside of WebCenter Portal. To do this you can use WebCenter Content to manage all of the unstructured assets for WebCenter Portal. They can include things like CSS and images that you want manage within your environment and provides revision control and workflow. This is a best practice if you want to allow design teams to access and work with WebCenter Portal without involving the development team for each and every change
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 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 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 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.3.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 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 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 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>