# How Look & Feel Determines Rendering

When you build a portal in WebLogic Workshop, the look & feels you use are the key to how your portal is rendered and what it looks like when it is rendered. This topic shows you how the different pieces of the look & feel framework are combined and configured to provide what the portal framework needs to render the look & feel in HTML.

This topic contains the following sections:

Overview

The Look & Feel File

The Portal File

Location of the Look & Feel Resources

The skin.properties File

Look & Feel Overrides

Summary

## Overview

The look & feel determines the following:

- Skin - A skin is a group of Cascading Style Sheet (CSS) files, framework images (mainly for portlet titlebar icons), and JavaScript functionality that is used in the portal desktop when it is rendered in HTML. A portal Web project can have multiple skins. When you select a look & feel for a desktop, a specific skin is used. Following are example skin elements:

  Image | CSS Style | JavaScript Function
      .bea-portal-button-float
      {
      }
      .bea-portal-button-float img
      {
          vertical-align: top;
          margin: 1px;
          border-style: solid;
          border-width: 1px;
          border-color: #666699;
      }
      function initPortletFloatButtons()
      {
          var links = document.getElementsByTagName("a");
          for (var i = 0; i < links.length; i++)
              {
                  if (links[i].className && links[i].className == "bea-portal-button-float")
                  {
                  initPortletFloatButton(links[i]);
                   }
              }
      }

- Skeleton JSPs - A skeleton is a group of JSPs that are used to render each component of the portal desktop as HTML, from the desktop to books and pages to portlet titlebars. The skeleton provides the physical boundaries of the portal components and provides references to the images, CSS classes, and JavaScript functions from the skin needed to render the portal. A portal Web project can have multiple skeletons. When you select a look & feel for a desktop, a specific skin and skeleton is used.

A look & feel is represented by an XML file (with .laf extension), as shown in the following figure.

Developers building portals with WebLogic Workshop are not the only users who can select the look & feel used by a portal desktop. While developers create look & feels and select the default look & feel used by a portal, portal administrators and visitors may ultimately determine the desktop look & feel. The following figures show how portal administrators and users can change the look & feel used by the desktop.

After a portal administrator creates a desktop in the WebLogic Administration Portal, the administrator can change the desktop look & feel on the Dekstop Properties page.

If visitor tools are enabled for the desktop, visitors can click the "Customize My Portal" link and change the desktop look and feel.

The following section shows the look & feel XML file and describes how it is used as the basis of portal desktop rendering.

## The Look & Feel File

Look & feel files point to the specific skin and skeleton to be used for the overall desktop look & feel.

Look & feel files are stored in the following location: <portal_Web_project>/framework/markup/lookandfeel/. Following is the avitek.laf provided by BEA. The key attributes are highlighted.

    <?xml version="1.0" encoding="UTF-8"?>
    <netuix:markupDefinition xmlns:netuix="http://www.bea.com/servers/netuix/xsd/controls/netuix/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.bea.com/servers/netuix/xsd/controls/netuix/1.0.0 markup-netuix-1_0_0.xsd">
        <netuix:locale language="en"/>
        <netuix:markup>
            <netuix:lookAndFeel
                definitionLabel="avitek" title="avitek"
                description="The avitek look and feel"
                skin="avitek" skinPath="/framework/skins/"
                skeleton="default" skeletonPath="/framework/skeletons/"
                markupType="LookAndFeel" markupName="avitek"/>
        </netuix:markup>
    </netuix:markupDefinition>

The following table describes the look & feel attributes.

