Modifying the Vanilla Theme

• Overview
• Creating a New Theme
• Updating Your Theme

Overview

In Adapt themes are plug-ins. To add and deploy a new theme, you create a zip file that includes all the files required by an Adapt plug-in, and upload it to the authoring tool using Plugin Management. Once uploaded, you can select and apply your new theme.

While there are a variety of ways to create a theme, perhaps the most straightforward method is to modify the bundled Vanilla theme as outlined below.

Creating a New Theme

1. Make a copy of Vanilla.

In a typical installation of the authoring tool, the root folder of Vanilla can be found at this location:
adapt_authoring\adapt_framework\src\theme\adapt-contrib-vanilla
Copy the adapt-contrib-vanilla folder to another convenient location. Change the name of the folder to reflect your new theme.

2. Update bower.json.

The bower.json file is read by the authoring tool when uploading plug-ins. Change the values for the following fields:

• name: the unique identifier (e.g., adapt-myNewTheme)
• version: three part number (major.minor.patch) for this theme (e.g., 0.0.1)
• displayName: the name displayed in the authoring tool (e.g., MyNewTheme)
• theme: last segment of the 'name' (e.g., myNewTheme)

(Consider updating package.json.)

Back to Top

3. Modify the Less.

Adapt uses the Less CSS preprocessor. One of the big advantages is that Less allows Adapt to use variables within CSS. You don't have to install it, but you have to work with it. When you publish your course, the .less files are processed and converted into .css files.

The .less files are located in the less folder. The file names help to locate style rules that you want to change. Several files deserve comments. The variables in colors.less, fonts.less, paddings.less, and generic.less are assigned to CSS style rules in the files located in the src folder. These files deserve to be the starting point of your modifications. src/theme-extras.less provides a home for bespoke classes that might extend the use of your theme. src/icons.less assigns CSS class names to the font icons located in fonts/vanilla.eot, etc.

Adapt also uses Handlebars. The name of these HTML templates are referenced by JavaScript files elsewhere in the source code. And the patterns discernible in their CSS classes are not arbitrary. To modify the styling of the templates, it is recommended that the style rules associated with these classes be changed rather than replacing the class names used in the templates. Note: Templates associated with plug-ins (components, extensions, menus, themes) are not located here in the templates folder. They are included in the source code of the plug-in. Plug-in developers are encouraged to style their templates using the class names found in the .less files so that your theme is extended to them, too.

Be sure to visit Styling Your Course in the Adapt framework wiki for more insights, especially about the most Less significant variables.

Back to Top

4. Override the templates.

Adapt templates stored in the Adapt Framework or associated plugins can be overridden in a theme by creating a file with the same name.

Back to Top

5. Zip up the folder.

The name the Zip file will not affect the name of the theme within the authoring tool, so feel free to change it if desired. Zip from the root of your theme folder, like this:

folder.zip/
    theme root folder/
        assets/
        fonts/
        ... etc.

Not like this:

folder.zip/
    assets/
    fonts/
    ... etc.

Note:
At this point in development Mac users should not use the built-in Compress utility. Instead use Terminal to navigate to the folder that is the parent of your custom theme. Run the following command
zip -r my-custom-theme-name.zip my-custom-theme-folder
where my-custom-theme-name is an arbitrary name for the zip file and my-custom-theme-folder is the actual name of the folder you want to zip.

Back to Top

6. Upload your theme

Because your theme is a plug-in, use the authoring tool's Plugin Management feature to upload your Zip file.

7. Select your theme

Once the upload completes successfully, your theme will be appear as a selection alongside Vanilla.

Updating Your Theme

The Plugin Management feature does more than insert your theme into the proper folders. It tracks the version numbers of all plug-ins to ensure they are compatible with versions of the authoring tool and the framework. When plug-ins are registered, Plugin Management notes when new versions are available and makes it easy for you to update them.

When you make a change to your theme, or any other type of plug-in, Plugin Management requires that it have a different version number than the one in its database. Before zipping your file, you must increment the version number found in bower.json. If you do not increment the version, it will result in an error stating ‘plugin already exists’.

Back to Top

A note about package.json

package.json is required by the Node Package Manager (npm). The Adapt framework and authoring tool make use of npm during installation and when building output. It is essential that registered plug-ins update the version number in package.json whenever it is incremented in bower.json. The version number in package.json is not required to be updated in plug-ins that are not registered. However, the Adapt community encourages you to adopt best practices and to package, register, and share your good work with the whole community.