5 Customizing Portal Layout Using CSS - Legacy User Interface

Oracle WebCenter Interaction provides a CSS template file that contains a wide range of CSS classes and IDs to facilitate customization for legacy user interfaces. The CSS template file is located in the PT_HOME\ptimages\tools\cssmill\templates directory in the portal Image Service.

The structure of the portal page is designed to support customizations on global, per user, per community, per product, per page, and per portlet levels. The portal supports 18 different color schemes and 8 languages out of the box. The CSS Style Sheet Mill allows you to implement custom color schemes and add new language style sheets easily without modifying portal source code.

Note:

This approach is provided to support the legacy user interface; the recommended way to customize the portal page is using Adaptive Layouts and Adaptive Styles. For details, see Chapter 3, "Using Adaptive Page Layouts" and Chapter 4, "Using Adaptive Styles (CSS Customization)."

Customizing Portal Page Layout and Design

All major and minor page elements are assigned either a CSS ID or class, or both. Uniquely identifiable objects (such as a specific page) are given unique ids. Identifiable classes of objects (such as pages in a specific community) are given classes. Each major region of the page is treated as a named box. For an introduction to the portal page, see Chapter 2, "Portal Page Layout".

These changes to the portal UI make it possible to modify page layout and design using the portal CSS template file. You can also use CSS to hide specific functionality exposed in the portal page. This section provides basic syntax rules and customization examples.

Syntax Guidelines

The portal CSS template file follows standard CSS syntax rules. For details on CSS, see http://www.w3.org/Style/CSS/. Below are some basic rules to keep in mind when modifying page styles.

To apply styles to a specific page, use the page ID. The example below sets the background color for the page with ID 1.

#pt-page-1
{
background-color: red;
}

You can change style settings for a specific user or type of user (administrator or guest). The example below displays a special header image on all browse-mode pages for guests. To modify a style for a specific user, replace "guest" with the name of the appropriate portal user object (for example, .ptPageUser-mycompany domain ad\Joe Smith).

.ptPageUser-guest #pt-header
{
background-image: url(/imageserver/plumtree/portal/private/img/example_guest.gif);
}

You can also change styles for specific communities. The example below sets the background color for the community with ID 200.

.ptCommunity-200
{
background-color: #AAA;
}

Customizing Layout

The portal CSS template file allows you to make a wide range of changes to the layout of the portal page. Below are some examples of layout customizations.

Modify page width: Specify whether a page spans the whole window or a portion of the window. This provides support for specific audiences such as those on smaller monitors. The example below limits the page to 800 x 200 pixels.
```
.portalContent
{
width: 800px;
height: 200px;
overflow: auto;
}
```

Change navigation tab location: Modify the location of the portal navigation tabs. You can apply changes to the entire portal, or to specific pages or groups of pages. The example below sets the tabs to appear in the center of the page header.
```
#pt-user-nav
{
display: inline;
margin-left: 15px;
margin-right: 15px;
}
```

Customizing Style

The portal CSS template file allows you to make a wide range of style changes to the portal page. Below are some examples of style customizations.

Customize portal banners and footers: Change the look and feel for portal banners and footers. You can apply changes to the entire portal, or to specific pages or groups of pages. For example, the code below changes the footer height.
```
#pt-footer { height: 36px; }
```
The code below hides the footer on the page with ID 1.
```
#pt-page-1 #pt-footer { display: none; }
```

Change the background color for a specific page or community: Modify the background color for a single page or a specific community. The example below sets the background color for the community with ID 200. To change the color scheme for the entire portal, modify the style sheet as explained in the next section, Deploying Portal Style Sheet Customizations (CSS Mill).
```
.ptCommunity-200
{
background-color: #AAA;
}
```

Change the background for a specific user: Modify the background of the portal for a specific user or type of user (administrator or guest). The example below displays a background image on all browse-mode pages for administrators.
```
.ptPageUser-administrator
{
background-image: url(/imageserver/plumtree/portal/private/img/example_administrator.gif);
}
```

