Skip to main content
Blackboard Help

Custom Theme Enhancements

With Service Pack 14, the existing tools for downloading, uploading and customizing a system theme include all style sheets for all features, regardless of whether the feature resides in the Learn core or in a building block delivered by Blackboard. Building blocks delivered by third-party vendors of building blocks can participate in this capability, but may need to revise their building block to conform to the file naming conventions for style sheet files required by the feature.

Restructured Package Themes

In order to successfully include all style sheets that are in building block “payloads” in Learn, the theme packages were restructured to distinguish core style sheets from style sheets that are specific to building blocks. This change directly mirrors the existing behavior of the Learn Language Pack Editor, which handles translated resources from both core Learn and from building blocks.

Theme packages downloaded from Learn now include a ‘core’ subdirectory, as well as subdirectories for each building block that contains its own tool-specific style sheets. Not all building blocks have such style sheets. A text file is also included at the top level of the theme package that provides a list of subdirectory names and the corresponding natural language building block name, to assist in locating the proper files during customization work.

The theme tool introspects the contents of all building blocks on the system, regardless of whether the building block is inactive, unavailable, or available. The way it determines if the building block has custom style sheets is by looking for files with a .css extension stored in a subdirectory of the css directory at the top level of the building block’s webapp source tree that matches the ID of the theme. Files found in these locations are included in the downloaded theme package

For example, in the Discussions building block, if the following files exist:

#1: plugins/Bb-discussionboard/webapp/css/as_2012/discussion_board.css

#2: plugins/Bb-discussionboard/webapp/css/as_schoolhouse/discussion_board.css

The first file is included in the theme package when downloading the Learn 2012 theme. The second file is included in the package when downloading the Bb Schoolhouse theme. Any files with .css extensions found in these directories are included.

If you manage your custom themes by storing copies of the packages offline, refresh your offline custom theme package by downloading it from the Admin Panel UI after upgrading to SP14, in order to get a copy with the new package structure introduced in that service pack. No changes to the style sheets themselves will occur, and no other changes to the customization workflow will occur. However, after upgrading to SP14, offline packages in the prior package structure will no longer be able to be uploaded - an error message is shown in this case.

Important Notes

  • The Theme DIFF Command Line Tool for comparing two themes has been updated to work with the new package structure. As a result of this change, the tool returns an error message when the packages that are compared have different package structures. The tool can still be used to compare two packages with the same structure, whether the structure is before SP 14 or after, as long as the structure is the same between packages. For more information, see Theme DIFF Tool.
  • When installing a building block containing its own style sheets on a system that has at least one custom theme, you will receive an informational receipt during installation. This receipt recommends checking the feature against your custom theme, just as you do when upgrading Learn. You will receive this message when your system has a custom theme already installed, even if that theme is not currently in use.
  • Information about whether a building block contains tool-specific style sheets is available for any building block in the Administrator Panel. In the Building Blocks section, select Building Blocks, and then select Installed Tools. Access the contextual menu for any building block listed and select View Components. If the Building Block contains tool-specific style sheets for any of the themes that ship with Learn, the theme handles will be listed on this page..

Known Issues

  • You cannot upload themes that have the old structure after upgrading to SP14. The workaround is to download those themes for offline storage after upgrading to SP14 or higher. For  more information, see the Important Note above.

To Learn More

To learn more about custom themes, see Using Themes.