Migrating Custom Themes

Overview

To apply a custom theme that you developed for an earlier release to SAS 9.3 Web applications, follow these steps:

Create a new theme structure. For information about creating a work area in which to construct the new version of your existing theme, see Step 2: Create a Work Area for the Theme.
Migrate the cascading style sheets used in your theme.
Migrate the images used in your theme.
Migrate the theme templates.
Migrate the descriptors used in your theme.

Migrating Cascading Style Sheets

Before attempting to move any CSS files from an existing theme to the \themes\theme-name\styles subdirectory of the work area for the new theme, you should first review the specifications for the Default theme at SAS-config-dir\Lev1\Web\Utilities\SASThemeExtensions\specs\Default\index.html. For any feature for which a component key has been defined, you should update the corresponding component key values in the CSS template (.vtl) files in the \Velocity\Stylesheets\Common\contexts\themes\theme-name, \Velocity\Stylesheets\Components\contexts\themes\theme-name, and \Velocity\Stylesheets\WRS\contexts\themes\theme-name subdirectories of the work area to achieve a compatible look and feel.

Custom style sheet files are required only if you need to provide theme support to features that are not covered by the CSS templates. For each style sheet file that you add, you must ensure that a corresponding STYLESHEET element is added to in the appropriate theme descriptor template (.vtl) file in the \Velocity\ThemeDescriptors\contexts\custom\theme-name subdirectory of the work area for the new theme. The STYLESHEET element must specify the value all for its PRODUCT= attribute.

Migrating Images

Before attempting to move any image files from an existing theme to the \themes\theme-name\images subdirectory of the work area for the new theme, see the image specifications for the Default theme at SAS-config-dir\Lev1\Web\Utilities\SASThemeExtensions\specs\Default\index.html. If the image from the existing theme replaces one of the images in the new theme, then you should ensure that the image from the existing theme is saved over the default image in the proper directory under the \themes\theme-name\images subdirectory. If the image from the existing theme does not replace an image in new theme, save it in the \themes\theme-name\images\Common subdirectory.

For each image file that you update or add, you must ensure that a corresponding IMAGE element is present in the appropriate theme descriptor template (.vtl) file in the \Velocity\ThemeDescriptors\contexts\custom\theme-name subdirectory of the work area for the new theme.

Migrating Theme Templates

Before attempting to move any theme template files from an existing theme to the \themes\theme-name\templates subdirectory of the work area for the new theme, you should consider carefully whether they are compatible with the SAS Web applications. SAS Web applications rely on the theme template structure being consistent with the versions that are shipped with the software. Theme templates must have the expected set of dynamic substitution variables in order for the applications to function properly.

Migrating Theme Descriptors

The theme descriptor template (.vtl) files in the \Velocity\ThemeDescriptors\contexts\custom\theme-name subdirectory of the work area for the new theme should represent the structure of the migrated theme resources. Review the files to ensure the following:

If you add cascading style sheet files to provide theme support for features that are not covered by CSS templates, ensure that you add corresponding new STYLESHEET elements to the STYLES section.
For each image file that you update or add, ensure that you update or add a corresponding IMAGE element in the IMAGES sections.
If you migrate existing theme template files, ensure that you update or add a corresponding TEMPLATE element in the TEMPLATES sections to reflect the change.

Special Considerations for SAS Logon Manager

Changes in the Second Maintenance Release for SAS 9.3

In the second maintenance release for SAS 9.3, the SAS Logon Manager Web application uses two different designs: "logon classic" and "logon corporate." The classic design is used with SAS Web applications that use mostly HTML and JSP. The corporate design is used with SAS Web applications that use mostly Adobe Flash technology.

The corporate design uses a different directory for images and a template file than the classic design. When you migrate your custom themes, review whether your custom images or template changes should also be added to the following images and themes.

Migrating the Logon Logo Image

To migrate a custom logo image for the logon page:

Change the context file to point to a new logo image.
1. Edit SAS-config-dir\Lev1\Web\Utilities\SASThemeExtensions\theme-name\Velocity\ThemeDescriptors\custom\theme-name\SemanticThemes.vtl
2. Change the following line to specify to a different image path.
  
  <Image name="logo_png" file="semantic/logo.png" description="SAS: The Power to Know" altTextKey="image.sas.logo.txt" />
  
  If you want to use your existing customer logo.gif, then change the entry to resemble the following example:
  <Image name="logo_png" file="logo.gif" description="your-description-here" altTextKey="image.sas.logo.txt" />
  
  Tip
  You can change or remove the description attribute. It is used as a tooltip for the logo image.

Add styles to your theme's SAS-config-dir\Lev1\Web\Utilities\SASThemeExtensions\theme-name\themes\theme-name\styles\custom.css file. Adjust some of the values in the following example, depending on the dimensions of your logo image and the desired appearance.

 .figure1 img {
    width: your-image-widthpx;
    height: your-image-heightpx;
}

.figure1 {
    width: 100%;
    min-width: your-image-widthpx;
    max-width: your-image-widthpx;
}

.logonabout {
    margin-bottom: 0em;
}

.banner .clearfix {
    display: none;
}

.logonhd {
    height: 5.0em;
}

.logonhd h1 {
    padding-top: 1em;
}

Logon Banner Background Image

To migrate your logon banner background image:

Create a new image and copy it to a new location.
1. Create a new PNG version of your custom image at SAS-config-dir\Lev1\Web\Utilities\SASThemeExtensions\theme-name\themes\theme-name\images\Components\BannerBackground.gif and name it BannerBackground.png. You can use an application like Microsoft Paint to do this.
2. The dimensions of BannerBackground.png are 781x145 pixels. The dimensions of BannerBackground.gif are 1063x479 pixels. You might need to resize your new image to match the size of BannerBackground.png. Again, you can use an application like Microsoft Paint to make the change.
3. Copy BannerBackground.png to SAS-config-dir\Lev1\Web\Utilities\SASThemeExtensions\theme-name\themes\theme-name\images\semantic\.
If you want your BannerBackground.png image to repeat, then add a style override to the SAS-config-dir\Lev1\Web\Utilities\SASThemeExtensions\theme-name\themes\theme-name\styles\custom.css file:
```
.banner {
    background: url("../images/semantic/BannerBackground.png") 
    repeat-x scroll left top transparent;
}
```
Tip
As an alternative to step 1, you can change the URL value to specify a different image, if you prefer.

Note: The corporate design shares the .banner style with the classic design. If you include the preceding .banner style in your custom.css file, then the BannerBackground.png appears in the corporate design—which might be undesirable. You can either create a BannerBackground.png image that works well for both the classic and corporate designs, or you can eliminate BannerBackground.png by adding the following style to your custom.css file:
```
.banner {
    background: none;
}
```

Logon Banner Background Color

This setting applies to the classic design only. If you want to change the banner background color that is to the right of the banner background image, edit

SAS-config-dir\Lev1\Web\Utilities\SASThemeExtensions\theme-name\Velocity\Stylesheets\Common\contexts\themes\theme-name\logon.theme-name.vtl

. Change the Logon_Classic_Banner_Background_Color value.

LogonArtTile.gif File

This file is not used in the new logon page for the classic or corporate designs. You do not need to migrate it.

LogonArtTop.gif File

To migrate your custom LogonArtTop.gif file:

Copy your custom LogonArtTop.gif from SAS-config-dir\Lev1\Web\Utilities\SASThemeExtensions\theme-name\images\Common\ to SAS-config-dir\Lev1\Web\Utilities\SASThemeExtensions\theme-name\images\semantic\.
If you want this image to repeat down the page from top to bottom, edit the custom.css file and add a repeat-y attribute as shown in the following example:
```
.content {
    background: url("../images/semantic/LogonArtTop.gif") 
    repeat-y scroll 0 5em transparent;
}
```
Tip
As an alternative to step 1, you can change the URL value to specify a different image, if you prefer.

Note: Similar to the .banner style, the .content style is used by both the classic and corporate designs. One setting might not look attractive on both designs. If you want to eliminate the graphic from the designs, you can set it to none (background: none;).

Colors for the Classic Design

To customize the color for the About link that appears in the banner for the classic design:

Edit SAS-config-dir\Lev1\Web\Utilities\SASThemeExtensions\theme-name\Velocity\Stylesheets\Common\contexts\themes\theme-name\logon.theme-name.vtl.
Change the Logon_Classic_About_Link_Color value to a color that works well with your custom theme's Banner_UtilityBar_Background_Color value in SAS-config-dir\Lev1\Web\Utilities\SASThemeExtensions\theme-name\Velocity\Stylesheets\Common\contexts\themes\theme-name\components.theme-name.vtl.
Change the additional About colors as needed. These are Logon_Classic_About_Link_Focus_Color and Logon_Classic_About_Link_Hover_Background_Color.
Adjust other Logon_Classic* colors in the logon.theme-name.vtl, as needed.

Colors for the Corporate Design

To customize the colors for the corporate design:

Edit SAS-config-dir\Lev1\Web\Utilities\SASThemeExtensions\theme-name\Velocity\Stylesheets\Common\contexts\themes\theme-name\logon.theme-name.vtl.

This file is used by the classic and corporate designs. The rest of the instructions apply to modifying the corporate-related design colors.
Change the page body color:
1. Change Logon_Corporate_Body_Background_Color to one in your theme’s color palette or set to white (#FFFFFF) to match the classic design.
2. Set Logon_Corporate_Body_Background_Gradient_Start_Color and Logon_Corporate_Body_Background_Gradient_End_Color to the same color as Logon_Corporate_Body_Background_Color.
Change the page text color by setting Logon_Corporate_Page_Text_Color to one in your theme’s color palette or set to black (#000000) to match the classic design.
Change the About link colors:
1. Change the Logon_Corporate_About_Link_Color value to a color that works well with your custom theme's color palette.
2. Change additional About colors as needed. These are Logon_Corporate_About_Link_Focus_Color and Logon_Corporate_About_Link_Hover_Background_Color.
Adjust other Logon_Corporate* colors in the logon.theme-name.vtl, as needed.

Additional Changes for the Corporate Design

If you are migrating the corporate design, edit the SAS-config-dir\Lev1\Web\Utilities\SASThemeExtensions\theme-name\themes\theme-name\styles\custom.css file and add the following styles:

body {
    filter: none;
    -ms-filter: none;
}
#page {
    /* 
     * The following is required to override background image. It does not
     * inherit the color key value. 
     */
    background: insert-Logon_Corporate_Body_Background_Color-value;
}
.logonabout a:link {
    text-shadow: none;
}
.logonabout a:hover {
    background: none;
}
.logonhd h1 {
    text-shadow: none;
}
.message {
    background: none;
    filter: none;
}
.message h2 {
    text-shadow: none;
}
.message.info {
    text-shadow: none;
}
.message.error {
    text-shadow: none;
}
.message.warning {
    text-shadow: none;
}
.main {
    background: none;
    -moz-border-radius: 0px;
    -webkit-border-radius: 0px;
    -khtml-border-radius: 0px;
    border-radius: 0px;
}

Rebuild SAS Themes

After previous changes are made to migrate your custom theme, run SAS Deployment Manager to rebuild the SAS Themes application. When this is complete, redeploy SAS Themes to your application server and restart the application server.