Customize portal navigation tabs: Define the dimension of portal tabs.
```
#pt-user-nav 
{
 width: 25px;
 }
```
Customize form elements: As with any CSS implementation, you can use the portal CSS template file to control text box sizing, button colors and fonts, and more.
Reference images: Reference images through CSS, including banner and branding images, and background images applied to page components. The example below displays a special header image on all browse-mode pages for guests.
```
.ptPageUser-guest #pt-header
{
background-image: url(/imageserver/plumtree/portal/private/img/example_guest.gif);
}
```

Setting Constraints

The portal CSS template file allows you to remove specific functionality from the page for a group of users or for a specific page or community.

Note: Using CSS to hide functionality is not a secure means of preventing user-server interaction. All examples are for demonstration purposes only and are not meant to imply a complete solution to any overall security scheme.

Disable specific functionality: Turn off controls for a specific group of users or for a specific page or community. You can disable navigation, search, and a variety of links, including My Home, My Account, Login/Logout and Help. The example below disables search controls for all guests.
```
.ptPageUser-guest #pt-search-controls
{
display: none;
}
```

Changing the Portal Color Scheme

The portal comes with 18 standard color schemes:

1: Purple/Violet	10: Blue Gray
2: Golden Brown	11: Dark Teal
3: Blue Purple	12: Dark Gray
4: Blue Green	13: Olive
5: Medium Brown (Cinnamon)	14: Standard (Royal Blue)
6: Strawberry	15: Pine Green
7: Purple (Grape)	16: Cranberry
8: Gold	17: Orange/ Rust
9: Dark Brown	18: Teal

To create a custom color scheme, start with an existing properties file.

In the portal Image Service, navigate to PT_HOME\ptimages\tools\cssmill\prop-color.
Make a copy of the color.18.properties file and rename it to "color.19.properties" (it is a best practice to create a new file so you can preserve all original copies of the properties files).

Open the new file in a text editor and modify the properties to create your custom color scheme. Enter the same simplified name for the new color scheme for each of the language style sheets. The example below creates a new color scheme based on the United States Postal Service web site.

<!-- color.19.properties -->
 
colorscheme.name.de=usps
colorscheme.name.en=usps
colorscheme.name.es=usps
colorscheme.name.fr=usps
colorscheme.name.it=usps
colorscheme.name.ja=usps
colorscheme.name.ko=usps
colorscheme.name.pt=usps
colorscheme.name.zh=usps
 
color.bg.darkest=#CC0000
color.bg.darker=#0066CC
color.bg.medium=#B5C4E1
color.bg.lighter=#99CCFF 
color.fg.medium=#003399
color.fg.light=#FFFFFF 
color.fg.alert.warning=RED
color.fg.alert.confirm=GREEN 
color.link.hover=#E7EFA1

Save the new properties file and close it.

Navigate to PT_HOME\ptimages\tools\cssmill. Open the file css-mill-ant-1-6.xml.
Search for the make_community_css target.

Copy the last sequence entry and paste it at the end of the list. Make sure to copy the entire entry: <make_comm_color_css COLOR="18" CSSPATH="@{CSSPATH}"/>. Modify the COLOR value by changing it to the number for your custom color scheme. The example below uses "19" for the new color property file created in the prevous section.

<!-- make_community_css -->
<target name="make_community_css" depends="make_css_dir">
<make_community_css CSSPATH="css/">
</make_community_css>
</target> 
<macrodef name="make_community_css">
<attribute name="CSSPATH" default="css/"/>
<sequential> 
<make_comm_color_css COLOR="1" CSSPATH="@{CSSPATH}"/>
<make_comm_color_css COLOR="2" CSSPATH="@{CSSPATH}"/>
...
<make_comm_color_css COLOR="18" CSSPATH="@{CSSPATH}"/>
<make_comm_color_css COLOR="19" CSSPATH="@{CSSPATH}"/>
 
<make_index FILENAME="community-themes.txt" CSSPATH="css/" INDEX="css/community-themes.txt"/> 
</sequential>
</macrodef>

Search for the make_index target.

