Administering SAS Web Application Themes

Steps for Defining and Deploying a New Theme

SAS provides a default theme for your use. You also have the choice of designing and deploying a custom theme for your environment.

To develop and deploy a new theme, follow these steps:

Design the theme. See Step 1: Design the Theme.
Create a work area for the theme. See Step 2: Create a Work Area for the Theme.
Make desired changes to the styles, graphics, and theme templates. See Step 3: Make Desired Changes to the Styles, Graphics, and Theme Templates.
Register the theme in metadata. See Step 4: Rebuild SAS Web Application Themes.
Rebuild SAS Web Application Themes and deploy in your test environment. See Step 5: Deploy SAS Web Application Themes in Your Test Environment.
Test the new theme in a test environment. See Step 6: Test the New Theme.
Move the new theme from test to production environment. See Step 7: Move the New Theme from Test to Production Environment.
Assign the default theme. See Step 8: Assign the Default Theme.

Note: You might choose to perform steps 3 through 6 iteratively, making limited changes to the theme during each iteration, so that you can more readily determine the effects of each set of changes to the theme. To deploy multiple themes in your environment, follow steps 1 to 6 to design and create your themes. Then follow step 7 to move each theme from test to production environment. [cautionend]

You can deploy multiple themes in your corporate environment. Before deploying the new theme in a production environment, you should first test it in a test environment to ensure that SAS Web applications function as expected with the new theme applied.

Step 1: Design the Theme

The first step in creating a custom theme is to plan the visual elements. Usually the new theme is based on an existing design, your organization's intranet standards, another in-house written application, or a purchased application or solution. Some organizations have a standard color palette with color specifications.

Review the specifications for the Default theme at SAS-configuration-directory\Lev1\Web\Utilities\SASThemeExtensions\specs\Default\index.html, and identify the component keys and image keys for the visual elements that you want to change in the new theme. Establish a set of colors that are compatible with your organization, and choose the images (for example, logos, banner images) you want to use in the new theme.

Generally, you can make the largest impact by updating the background colors, border colors, and text attributes for Web application pages and SAS Information Delivery Portal portlets. In addition, you might want to replace the SAS logo in the banner with our own organization's logo. If you select a different color palette, consider that you might need to adjust the colors in images to match the new palette.

The Color Palette page at SAS-configuration-directory\Lev1\Web\Utilities\SASThemeExtensions\specs\Default\html\
colorPalette.html lists all 55 color keys of the default theme and specifies the default hexadecimal color value for each color key. It also provides links to documentation on each user interface element where the color is applied.

Options in Designing the Theme

When you create a new theme, there are three ways to define your theme:

Use the Color Palette and replace the 55 default SAS colors with your organization's palette. The colors are applied automatically across the user interface.
Specify the color to be used for each interface component. You must specify the color for each context key of the user interface component. This approach takes more time, but it provides maximum flexibility and control.
Start with the Color Palette, and make individual changes to selected user interface components. This approach overrides how the color palette is applied in some cases.

If you choose to set colors for the context key of each user interface component, the Web pages at SAS-configuration-directory\Lev1\Web\Utilities\SASThemeExtensions\specs\Default\index.html provide tools and resources to assist you with this process.

Step 2: Create a Work Area for the Theme

To create a work area that contains a copy of the Default theme as a basis for your new theme, use one of the following scripts provided in the SAS-configuration-directory\Lev1\Web\Utilities\SASThemeExtensions directory:

for Windows:
```
NewTheme.bat theme-name true
```
for UNIX:
```
NewTheme.sh theme-name true
```
for z/OS:
```
NewTheme.sh theme-name true
```

Beginning with the third maintenance release for SAS 9.2, the NewTheme.sh script is available for z/OS.

To use the Color Palette option, the true parameter is required in the command.

Note: The theme name must not contain spaces. [cautionend]

The following figure shows the theme-name directory, which is the root directory for theme resources. The \theme-name\MetadataTools directory contains SAS programs for managing the theme. The Velocity directory contains several subdirectories with files.

Subdirectories within SASThemeExtensions Directory

[Subdirectories within SASThemeExtensions Directory]

