Steps for Defining a New Theme

To develop a new theme, you should use the following recommended approach:

• Instead of creating a new theme from scratch, use the SAS Winter theme as a starting point. (The SAS Winter theme is easier to modify than the SAS Default theme.)

• Use a nonproduction environment to make your changes and test them. For example, you can use a single-machine portal installation on your desktop, or you can use a portal installation that is reserved for development activities.

• Place all of your style changes in a separate style sheet that will supercede the SAS style sheets. (Note: There is one exception to this approach. To customize the page that displays information maps, you must modify the styles directly in sasComponentsTheme.css.)

• Make changes on an incremental basis, viewing the results of each change in an active portal session before you make the next change.

• If you make changes to a template file, you must restart the portal Web application.

Here are the detailed steps for this process:

1. Create a directory, and extract files from SASTheme_winter.war.

2. Assign a theme name and create a new, empty style sheet.

3. Deploy the renamed theme in a nonproduction environment.

4. Make desired changes to the styles, graphics, and theme templates.

5. Add a background image to the banner (optional).

6. Update the theme descriptors.

7. Deploy the new theme in the production environment.

Step 1: Create a Directory, and Extract Files from SASTheme_winter.war

It is recommended that you use the SAS Winter theme as the basis for creating your new theme. You should begin by creating a directory that contains a copy of the SAS Winter theme, as follows:

1. Create a directory for your new theme. In naming the directory, follow these guidelines:

   • The directory name must not contain spaces.

   • To distinguish your custom theme from themes that are provided by SAS, it is recommended that you not use the character string "SASTheme" in the directory name.

   Note: This directory name is not the theme name. The theme name is assigned in Step 2.

2. The SAS Web Infrastructure Kit includes an archive named SASTheme_winter.war which contains all of the elements that make up the SAS Winter theme. You can find this archive either in the portal Web application's directory structure on the Web server, or in the SAS Web Infrastructure Kit's original installation location. For example, if you installed the product in the default location on a Windows system, then the SASTheme_winter.war file would be located in the following path:

   c:\Program Files\SAS\Web\Portal2.0.1

   Extract the contents of SASTheme_winter.war to the directory that you created in Step 1.a. The following directory structure is created:

   Directory	Contents
   /themes	This directory contains the following theme descriptors: SASthemes.xml SolutionsThemes.xml You will need to update the theme descriptors with the name of your new theme, as described in Step 2. You may need to make other changes, as described in Step 6.
   /themes/winter	You will need to rename this directory, as described in Step 2. This directory does not contain any files.
   /themes/winter/images	This directory contains the theme's images. The images can be modified as described in Step 4.
   /themes/winter/styles	This directory contains the following Cascading Style Sheets: Portal.css sasStyle.css sasComponents.css sasComponentsLayout.css sasComponentsTheme.css sasScorecard.css You will be creating an additional style sheet in this directory, as described in Step 2.
   /themes/winter/templates	This directory contains HTML document templates. The templates can be modified as described in Step 4.
   /WEB-INF	This directory contains the file web.xml, which is the Web application deployment descriptor for the theme. Some Web servers require this directory and file to be present.

Step 2: Assign a Theme Name and Create a New, Empty Style Sheet

In this step, you will assign a name to your theme, create a new (empty) style sheet for your theme, and make corresponding updates to the theme descriptors. Follow these steps:

1. Rename the winter directory (located under the themes directory) to the name for your new theme. The name cannot contain spaces.

2. Open SASthemes.xml in a text editor, and edit the theme element as follows:

   name

   Replace winter with the unique name for your theme. The name must match the directory name that you assigned in Step 2.a.

   label

   Replace SAS Winter with a descriptive label for your theme. When users choose Preferences on the Options menu, this label will appear as a selection in the Theme field.

   Note: The current version of the Web Infrastructure Kit does not support localization of the theme label.

   description

   Replace winter theme for SAS applications with a free-form description.

   URIPath

   In the path themes/winter, replace winter with the name of the directory in which the new theme is to be deployed. The directory name must be the same as the theme name, as defined in the name attribute.

