Steps for Defining and Deploying a New 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-config-dir\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-config-dir\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.

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

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

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-config-dir\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.

Image files are located in three subdirectories located in the SAS-config-dir\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-config-dir\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 ComponentsThemes.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:

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 ComponentsThemes.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.

You should make changes to theme templates only in situations where you want to change the layout of a page element (for example, to change 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>

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\contexts subdirectory of the work area. Provide a descriptive name for the new theme. The name is used in the selection list of available themes in the Preferences page in SAS Web applications.

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:

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

To assign a theme as the default theme, use the UpdateDefaultTheme.sas program located in the SAS-config-dir\Lev1\Web\Utilities\SASThemeExtensions\themes\theme-name\MetadataTools 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 is not installed on the middle tier machine, copy the UpdateDefaultTheme.sas program to the metadata server, and submit the SAS program on that machine.