The following figure shows the subdirectory structure that is created under the SAS-configuration-directory\Lev1\Web\Utilities\SASThemeExtensions\themes\theme-name\themes\theme-name directory.

Subdirectories for Images, Styles, and Templates

[Subdirectories for Images, Styles, and Templates]

Here is an explanation of the folders and their contents:

\theme-name\themes\theme-name\images

contains the standard collection of images for SAS Web applications that use the theme infrastructure. The images are divided into the following subdirectories by category:

Common	contains images that are commonly used in SAS Web applications.
Components	contains images for the collection of components (widgets) that are shared by SAS Web applications.
WRS	contains images for SAS Web Report Studio.

\theme-name\themes\theme-name\styles

contains a cascading style sheet file named custom.css that can be used to define additional style elements for the theme. This file is empty when the work area is created.

\theme-name\themes\theme-name\templates

contains theme templates, which are HTML fragments that render specific portions of pages in SAS Web applications. The template files are divided into the following subdirectories by category:

Common	contains theme templates for page elements that are commonly used in SAS Web applications.
Components	contains theme templates for the collection of components that are shared by SAS Web applications.
WRS	contains theme templates for elements in SAS Web Report Studio pages.

The following figure shows the subdirectories below the SAS-configuration-directory\Lev1\Web\Utilities\SASThemeExtensions\themes\theme-name\Velocity directory.

Subdirectories within the Velocity Directory

[Subdirectories within the Velocity Directory]

Here is an explanation of the contents of the directories:

\theme-name\Velocity\Stylesheets\_shared\contexts\themes: contains a context file named theme-name.vctxt that defines context values for font families and standard colors that can be used in CSS templates.
\theme-name\Velocity\Stylesheets\Common\contexts\themes\theme-name: contains CSS template files that are used to build style sheets for page elements that are commonly used in SAS Web applications, including portal.theme-name.vtl, sasStyle.theme-name.vtl, and sasScorecard.theme-name.vtl.
\theme-name\Velocity\Stylesheets\Components\contexts\themes\theme-name: contains a CSS template file named components.theme-name.vtl that is used to build style sheets for the collection of components that are shared by SAS Web applications.
\theme-name\Velocity\Stylesheets\WRS\contexts\themes\theme-name: contains a CSS template file named wrs.theme-name.vtl that is used to build style sheets for SAS Web Report Studio.
\theme-name\Velocity\ThemeDescriptors\contexts: contains a context file named theme-name.themeDescriptor.vctxt that defines context values that can be used in theme descriptor templates.
\theme-name\Velocity\ThemeDescriptors\contexts\custom\theme-name: contains theme descriptor template files for building the XML files that define the available collections of style sheets, theme templates, and images, including ComponentsThemes.vtl, CustomThemes.vtl, SASThemes.vtl, SolutionsThemes.vtl, and WRSThemes.vtl.

If you were to build the new theme at this point, it would be a fully functional duplicate of the Default theme.

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

Changing Colors

To make style changes to specific page features, you must first identify the component key associated with that feature and then locate the CSS template file that sets the value for that key. For example, suppose your new theme design calls for changing the color for the title text in the banner at the top of SAS Web applications. The Banner specifications at the Themes Web site SAS-configuration-directory\Lev1\Web\Utilities\SASThemeExtensions\specs\Default\Components\

html\Banner.html show that the context key for the title text is Banner_Title_Text_Color and it displays its context value.

Each Themes Web page displays the context keys and context values.

You can specify a new color explicitly, as follows:

   Banner_Title_Text_Color=#e69b00

Because components.theme-name.vtl is a CSS template file, another option is to use the generic color values that are defined in the theme-name.vctxt file in the \Velocity\Stylesheets\_shared\contexts\themes subdirectory of the work area for the new theme. For example, you might specify the following value instead of an explicit value:

   Banner_Title_Text_Color=${Color53}

The corresponding color value is substituted in the resulting CSS when the new theme is built.

The general form for using a context value in a template file is ${context-value-name}. Using context values instead of explicit values can make it easier to maintain the theme because you can change all component keys that use a given value by making one change to the context file.

Changing Graphics