Attribute | Description
definitionLabel | Requried. The unique label used to identify the look & feel for setting entitlements. Each look & feel in the portal Web project must have a unique definitionLabel. For best practices, use the same name as the markupName.
title | Required. The string used to display the name in the Look & Feel drop-down fields in WebLogic Workshop, the WebLogic Administration Portal, and on the visitor tools page.
description | Optional. Description of the look & feel. The description is used in the WebLogic Administration Portal; when you select a look & feel in the portal Library, the description appears on the Look & Feel Properties page.
skin | Optional. The name of the directory containing the skin you want to use. If you do not set this attribute, the /framework/skins/default skin is used.
skinPath | Optional. The path, relative to the portal Web project, to the parent directory of the skin directory. If you do not set this attribute, the /framework/skins/<skin_attribute_name> skin is used. If no skin attribute is set, the /framework/skins/default skin is used.
skeleton | Optional. The name of the directory containing the skeleton JSPs you want to use. If you do not set this attribute, the framework uses the default.skeleton.id path in the skin.properties file of the skin used. If you do not set this attribute and no default.skeleton.id path is set in skin.properties, the /framework/skeletons/default skeleton is used.
skeletonPath | Optional. The path, relative to the portal Web project, to the parent directory of the skeleton directory. If you do not set this attribute, the framework uses the default.skeleton.path in the skin.properties file of the skin is used. If you do not set this attribute and no default.skeleton.path is set in skin.properties, the /framework/skeletons/<skeleton_attribute_name> skeleton is used. If you do not set this attribute and no skeleton attribute is set, the /framework/skeletons/<default.skeleton.id> skeleton is used. If you do not set this attribute and no skeleton attribute is set, and skin.properties contains no default.skeleton.id, the /framework/skeletons/default skeleton is used.
markupType | Required. The name of the type of component. Must always be "LookAndFeel".
markupName | Required. The name for the look & feel. Each look & feel in the portal Web project must have a unique markupName. For best practices, use the same name as the definitionLabel.

When you select a Look and Feel in the WebLogic Workshop Property Editor for a selected desktop, the look & feel XML is automatically added to the underlying XML in the .portal file, as shown in the following section.

## The Portal File

Following is an example portal file, created with the Portal Designer, showing the inserted look & feel XML from the .laf file. The look & feel XML was inserted when the Look and Feel property was set for the selected desktop in the Property Editor (see the first figure in this topic). When the .laf file is inserted into the .portal file, its job is finished in the rendering process and the .portal file is used to set look & feel.

    <?xml version="1.0" encoding="UTF-8"?>
    <portal:root xmlns:html="http://www.w3.org/1999/xhtml-netuix-modified/1.0.0"
        xmlns:netuix="http://www.bea.com/servers/netuix/xsd/controls/netuix/1.0.0"
        xmlns:portal="http://www.bea.com/servers/netuix/xsd/portal/support/1.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.bea.com/servers/netuix/xsd/portal/support/1.0.0 portal-support-1_0_0.xsd">
        <portal:directive.page contentType="text/html;charset=UTF-8"/>
        <netuix:desktop definitionLabel="defaultDesktopLabel" markupName="desktop" markupType="Desktop" title="New Portal Desktop">
            <netuix:lookAndFeel definitionLabel="avitek" description="The avitek look and feel"
                markupName="avitek" markupType="LookAndFeel" skeleton="default"
                skeletonPath="/framework/skeletons/" skin="avitek" skinPath="/framework/skins/" title="avitek"/>
            <netuix:shell description="A header with a link and footer is included in this shell."
                markupName="headerFooterVisitor" markupType="Shell" title="Header-Footer Visitor Shell">
                <netuix:head/>
                <netuix:body>
                    <netuix:header>
                        <netuix:jspContent contentUri="/portlets/header/header.jsp"/>
                    </netuix:header>

                        [XML for books, pages, and portlets...]

                    <netuix:footer>
                        <netuix:jspContent contentUri="/portlets/footer/footer.jsp"/>
                    </netuix:footer>

The portal file is a template with which multiple desktops can be created in the WebLogic Administration Portal. When used as a template, the portal file determines the default look & feel of any desktop created from it.

## Location of the Look & Feel Resources

The look & feel attributes in the portal file tell the portal which skin and skeleton to use to render the portal in HTML. The portal in the previous example will use the following skin and skeleton resources:

Skin | Skeleton
The /css, /images, and /js directories contain the CSS files, framework images (mainly portlet titlebar icons), and JavaScript files that will be used in the skin. The skin.properties file (discussed in the next section) contains references to these resources, and at rendering time those resource references are inserted into the HTML <head> region. You can name your skin resource directories anything you like as long as you reference them correctly in skin.properties (or skin_custom.properties). Skins can also contain subdirectories for sub-skins, or themes (discussed in Look & Feel Overrides). | The skeleton is made up of JSPs that map to and convert each portal component to HTML. The XML elements for the portal components in the .portal file determine the order in which the skeleton JSPs are called and rendered as HTML. This figure shows a clipped view of the skeleton contents. The subdirectories shown are skeleton themes and skeletons used for mobile devices. The JSPs in the root /default directory make up the "default" skeleton. Themes are discussed in Look & Feel Overrides.

### Note About Portlet Titlebar Icons

The icons used in portlet titlebars are stored in the skin's /images directory. The portal framework reads the portal Web project's WEB-INF/netuix-config.xml file to determine which of these graphics to use for the portlet's different states and modes (minimize, maximize, help, edit, and so on).

