customizing page skins at runtime in webcenter spaces (11 ...€¦ · customizing page skins at...

Customizing Page Skins at Runtime in WebCenter Spaces (11.1.1.2.0)

An Oracle White Paper November 2009



Introduction ............................................................................................ 3

Overview ................................................................................................ 3

1. CSS and Compression .......................................................................... 4

2. Identifying the CSS Class Used by UI Components................................ 4

2.1 Example 1 – CSS Class for Logout Link Color ................................ 5

2.2 Example 2 – CSS Class for Active Top-Level Tabs.......................... 6

3. Overriding a CSS Class with a Custom Style ......................................... 7

3.1 Creating a HTML Document for Your Custom CSS......................... 7

3.2 Applying Your Custom CSS to a Page............................................. 8

3.3 Adding Multiple Style Customizations ............................................ 9

3.4 Adding Styles Containing Images ................................................. 10

4 A More Complex Example .................................................................. 13

5. References......................................................................................... 17


3

Introduction This white paper describes how to customize WebCenter Spaces page skins at runtime.

Customizing existing page skins provides a quick way for customers to “brand” their

pages and offers an alternative to writing a skin from scratch and then deploying it as

described in the Extending WebCenter Spaces1 white paper.

There are several advantages to the customization method described in this paper⎯it

can be used for any editable WebCenter Spaces page using only the Web browser, it

does not require administrative privileges, nor does it require extending WebCenter

Spaces with specially built .JAR or .WAR files. You can customize skins on a page-by-

page basis or for multiple pages by editing site templates2.

There are limitations related to patching and versioning since Cascading Style Sheets

(CSS) written using this method may need to be modified when upgrading to a newer

version of WebCenter Spaces as compressed CSS class names may change.

A tool such as Firebug is required to analyze WebCenter Spaces pages.

Overview

Customizing page skins in WebCenter Spaces at runtime involves:

• Identifying the set of Cascading Style Sheet (CSS) classes that you want to change

• Overriding the CSS classes with your own colors, fonts, and so on

• Uploading your custom CSS as an HTML document to the appropriate document library, together with any required images

• Embedding the HTML document, containing your customized styles in the page, using Content Presenter

1 http://www.oracle.com/technology/products/webcenter/pdf/owcs_r11_extend_spaces_wp.pdf 2 “Customizing Site Templates” is the subject of another whitepaper. Soon available for download from: http://www.oracle.com/technology/products/webcenter/white_papers.html


4

First, this whitepaper explains how WebCenter Spaces uses Cascading Style Sheets and then describes each of these steps in detail.

1. CSS and Compression

The CSS that defines the appearance of any page in WebCenter Spaces comes from a single consolidated CSS file. The CSS file is built on demand by combining smaller CSS files into one large one, then compressing the class names to reduce the overall size of the file.

An example of this compression is as follows (this class sets the color of labels in form layouts). Normally, a CSS contains something like this:

.af_panelFormLayout_label-cell { color: #534741 }

With compression turned on it might look like this:

.x123 {color: #534741}

By default, compression is enabled in WebCenter Spaces but it can be disabled using a context parameter in the WEB-INF/web.xml file (inside spaces.war):

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

This whitepaper assumes that compression is enabled, which is recommended for better performance.

2. Identifying the CSS Class Used by UI Components

To customize the appearance (color, font, and so on) of a UI component in WebCenter Spaces you must first identify the CSS class that the component is using. Once you know the current class, you can override it with your custom CSS.

The easiest way to find the CSS class is using a free add-on for Mozilla Firefox called Firebug. You can download Firebug from http://www.getfirebug.com or choose Tools > Add-ons from the Firefox menu, and search for “Firebug”.

(While Internet Explorer 8, Safari, and Chrome have similar capabilities, Oracle recommends Firebug on Firefox).


5

2.1 Example 1 – CSS Class for Logout Link Color

This example explains how to customize the color of the links in the global chrome of WebCenter Spaces.

Firstly, open WebCenter Spaces in Firefox. Right-click the element you want to re-style with your own color or image, and choose Inspect Element. For example, the Logout link:

Choosing Inspect Element from the Logout link right-click menu

Choosing Inspect Element opens Firebug at the bottom of the browser window:

Displaying Firebug for the Logout link

In this skin example, the Logout link color is #0D4988, which is a medium blue. On closer inspection, you can see that the style driving the Logout link is:

.xnt .xf0[theme="dark"] { color: #0D4988; }

This is known because the <a> tag in the left-hand panel is using class="xf0".


6

Using Firebug, you can try out new colors by changing “#0D4988” to another color, for example, “red”. Such changes are not stored anywhere as they are applied transiently in your browser window. Temporarily changing colors in this way is also a good way to check that you have identified the correct CSS class for the UI component you wish to style.

2.2 Example 2 – CSS Class for Active Top-Level Tabs

This example explains how to customize the CSS class that gives the active top-level tab in WebCenter Spaces a light blue gradient.

First, “inspect” one of the tabs using Firebug:

Inspecting top-level tabs using Firebug

The Firebug panel displays:

Displaying Firebug for an active tab

Firebug shows that the active tab image comes from a PNG file called t12_above_mid_a.png. Hover the cursor over the file name to view the image. Right-click the image to display its full URL, or open it in a new tab.

Firebug also shows that the CSS class driving the appearance of active top-level tabs is:

.xf7.p_AFSelected .xwg[theme="medium"] { background-image:url(/webcenter/afr/fusion/t12_above_mid_a.png); }

To change the appearance of these tabs, you must upload the new image and override this exact rule with one that points to the new image.


7

3. Overriding a CSS Class with a Custom Style

Once you know which CSS class a particular component is using, for example, .xnt .xf0[theme="dark"] in section 2.1 above, you can define your own CSS to replace the rule that is coming from the skin.

For example, to display global links in red (rather than blue) the following new rule is required:

.xnt .xf0[theme="dark"] { color: red; }

The following sections explain how to inject a customized CSS such as this into a running page.

3.1 Creating a HTML Document for Your Custom CSS

Firstly, you must create a HTML document in which to store your page’s custom style information. The location of this document is important because your customized CSS must be accessible to everyone who views the page. Create this HTML document in the appropriate folder as follows:

o Group space pages – any folder in the group space’s document library

o Business role pages – the administrator’s \public folder

o Personal pages – the page owner’s \public folder

For example:

1. Go to the document library, (typically the Documents tab, for the group space or personal space that owns the page.

2. Create a folder for the custom CSS or identify an existing one.

Remember that if your CSS customizations apply to business role pages or personal pages the folder must be public.

3. Choose File > New >HTML Document or click the icon.

4. Enter a file name, for example, mycss.htm.

5. Switch to Source Code Editing Mode by clicking the icon in the editor.

6. Enter your custom CSS surrounded by a <style> tag. For example:

<style type="text/css"> .xnt .xf0[theme="dark"] { color: red; } </style>

7. Click the Create button.


8

3.2 Applying Your Custom CSS to a Page

You “inject” a customized CSS into a WebCenter Spaces page by adding the HTML file (containing the custom CSS) to the page using Content Presenter. The custom style overrides the style that is defined in the page skin because the custom CSS is included after the skin’s CSS.

Follow these steps for each page that requires a customized CSS:

1. Go to the page.

2. Click Page Actions > Edit Page to edit the page.

3. Click Add Content on one of the boxes on the page.

4. Click the Documents folder in the catalog.

5. Drill down until you find the HTML document that contains your custom CSS. For example, mycss.htm.

Locating the HTML file that contains your custom CSS

6. Click Add next to the HTML file, and then choose Content Presenter from the menu.

Choosing Content Presenter from the catalog menu

7. Click Close to dismiss the Catalog. You should see the new item on the page.

8. Click Save and then Close to exit Oracle Composer.

The new style that is defined in your customized CSS takes effect on the page. Using the example provided, the color of the links in the global chrome display in red:


9

Effect of the custom CSS on global links

You can repeat these steps for any user-created page that requires your customized CSS (mycss.htm in this example).

3.3 Adding Multiple Style Customizations

The above example overrides a single CSS class, that is, the color of links in the global chrome. To override multiple styles, simply edit the HTML document that contains your style customizations and add further customizations to the file. Your changes will be reflected in every page that includes the HTML document.

For example:

1. Go to the document library, typically the Documents tab, for the group space or personal space that owns the page.

2. Find the HTML document that contains your custom CSS, for example, mycss.htm.

3. Choose File > Versioning > Check Out to check out the file.

4. Choose File >Edit… or click the Edit icon .

5. Update the code with additional CSS classes. For example:

<style type="text/css"> .xnt .xf0[theme="dark"] { /* global links */ color: red; font-size: 12px; font-family: verdana; } .x178 { /* page content */ background-color:lightyellow; } </style>

6. Click Check-in and close,

7. Now navigate to any page that includes your style customizations to observe the effect.


10

3.4 Adding Styles Containing Images

The previous sections describe how to change colors and fonts on WebCenter Spaces pages but often, the appearance of WebCenter Spaces comes from small images. For example, top-level tabs comprise three images, one each for the left, center, and right of the tab.

Three parts of a top-level tab (left, center, right)

Use Firebug (see also Section 2.2) to inspect the left part of the tab. The style looks like this:

.xf7.p_AFSelected .xwe[theme="medium"] { background-image:url(/webcenter/afr/fusion/t12_above_start_a.png) }

Similarly, the right area looks like this:

.xf7.p_AFSelected .xwg[theme="medium"] { background-image:url(/webcenter/afr/fusion/t12_above_mid_a.png) }

And the center area looks like this:

.xf7.p_AFSelected .xwf[theme="medium"] { background-image:url(/webcenter/afr/fusion/t12_above_end_a.png) }

To change the appearance of the tabs, you must create and upload new images and override the current styles with rules that point to the new images.

New images should keep the same dimensions (width and height) as the images they are to replace and it is advisable to keep the same filenames too, for example, t12_above_mid_a.png.


11

3.4.1 Uploading Images for Custom Styles

In a group space, the best place to upload new images is the group space document library. For ease of use, consider adding an \images subfolder in the same folder as your customized style file:

Images uploaded to a group space document library

Similarly, you can upload images for business role pages and personal pages to an \images subfolder, located under the same \public folder as the custom CSS:

Images uploaded to a personal space document library


12

Once uploaded, you can determine the URL to an image (in the document library) by right-clicking the link to the image and copying the link location to the clipboard:

Copying the URL of an image to the clipboard from document library

Alternatively, select the image in the document library, and choose File > Properties or click the icon in the toolbar. In the Document Properties screen, right-click the link next to URL and

copy the link location to the clipboard:

Copying the URL of an image to the clipboard from document properties

Use that URL to write a new CSS rule such as:

.xf7.p_AFSelected .xwf[theme="medium"] { background-image:url(/webcenter/content/conn/stellent- stanl18/path/WebCenter0809/csstest/images/t12_above_end_n.png) }

Add the custom rule to the HTML document that contains your style customizations, as described in Section 3.3.


13

4 A More Complex Example

This section provides a more complex CSS customization example. The sample provided includes overrides for the branding bar, the tabs, the page background, and the ShowDetailFrames (displayed around task flows).

WebCenter Spaces with the sample CSS applied

All the images referenced in this whitepaper are available for download from OTN (see accompanying file css_images.zip). If you want to follow this example, remember to modify all the image URLs to reflect their location on your content server.

The example CSS is only applicable if you are using one of the “FX skins”, for example, Deep Sea FX, Dusk FX, Mist FX, and so on.

The complete CSS is as follows:


14

<style type="text/css"> /* global Container */ .xn5[theme="dark"] { background-color: #5B7281; background-image: url(/webcenter/content/conn/stellent-stanl18/path/WebCenter0809/csstest/images/global_bg.jpg); background-repeat: repeat-x; } /* branding bar title */ .xdj { color: #5B7381; font-family: serif; font-size: 18px; font-weight: bold; padding-top: 4px; } /* branding bar gradient */ .xnt.xhl[src="/webcenter/afr/gradient-white-none.png"] { height: 0px; } /* goLink in global chrome overrides hardcoded white */ .xnt.x1a > .xfg { background-image: url(/webcenter/content/conn/stellent-stanl18/path/WebCenter0809/csstest/images/global_bg.jpg); display: block; height: 2.5em; } /* branding bar global links */ .xnt .xf0[theme="dark"], .xnt .xfg[theme="dark"] { color: #666666; } /* remove bottom border from contentBody */ .xna[theme="contentBody"] { border-bottom: none; } /* contentBody center */ .xpp[theme="contentBody"] {

background-color: transparent; } /* contentBody top left, top, and top right */ .xpl[theme="contentBody"], .xpm[theme="contentBody"], .xpn[theme="contentBody"] {

background-image: none; } /* contentBody left, right */ .xpo[theme="contentBody"], .xpr[theme="contentBody"] {


15

background-image: none; background-color: transparent;

} /* contentBody bottom left, top, and top right */ .xps[theme="contentBody"], .xpt[theme="contentBody"], .xpu[theme="contentBody"] {

background-color: transparent; } .xpt[theme="contentBody"], .xpq[theme="contentBody"] { display: none; } /* top-level in-active tabs */ .xwe[theme="medium"], .xf7:hover .xwe[theme="medium"] { background-image: url(/webcenter/content/conn/stellent-stanl18/path/WebCenter0809/csstest/images/t12_above_start_n.png); } .xwg[theme="medium"] { background-image: url(/webcenter/content/conn/stellent-stanl18/path/WebCenter0809/csstest/images/t12_above_mid_n.png); color: #FFFFFF; } .xwf[theme="medium"], .xf7:hover .xwf[theme="medium"] { background-image: url(/webcenter/content/conn/stellent-stanl18/path/WebCenter0809/csstest/images/t12_above_end_n.png); } /* top-level active tab */ .xf7.p_AFSelected .xwe[theme="medium"] { background-image: url(/webcenter/content/conn/stellent-stanl18/path/WebCenter0809/csstest/images/t12_above_start_a.png); } .xf7.p_AFSelected .xwg[theme="medium"] { background-image: url(/webcenter/content/conn/stellent-stanl18/path/WebCenter0809/csstest/images/t12_above_mid_a.png); color: #000000; } .xf7.p_AFSelected .xwf[theme="medium"] { background-image: url(/webcenter/content/conn/stellent-stanl18/path/WebCenter0809/csstest/images/t12_above_end_a.png); } /* second level tab bar */ .xpm[theme="medium"] { background-image: url(/webcenter/content/conn/stellent-stanl18/path/WebCenter0809/csstest/images/dblt.png); } .xpo[theme="medium"]


16

{ background-image: url(/webcenter/content/conn/stellent-stanl18/path/WebCenter0809/csstest/images/dbls.png); } .xpp[theme="medium"] { background-image: url(/webcenter/content/conn/stellent-stanl18/path/WebCenter0809/csstest/images/dblc.png); } .xpr[theme="medium"] { background-image: url(/webcenter/content/conn/stellent-stanl18/path/WebCenter0809/csstest/images/dble.png); } /* page content */ .x178 { background-color: #f0f0f0; background-image: url(/webcenter/content/conn/stellent-stanl18/path/WebCenter0809/csstest/images/watermark.png); background-repeat: repeat; } /* SDF Header */ .x18w.p_AFMedium { padding-bottom: 2px; } /* SDF Header / Medium */ .x18x.p_AFMedium, .x18y.p_AFMedium, .x18z.p_AFMedium { background-image: none; } /* SDF Header Text */ .x18x { color: #444444; font-family: corbel; font-size: 14px; font-weight: normal; } /* SDF Content / Medium */ .x18u.p_AFMedium { background-color: transparent; background-image: url(/webcenter/content/conn/stellent-stanl18/path/WebCenter0809/csstest/images/sdfcontent.png); background-repeat: repeat-x; border-color: #999999; border-width: 1px 0 0; color: black; } </style>


17

5. References

Visit the following Web pages to learn more about CSS and skinning in ADF Faces.

Apache Trinidad Skinning

http://myfaces.apache.org/trinidad/devguide/skinning.html

W3C CSS

http://www.w3.org/Style/CSS/

Modifying Page Skins at Runtime in WebCenter Spaces (11.1.1.2.0) November 2009 Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065 U.S.A. Worldwide Inquiries: Phone: +1.650.506.7000 Fax: +1.650.506.7200 oracle.com

Copyright © 2009, Oracle and/or its affiliates. All rights reserved. This document is provided for information purposes only and the contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. We specifically disclaim any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without our prior written permission.

Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

0109