Image files are located in three subdirectories located in the SAS-configuration-directory\Lev1\Web\Utilities\SASThemeExtensions\specs\Default folder. These subfolders are: Common, Components, and WRS. The properties of each image are defined in the Theme Descriptors files.

The process for customizing images is similar to that for customizing styles. For example, suppose your new theme design calls for changing the background image for the banner at the top of SAS Web applications. A review of the Banner specifications at SAS-configuration-directory\Lev1\Web\Utilities\SASThemeExtensions\specs\Default\index.html shows that the image key for the banner background is banner_background. A search for that string in the work area for the new theme shows the following IMAGE element in the components.theme-name.vtl file in the Velocity\ThemeDescriptors\custom\theme-name subdirectory of the work area:

<Image name="banner_background" ...  file="BannerBackground.gif"/>

You can change the image used for the banner background image in either of the following ways:

by replacing the existing BannerBackground.gif file in the themes\theme-name\images\Components subdirectory of the work area with a revised image with the same name. Make sure that the new image has the following criteria:
- The filename of the new graphic is identical to the filename of the graphic being replaced.
- The new graphic is in the same format as the original image (for example, .jpg or .gif).
- The dimensions of the new graphic and its pixels are same as the graphic being replaced.
If you need to change the size, filename, or the image format of the graphic, modify the theme descriptor. For example, if you replace the logo.gif file with a new file called myLogo.jpg that has a width of 300 pixels and height of 70 pixels, modify the ComponentsThemes.vtl file as follows:
```
<Image name="logo" description="My Logo" altTextKey="desktop.logo.text"
appliesTo="ALL" width="300" height="70" file="myLogo.jpg"/>
```
by changing the FILE= attribute in the IMAGE element in the components.theme-name.vtl context file to point to a different image file.

Note: You should not change the value of the NAME= attribute in the IMAGE element. SAS Web applications depend on the NAME= attributes remaining constant.

Another common image change is to replace the SAS logo in the standard banner with your organization's logo. You can change the graphic used for the banner logo either by replacing the existing logo.gif file in the themes\theme-name\images\Components subdirectory of the work area with a copy of your logo with that filename or by changing the target of the FILE= attribute for the IMAGE element in the components.theme-name.vtl context file for which the NAME= attribute has the value logo.

When customizing images, you should ensure that the replacement graphics have approximately the same dimensions as the original graphics. Otherwise, the images might disrupt the appearance of the applications in which they are used.

Changing Theme Templates