Copy the last sequence entry and paste it at the end of the list. Make sure to copy the entire entry: <append_index_for_color COLOR="18" INDEX="@{INDEX}"/>. Modify the COLOR value by changing it to the number for your custom color scheme. The example below uses "19" for the new color property file created in the prevous section.

target name="make_index" depends="make_css_dir">
<make_index>
</make_index>
</target>
 
<macrodef name="make_index">
<attribute name="FILENAME" default="community-themes.txt"/>
<attribute name="CSSPATH" default="css/"/>
<attribute name="INDEX" default="css/community-themes.txt"/> 
<sequential>
<echo> Making @{INDEX}</echo>
<tstamp prefix="backup"/>
<touch file="@{INDEX}"/>
<copy filtering="false"
overwrite="yes"
file="@{INDEX}"
tofile="backup/@{FILENAME}${timestamp_appendix}"/>
 
<delete file="@{INDEX}"/>
<touch file="@{INDEX}"/>
 
<append_index_for_color COLOR="1" INDEX="@{INDEX}"/>
<append_index_for_color COLOR="2" INDEX="@{INDEX}"/>
...
<append_index_for_color COLOR="18" INDEX="@{INDEX}"/>
<append_index_for_color COLOR="19" INDEX="@{INDEX}"/>
</sequential>
</macrodef>

Save the css-mill-ant-1-6.xml file and close it.

To deploy your customizations, run the CSS Mill as described in Deploying Portal Style Sheet Customizations (CSS Mill).

Customizing Portlet Layout and Style

The CSS template also allows you to customize portlet content and design in a variety of ways. You can customize specific portlets using the unique ID assigned to each portlet, or use CSS classes to modify the design of a group of portlets (for example, those in the first column of a two-column page). You can also set constraints for portlets, including limiting a specific portlet to a three-column layout or preventing users from collapsing portlets.

This section provides basic syntax rules and customization examples.

Syntax Guidelines

The portal CSS template file follows standard CSS syntax rules. For details on CSS, see http://www.w3.org/Style/CSS/. Below are some basic rules to keep in mind when modifying portlet styles.

To apply a CSS tag to a specific portlet, use the portlet ID. the example below increases the size of the portlet title for the portlet with ID 6. (You can also define basic styles for a specific portlet within the portlet code.)

#pt-portlet-6 .portletTitle
{
height: 26px;
}

You can also apply styles to groups of portlets, including those on a specific page or in a specific community. To apply styles to a portlet on a specific page or community, use the page or community ID. The example below removes the portlet preferences link for portlets on the page with ID 100.

.portletPrefsButton #pt-page-100 
{
display: none;
}

Customizing Portlet Style

The portal CSS template file allows you to make a wide range of style changes to portlets. Following are examples of portlet style customizations using the portal CSS template file.