## The skin.properties File

Each skin has a skin.properties file, which is used by the portal framwork to populate the <head> section of the rendered HTML, among other things. Included in skin.properties are references to the images directory, the CSS files containing the styles to be used in the HTML, and the JavaScript files containing the functions that will be used in the HTML.

Note: You can also create a file called skin_custom.properties in the same directory as skin.properties. Any entries you include in skin_custom.properties are also added to the HTML <head> region. This feature lets you customize the properties without having them overwritten by product updates.

The following will not be rendered:

- Style Sheet styles that do not exist in one of the .css files listed in the <head>.
- JavaScript functions that do not exist in one of the .js files listed in the <head>.

That is why it is important to add references to all skin resources in skin.properties or skin_custom.properties.

The skin.properties or skin_custom.properties files can also contain skeleton path information that is used if skeleton attributes are omitted from the look & feel (.laf) file, as described in The Look & Feel File.

The following table shows an example of how entries in skin.properties for the active skin are converted to HTML <head> entries. Different skins may have different entries.

skin.properties Entries | Rendered HTML <head> Entries
images.path: images | content="/framework/skins/avitek/images"/>
link.body.href: css/body.css link.body.rel: stylesheet link.book.href: css/book.css link.book.rel: stylesheet link.button.href: css/button.css link.button.rel: stylesheet link.fix.href: css/fix.css link.fix.rel: stylesheet link.form.href: css/form.css link.form.rel: stylesheet link.layout.href: css/layout.css link.layout.rel: stylesheet link.portlet.href: css/portlet.css link.portlet.rel: stylesheet link.window.href: css/window.css link.window.rel: stylesheet link.window-plain.href: css/plain/window.css link.window-plain.rel: stylesheet | <link href="/sampleportal/framework/skins/avitek/css/body.css" rel="stylesheet"/> <link href="/sampleportal/framework/skins/avitek/css/book.css" rel="stylesheet"/> <link href="/sampleportal/framework/skins/avitek/css/button.css" rel="stylesheet"/> <link href="/sampleportal/framework/skins/avitek/css/fix.css" rel="stylesheet"/> <link href="/sampleportal/framework/skins/avitek/css/form.css" rel="stylesheet"/> <link href="/sampleportal/framework/skins/avitek/css/layout.css" rel="stylesheet"/> <link href="/sampleportal/framework/skins/avitek/css/portlet.css" rel="stylesheet"/> <link href="/sampleportal/framework/skins/avitek/css/window.css" rel="stylesheet"/> <link href="/sampleportal/framework/skins/avitek/css/plain/window.css" rel="stylesheet"/>
script.skin.src: skin.js script.skin.type: text/javascript script.menu.src: menu.js script.menu.type: text/javascript script.float.src: float.js script.float.type: text/javascript script.menufx.src: menufx.js script.menufx.type: text/javascript script.util.src: util.js script.util.type: text/javascript script.delete.src: delete.js script.delete.type: text/javascript script.search.path: js | <script type="text/javascript" src="/sampleportal/framework/skins/avitek/js/skin.js"></script> <script type="text/javascript" src="/sampleportal/framework/skins/avitek/js/menu.js"></script> <script type="text/javascript" src="/sampleportal/framework/skins/avitek/js/float.js"></script> <script type="text/javascript" src="/sampleportal/framework/skins/avitek/js/menufx.js"></script> <script type="text/javascript" src="/sampleportal/framework/skins/avitek/js/util.js"></script> <script type="text/javascript" src="/sampleportal/framework/skins/avitek/js/delete.js"></script> Provides the directory for the location of the JavaScript files.

You can control the order in which the CSS and JavaScript entries are inserted into the HTML <head> section by adding link.input.index: 1 to a CSS entry and script.util.index: 1 to a script entry, where the number is the order in which the entry should be inserted. All CSS entries are inserted first, followed by all script entries.

## Look & Feel Overrides

You can override the skin elements and skeletons on individual portal components so that those components have a different look & feel than the other portal components. For example, you can override the look & feel of a portlet so that it looks different than the other portlets on a page.

### Overriding Look & Feel with Themes

As part of each skin or skeleton, you can create sub-skins and sub-skeletons called "themes." Themes contain all or part of the resources contained in a skin or skeleton. For example, a skin theme can contain a /css subdirectory with a single CSS file, and a skeleton theme can contain a single JSP to render a portlet titlebar. Themes can be used on books, pages, and portlets.