You should make changes to theme templates only in situations where you want to change the layout of a page element (for example, to tweak the logo's placement in the banner or to adjust the padding between rows in a menu). If you decide to alter a theme template, proceed with caution. SAS Web applications rely on the template structure being consistent with the versions that are shipped with the software. Improper changes to theme templates might prevent SAS Web applications from functioning properly. In particular, do not change the dynamic substitution variables in theme templates because SAS Web applications expect the existing values.

Dynamic substitution variables should not be changed in theme templates because SAS Web applications expect the existing values. However, if you need to change a dynamic substitution variable, here is an example where %BANNER_TITLE is the dynamic substitution variable:

<td nowrap id="bantitle" class="banner_title">%BANNER_TITLE</td>

Note: When a new release of themes is installed at your site or an upgrade is performed, the existing theme template files are replaced by the new theme template files. If you have customized theme template files and want to retain them for future use, copy them to a different location before the installation or upgrade. [cautionend]

Additional Considerations

Another change that you might want to make when creating your new theme is to update the theme_displayName= element in the theme-name.themeDescriptor.vctxt file in the Velocity\ThemeDescriptors\context subdirectory of the work area. Provide a descriptive name for the new theme that will appear in the selection list of available themes in the Preferences page in SAS Web applications.

Step 4: Rebuild SAS Web Application Themes

To rebuild the EAR file for SAS Web Application Themes and register your themes in metadata, follow these steps:

Make sure that the SAS Metadata Server is running.
Access the SAS Deployment Manager.

On Windows, use the shortcut on the Start menu or run the config.exe file in the SAS-installation-directory\SASDeploymentManager\9.2 directory.

On UNIX, run the config.sh file.

On z/OS, run the config.rexx file.
Select the Rebuild Web Applications option and click Next.
In the Select Configuration Directory\Level dialog box, specify the configuration directory and the level (for example, Lev1) in which you want to rebuild the applications.
In the Select Configuration Information dialog box, enter the user ID and password for an unrestricted administrative user (for example, sasadm@saspw).
In the Select Web Applications to Rebuild dialog box, select the SAS Themes check box.
In the Summary dialog box, click Start to start the rebuild.
When the rebuild is complete, click Finish to close the SAS Deployment Manager.

The rebuilt SAS Web Application Themes archive file (sas.themes.ear) can be found in the SAS-configuration-directory\Lev1\Web\Staging directory. It should now contain a new Web archive (WAR) file for the new theme named sas.theme.theme-name.war.

Step 5: Deploy SAS Web Application Themes in Your Test Environment

To deploy the rebuilt SAS Web Application Themes to your Web application server in a test environment, see Redeploying the SAS Web Applications.

If you chose to configure your Web application server manually or deployed the SAS Web applications manually when you installed SAS 9.2, see your Instructions.html generated by the SAS Deployment Wizard.

If you chose to have the SAS Deployment Wizard configure your Web application server and deploy the SAS Web applications automatically, see the manual instructions for your Web application server on the SAS third-party Web site at http://support.sas.com/resources/thirdpartysupport/v92.

Step 6: Test the New Theme

After you have completed the deployment procedures, follow these steps to test the new theme:

Navigate to the portal in the production environment.
Log on and select Options Preferences. The new theme should appear as a selection on the Preferences page.
Select the new theme and observe the effect of the changes that you made in Step 3: Make Desired Changes to the Styles, Graphics, and Theme Templates. To view the new theme, log off from the portal. Then log in to the portal to view the new theme that was applied.
Repeat the procedures outlined in Steps for Defining and Deploying a New Theme until you are satisfied with the display of the new theme.

If you test the new theme several times, log out of the portal and log on again to view the updated theme each time.

Step 7: Move the New Theme from Test to Production Environment

To move a theme from a test to a production environment, follow these steps:

Copy the entire contents of the SAS-configuration-directory\Lev1\Web\Utilities\SASThemeExtensions directory to the same directory path on the production machine.
Run SAS Deployment Manager, and use the Rebuild Web Applications option to register the theme in the metadata. See Step 4: Rebuild SAS Web Application Themes.
Rebuild SAS Web Application Themes and deploy to your Web Application Server. See Step 5: Deploy SAS Web Application Themes in Your Test Environment.
Assign the new theme as the default theme. See Step 8: Assign the Default Theme.

Step 8: Assign the Default Theme

If you want your new or custom theme to be the default theme for all users who have not selected a theme for themselves in their application's Preferences, then you should set the new theme as the default.

There are two ways to modify the theme metadata:

Use SAS Management Console. See Assign the Default Theme from SAS Management Console.
Use the UpdateDefaultTheme.sas program. See Assign the Default Theme with the UpdateDefaultTheme.sas Program.

Assign the Default Theme from SAS Management Console

To assign a new theme as the default theme by using the SAS Management Console, follow these steps:

Deploy the new EAR file by using the appropriate procedures for your Web application server.
In SAS Management Console, on the Plug-ins tab, navigate to Application Management Configuration Manager SAS Application Infrastructure and right-click to display the SAS Application Infrastructure Properties dialog box.
Click the Settings tab.
In the Default Theme field, enter the name of your theme.
Click OK to exit the SAS Application Infrastructure Properties window.
To enable the new theme to go into effect, restart SAS Remote Services and the Web Infrastructure Platform in the Web application server.

Assign the Default Theme with the UpdateDefaultTheme.sas Program

To assign a theme as the default theme, use the UpdateDefaultTheme.sas program located in the SAS-configuration-directory\Lev1\Web\Utilities\SASThemeExtensions\themes\theme-nameMetadataTools directory. After the UpdateDefaultTheme.sas program has been run, the new theme will be in effect for users who have not selected a different theme on their Preferences page.

If SAS 9.2 is not installed on the middle tier, copy the UpdateDefaultTheme.sas program to the metadata server, and submit the SAS program on that system.

Top of Page