3. Repeat Step 2.b for every theme descriptor (XML) file.

4. Use a style sheet editor or text editor to create a new cascading style sheet. For best results, do not enter any classes into the file in this step. Instead, you may want to enter some comment lines to describe the purpose of the file.

   Using a file name of your choice and the filename extension .css, save the style sheet in the styles subdirectory of your new theme.

5. Open SASthemes.xml in a text editor. In the Styles element, create a new StyleSheet subelement as follows:

   name

   Enter a unique name for your new style sheet.

   description

   Enter a free-form description of your style sheet.

   order

   Enter a number to indicate the order in which this style sheet is to be loaded. To ensure that your class definitions will supercede all other class definitions, specify a number that is higher than those specified for the other style sheets.

   media

   Specify screen, which is the display media to which your style sheet applies.

   file

   Specify the file name that you assigned when you saved your style sheet in Step 2d.

Note: It is important to update the theme element in every theme descriptor (XML) file, as described in Step 2.c. However, the StyleSheet element needs to be added only to the SASthemes.xml file.

Step 3: Deploy the Renamed Theme in a Nonproduction Environment

Deploy the copied, renamed theme to a nonproduction installation of the portal. For example, deploy it to a single-machine portal installation on your desktop, or deploy it to a portal installation that is reserved for development activities. For instructions, see Theme Deployment in the "Customizing the Portal's Display" chapter in the SAS Intelligence Platform: Web Application Administration Guide.

After you have completed the deployment procedure, do the following:

1. Bring up the nonproduction portal.

2. Log on, and select Preferences on the Options menu. The new theme should appear as a selection on the Preferences page.

3. Select the new theme so that you will be able to observe the effect of the changes that you will make in Step 4.

Step 4: Make Desired Changes to the Styles, Graphics, and Theme Templates

First, determine which visual elements you want to change in the new theme. Generally, you can make the largest impact by updating the style classes that control the background colors, border colors, and text attributes for portal pages and portlets. In addition, you might want to replace the SAS logo with our own organization's logo.

Changes to the theme templates are needed only if you want to change the layout of the portal's elements (for example, the logo's placement in the banner or the padding between rows in a menu).

To determine which specific styles, graphics, and templates to change, refer to the following topics:

• Style Sheet and Graphics Reference
• Theme Template Reference

Then make the desired changes to the appropriate components. Follow these guidelines:

• Put all of your style changes in the new style sheet that you created in Step 2. Using a style sheet editor, locate the appropriate style in the SAS style sheets. Then copy and paste the class definition to your new style sheet and make the desired changes.

  Note: There is one exception to this approach. To customize the page that displays information maps, you must modify the styles directly in sasComponentsTheme.css.

• Use an incremental approach to making changes. For example, add one or two style classes to your style sheet and modify the colors. Then save the style sheet, and refresh the portal image to view the results of the change. Repeat these steps for each additional change.

• In the template files, do not change the substitution variables, since these are required by the portal Web application.

• If you assign new names to any of the template files, you must update the theme descriptor files to specify the new file names, as described in Step 6.

• You might want to assign new names to any graphics files that you have changed. However, you must update the theme descriptor files with the new names, as described in Step 6.

• To debug the theme, you can insert comments into the theme template HTML files, and then use the source viewer in your browser to determine where each template is surfaced. In addition, you can use the source viewer in your browser to locate the style class names that affect specific portions of the display.

Step 5: Add a Background Image to the Banner (Optional)

The banner for the Winter theme does not include a background image. However, you can add a background image to the banner by following these steps:

1. Place your background image in the images subdirectory.

2. In the theme descriptor files, locate the image element for banner_background, and specify the name of your image file in the file attribute. Do not modify the name attribute.