Each theme requires a .theme file located in <portal_Web_project>/framework/markup/theme/. Following is a sample theme file:

    <?xml version="1.0" encoding="UTF-8"?>
    <netuix:markupDefinition xmlns:netuix="http://www.bea.com/servers/netuix/xsd/controls/netuix/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.bea.com/servers/netuix/xsd/controls/netuix/1.0.0 markup-netuix-1_0_0.xsd">
        <netuix:locale language="en"/>
        <netuix:markup>
            <netuix:theme
                name="alert"
                title="Alert Theme" description="A simple alert theme."
                markupType="Theme" markupName="alert"/>
        </netuix:markup>
    </netuix:markupDefinition>

The theme file contains two key attributes:

- title - The title attribute value is used to populate the Theme drop-down list where it appears in the book, page, and portlet properties in the Portal Designer and in the WebLogic Administration Portal.
- name - The name attribute value tells the portal framework the name of the theme directory to look in to apply theme resources to the book, page, or portlet.

The theme XML is inserted in the .portal around the XML for the book, page, or portlet to which the theme applies.

The following figures show where you set a theme in WebLogic Workshop and in the WebLogic Administration Portal.

WebLogic Workshop | WebLogic Administration Portal

Theme selection for a book, page, or portlet does not depend on the look & feel selected for a desktop. All themes are available for selection for all look & feels, whether or not the skins and skeletons for the look & feels contain the selected theme. If a skin or skeleton does not contain the selected theme, the theme is ignored. If both a skin and a skeleton theme exists for the selected look & feel, both are used.

The following figures show an example theme directory structure for the theme file, a skin theme, and a skeleton theme:

Theme File | Skin Theme | Skeleton Theme

If skin or skeleton resources are not explicity contained in a theme, the parent skin or skeleton resources are used. For example, if a skeleton theme uses only a JSP to render a portlet titlebar, the parent skeleton JSPs are used to render the rest of the portlet.

For skeletons, the ability to use parent resources is dependent on a file in the skeleton theme directory called skeleton.properties,which contains a single entry:

jsp.search.path: ., ..

where ., .. is a relative path to the theme's own skeleton JSPs and to the parent skeleton's JSPs.

In the parent skin, the skin.properties must contain path information to its skin themes in the following format:
theme.alert.search.path: alert/images, images

The name of the theme directory is the second entry in the property. The path to the theme images is set (alert/images), along with the path to the parent skin's images directory (images) in case the theme images are an incomplete subset of the necessary images.

### Overriding Look & Feel with Properties

For any selected component in the Portal Designer, you can override CSS properties and the skeleton JSP used to render the component. With the portal component selected in the Portal Designer, set the property overrides you want in the Property Editor under Presentation Properties, as shown in the following figure.

When the portal desktop is rendered as HTML, the skeleton JSP you selected is used to render the component, and the style overrides you entered are automatically inserted into the XML of the .portal file.

## Summary

The look & feel selected for a portal desktop serves as the basis for how the desktop is rendered in HTML. The look & feel XML file (.laf) points to a specific skin and a specific skeleton on the file system to use for rendering.

Skins are made up of framework images (like portlet titlebar icons), CSS files, and script files, such as JavaScript. Skeletons are JSPs that convert XML-based portal components to HTML.

Once a look & feel is selected, its XML is inserted into the .portal XML file, which is the primary XML file used to control desktop rendering (.portlet XML files are used to render portlets). The look & feel settings point to the file-based skin and skeleton resources that are used to generate and used in the rendered HTML.

The skin used in a look & feel contains a skin.properties and an optional skin_custom.properties file that contains references to all images, CSS files, and script files that are used by the skin. The entries in skin.properties and skin_custom.properties are converted to HTML <head> entries so that any framework images, CSS styles, and script functions used in the HTML are recognized.

You can override the look & feel for any book, page, or portlet by using themes; and using the Portal Designer and Portlet Designer Property Editor you can override CSS styles, attributes, and the skeleton JSP used to render desktops, books, pages, and portlet titlebars and windows.

Related Topics

The Portal User Interface Framework

How the Shell Determines Header and Footer Content

How Portal Components are Rendered

Portal User Interface Framework Reference

Creating Look & Feel Files

Creating Skins and Skin Themes

Creating Skeletons and Skeleton Themes

Creating a Portal File

Properties for All Portal Components (property overrides)

Adding Visitor Tools to Portals

Tutorial: Changing a Portal's Look & Feel and Navigation