Change portlet color schemes: Change the color scheme of portlets for specific columns.
```
#pt-portlet-100 { background-color: white; }
#pt-portlet-100 .platPortletHeaderBg { background-color: tan; } 
```
You can also define basic styles for portlets within the portlet code (instead of in the CSS template file). Use the pt:token adaptive tag to reference the portlet ID and ensure that the style is only applied to the current portlet. This code sets the portlet background to tan. (For details on adaptive tags, see the Oracle WebCenter Interaction Web Service Development Guide.
```
<pt:namespace pt:token="$$TOKEN$$" xmlns:pt='http://www.plumtree.com/xmlschemas/ptui/'/> 
<style> 
#pt-portlet-$$TOKEN$$ { background-color: tan; } 
</style> 
```

Add custom portlet padding: Control the padding around individual portlets, groups of portlets in a column, and selective portlets. The sample code below adds padding below the portlet with ID 43.
```
#pt-portlet-43 .portletBody 
{
padding-bottom: 5px;
}
```

Setting Constraints

The portal CSS template file allows you to set constraints for portlets. Below are some examples.

Set the portlet width for specific pages or layouts: Set the width of a portlet for a specific page or set of pages. You can define portlet settings by page, layout/column, or community. The example below limits the portlet with ID 15 to a width of 250 pixels on the page with ID 1.
```
#pt-page-1 #pt-portlet-15
{
width: 250px;
}
```

Prevent certain users from collapsing portlets: Disable the collapse option for a group of users or for portlets on a specific page. You can also prevent users from collapsing a specific portlet by using the portlet ID.
```
.ptPageUser-guest .portletCollapseButton
{
display: none;
}
```
Note: Using CSS to hide functionality is not a secure means of preventing user-server interaction. All examples are for demonstration purposes only and are not meant to imply a complete solution to any overall security scheme.

To deploy your customizations, run the CSS Mill as described in Deploying Portal Style Sheet Customizations (CSS Mill).

Adding New Language Style Sheets

If you add support for an additional language to the portal, you must add the corresponding style sheets for that language. The portal was designed to make adding languages and generating the language style sheets relatively easy.

Each language file in the \ptimages\tools\cssmill\prop-text folder has language-specific values for font style, font size, text style, etc. This design makes it easy to change the default font for each language. For example, if you want the default font for the Japanese user interface to be Tahoma, add Tahoma to the "ja" language file in the prop-text folder.

After adding a language file, you must also edit the build.xml file to generate the new language style sheets.

For example, the steps below explain how to add "Dutch" as a portal user interface language.

Navigate to the \ptimages\tools\cssmill\prop-text folder in the Image Service. Copy one of the existing files to the same folder and rename it using the language conventions in ISO-639-1 and ISO-3166. For example, for Dutch, rename the file to "nl".
Open the new file in a text editor and make any necessary modifications for the new language. For example, to add a new default font, you could change the following line: font.largest=20px verdana,arial,helvetica,"sans-serif"to:font.largest=21px Tahoma,"MS PGothic",Verdana,"sans-serif"Be sure to add the new font for each font attribute in the language file.
Navigate to the \ptimages\tools\cssmill\prop-color folder in the Image Service. Add the new language's translation for the name of the color in every color properties file. For example, open the color.1.properties file and copy the last colorscheme.name entry. Change the name according to the new language ID used in step 1. In this example, you could copy the following line: colorscheme.name.zh=\\u6DE1\\u7D2Band change it to:colorscheme.name.nl=Lavendelblauw
Modify the Ant build script (build.xml) to include the new language to the style sheet collection by following the steps below. (This is the only way the script knows to create versions of the new style sheet for each language supported by the portal.)
1. Navigate to the \cssmill directory and open the build.xml file in a text editor.
2. Add an entry for the new language within the make_main_css target: Copy the last <antcall target="make_main_language_css"> entry and paste it at the end of the list. Modify the <param name="LANGUAGE" value="pt"/> tag by changing the value ("pt") to the language ID used in step 1 ("nl").
3. Add an entry for the new language within the make_comm_color_css target: Copy the last <antcall target="make_comm_lang_color_css"> entry and paste it at the end of the list. Modify the <param name="LANGUAGE" value="pt"/> tag by changing the value ("pt") to the language ID used in step 1 ("nl").
4. Add an entry for the new language within the append_index_for_color target: Copy the last <concat destfile="${INDEX}" append="true">mainstyle${COLOR}-pt.css=${colorscheme.name.pt}</concat> entry and paste it at the end of the list. Change the language id in the new line to the new language id by changing the value ("pt") to the language ID used in step 1 ("nl"). In this example, the new line would look like this:<concat destfile="${INDEX}" append="true">mainstyle${COLOR}-nl.css=${colorscheme.name.nl}</concat>
5. Save the build.xml file and close it.
Create the new style sheets by running the make_all batch file as explained in the next section, Deploying Portal Style Sheet Customizations (CSS Mill).
Verify that the new language style sheets were created based on the new language property file. Navigate to the cssmill\css directory and confirm that there are 20 new style files with the new language ID used in step 1 ("mainstyle-nl.css"). For further verification, open the community-themes.txt file (in the \css directory) and confirm that there is a new entry corresponding to the language ID used in the new language property file.
After confirming that your changes are correct, move the new style sheet files from the \cssmill\css folder to the \imageserver\common\public\css folder used by the portal.
Restart the Java Application Server.

Deploying Portal Style Sheet Customizations (CSS Mill)

After changing the portal style sheet template, you must run the CSS Style Sheet Mill to deploy your customizations. The CSS Mill facilitates the management and maintenance of style sheets and allows you to create new style sheets quickly and easily using property files to define key attributes used in the portal's style classes. The portal comes with a set of standard property files, and you can create new files for use in custom style sheets. Although it is possible to edit existing property files, it is recommended practice to make a new property file so you do not lose any information.

The CSS Mill creates all the portal style sheets dynamically using the portal style sheet template file, making them disposable. The entire set is created by running a batch file. This configuration also allows you to update portal style attributes (for example, the background color across all pages) by editing a single root property file; when the batch file is run, the changes are propagated through all instances of the attribute in every style sheet.

CSS Mill Structure

The files used by the CSS Mill are located in the PT_HOME\ptimages\tools\cssmill directory in the portal Image Service. This directory includes the following folders:

\prop-text contains text property files; a different file is provided for each language supported by the portal.
\prop-color contains color property files; a different file is provided for each of the 18 standard color combinations available in the portal.
\templates contains the files that define the styles used by the portal. Other products can have their own templates.

Each property name in a property file represents a marker used in a template. The CSS Mill uses the values set in the property files to replace the corresponding markers in the associated style sheet template and create new style sheets for use by the portal. To view where a property name is used within a style sheet, look for the corresponding marker in one of the templates. Markers use the syntax @MarkerName@.

The root \cssmill folder contains the batch files and the build.xml file that provides the necessary Ant scripts to create the style sheets. There are three commonly-used batch files:

make_all creates all portal style sheets by replacing the markers in the templates with the corresponding values from the property files. This script creates a version of each style sheet for each language supported by the portal and places the files in the \css folder, and saves a backup of the previous version in the \backup directory.
make_portal_css creates only the default portal style sheets. The default portal style sheet is the single color style sheet that appears in the default portal.
make_community_css creates only the community style sheets. Community style sheets are the 18x8 style sheets used in header portlets.

Using the CSS Mill

To deploy changes made to the portal style sheet template, you must run the CSS Mill to create new style sheets for the portal. You can use one of the standard color schemes or implement a custom color scheme from a custom properties file. These instructions utilize both the portal server and the portal Image Service.

These instructions use Ant 1.6.x.

Open a command prompt on the portal Image Service and change the directory to the CSS Mill root directory (PT_HOME\ptimages\tools\cssmill).
Run the following command: ant make_all. This command creates new style sheets for each of the properties files.

Note: If you are implementing a new color scheme, you can use the new style sheets created by the ant make_all command or overwrite the default style sheets using ant make_all -DCOLOR=19 (set the -DCOLOR parameter to the number of the properties file that should be used).
Open Windows Explorer and navigate to PT_HOME\ptimages\tools\cssmill\css. Sort by Date Modified and find the files generated in the previous step.
Navigate to PT_HOME\ptimages\tools\cssmill\css and copy the stylesheets for the color scheme you want to implement (to continue the example in the previous section, you would copy the mainstyle19 style sheets). If you did not implement a new color scheme or chose to overwrite the default style sheets, copy the mainstyle files instead.
Paste the copied files to PT_HOME\ptimages\imageserver\plumtree\common\public\css. Select "Yes to all" if asked whether you would like to overwrite the existing files of the same name.
On your portal server, open Windows Explorer and navigate to PT_HOME\settings\portal and open the portalconfig.xml file in a text editor.
Find the <StyleSheetName> tag (under the <MyPages> tag) and change the value attribute to "mainstyle#" where "#" is the number of the color scheme you want to apply. In the example below, the color scheme is changed to the custom color scheme, #19.
```

<StyleSheetName value="mainstyle19"></StyleSheetName>
```
Note: If you did not implement a new color scheme or chose to overwrite the default style sheets, the value attribute should be "mainstyle".
Still on your portal server, reload your portal. (It is not necessary to restart the application server after running the CSS Mill.)