3. In your custom style sheet, assign the attribute background-color: transparent to the following style classes: .primaryMenuRow, table.linkbar, td#banbullet, td#banlogo, div#banner, and div#banner td#bantitle.

   If you want the top section of banner (which contains the banner links) to be shaded, assign the appropriate opacity level to the div.transbar class. Otherwise, assign the attribute background-color: transparent to this class.

   Here is an example of the entries that you might make to your custom style sheet:

   .primaryMenuRow {background-color: transparent;}
table.linkbar {background-color: transparent;}
td#banbullet {background-color: transparent;}
td#banlogo {background-color: transparent;}
div#banner {background-color: transparent;}
div#banner td#bantitle {background-color: transparent;}
div.transbar {filter:alpha(opacity=25); -moz-opacity:.25;}

4. In the file banner.html (located in the templates subdirectory), locate the following text:

   <div id="banner" class="primaryMenuRow">

   Replace this text with the following text:

   <div id="banner" style='background-image: url("%BANNER_BACKGROUND")'>

Step 6: Update the Theme Descriptors

A theme descriptor is an XML file that describes the elements of a theme. The default theme has two theme descriptors:

• SASthemes.xml specifies the image files, the page templates, and style sheets for the portal Web application.

• SolutionsThemes.xml specifies image files, page templates, and style sheets for SAS solutions applications that run in the portal.

Use these steps to update the theme descriptors. For more information about the elements and attributes, see the Element Descriptions and the comments at the top of SASthemes.xml.

1. In the Image elements of the appropriate descriptor file(s), update the file attribute to reflect any new names that you have assigned to graphics files. If you changed the size of an image, you must also update the width and height attributes. (Note: Do not change the name attributes, since the portal Web application uses these names to determine which graphics to display. For example, the name attribute for the logo image must retain the value logo. However, you can change the file attribute from logo.gif to MyCompanyLogo.gif.)

2. In the Template elements of the appropriate descriptor file(s), update the file attribute to reflect any new names that you have assigned to template files.

3. Make any other necessary changes to the descriptor files. For example, if you change the directory name images or styles, then you must change the directory attribute in the Styles or Images elements. However, it is not advisable to change these directory names.

4. Save the updated files.

Step 7: Deploy the New Theme in the Production Environment

Use the following steps to deploy the new theme so that it will be available to the portal Web application and to other applications running in the portal:

Note: It is recommended that you test your new theme in a nonproduction environment before deploying it into a production environment.

1. Compress the theme's directories and files into a WAR file. When creating the file, follow these guidelines:

   • Be sure to include the WEB-INF directory and the web.xml file that it contains, because some Web servers require this directory and file to be present.

   • Give the WAR file a name that does not contain spaces. To distinguish your custom theme from themes that are provided by SAS, it is recommended that you not use the character string "SASTheme" in the name.

     Note: Instead of creating a new WAR file, you can place the directory that contains the new theme directly into the servlet container.

2. Deploy the new WAR file by using the appropriate procedures for your servlet container.

3. Have the administrator use the program LoadThemeConnection.sas to update your metadata repository with information about the new theme. For instructions, see Theme Deployment in the "Customizing the Portal's Display" chapter in the SAS Intelligence Platform: Web Application Administration Guide. After LoadThemeConnection.sas has been run, users will see the new theme as a selection on the Preferences page in the portal Web application.

4. The administrator can use the program UpdateDefaultTheme.sas to specify the new theme as the default theme. For details, see Changing the Default Theme in the "Customizing the Portal's Display" chapter in the SAS Intelligence Platform: Web Application Administration Guide.

   After UpdateDefaultTheme.sas has been run, the new theme will be in effect for users who have not selected a different theme on the Preferences page.

Note: If you need to delete a custom-developed theme from the deployment for the portal Web application, then you can use the program DeleteThemeConnection.sas. For details, see Deleting Custom-Developed Themes in the "Customizing the Portal's Display" chapter in the SAS Intelligence Platform: Web Application Administration Guide.