vanilla wiki

#Vanilla

Vanilla is a theme bundled with the Adapt framework.

Vanilla provides specific values to styles, including colors, padding, margins, and assets such as fonts and background images. It was designed to be functional, minimal, and easy to modify. It is intended to be the foundation for customised themes.

##Installation

As Adapt's core theme, Vanilla is included with the installation of the Adapt framework and the installation of the Adapt authoring tool.

• If Vanilla has been uninstalled from the Adapt framework, it may be reinstalled. With the Adapt CLI installed, run the following from the command line:
  adapt install adapt-contrib-vanilla

• If Vanilla has been uninstalled from the Adapt authoring tool, it may be reinstalled using the Plug-in Manager.

##Uninstallation
The Adapt framework and authoring tool do not allow the installation of more than one theme at a time. In order to replace Vanilla, it must be uninstalled.

• To uninstall Vanilla from the Adapt authoring tool, use the Plug-in Manager.

• To uninstall Vanilla when working with the framework standalone, make the root of your framework installation your current working directory and run the following command:
  adapt uninstall adapt-contrib-vanilla

Back to Top

This page focuses on the structure of the Vanilla theme and how it works with Adapt. Visit the page dedicated to Usage and Tips for brief how-tos and other insights into modifications.

Important: The authoring tool does not yet provide the capability to modify theme colors, margins, graphics and other styles. For example, there is no user interface associated with the Adapt framework or authoring tool that will allow you to choose a font, or a pixel size from a dropdown or to choose a color using an eyedropper. Until that capability is introduced, it is recommended to make and test theme modifications using the Adapt framework, then upload the completed theme into the authoring tool.

Settings overview

Unlike most Adapt plug-ins, the Vanilla theme has no attributes that are required to be configured in the authoring tool. There are several settings that can be used to configure individual blocks. These settings have not been integrated yet into the authoring tool.

The relationship between Vanilla's properties and the way they are presented in the authoring tool’s interface is governed by properties.schema.

[To Do: Add block level configuration when it is available in the authoring tool.]

Back to Top

Structure

Vanilla complies with the file/folder structure specified for Adapt themes. Of the files that are found in Vanilla's root, only one impacts the visual presentation: theme.json. It contains pixel-widths used by Adapt to categorize screen sizes. Let's look at the purpose of the folders.

####assets

The assets folder is the proper location for all media used by the theme. These are primarily images and graphics; but, if a theme required audio or video files, they would be stored here. These assets are not content-specific, since themes are intended to be applied across multiple courses. In the case of Vanilla, the assets include the GIF that indicates the page is loading, some JPGs used to demonstrate how to use the Classes property, and a couple of utility PNGs.

####fonts

Vanilla's fonts folder does not hold files for its text font Open Sans. That font family is a Google font and is imported in fonts.less. The files found in this folder are various formats of an icon font that has been named vanilla. If you choose to include a font family rather than import it in a Less file, store it here.

####js

This folder holds a couple of JavaScript files that associate user configurations with theme styles. It is unlikely that a desired theme modification would necessitate a change to these files.

####less

Adapt employs a CSS pre-processor called Less which makes CSS more manageable by using variables and other techniques. During the build process, the Less files are transformed into CSS. Knowledge of CSS alone is often sufficient to effect significant modifications to the theme. However, that CSS knowledge is applied to Less files—there are no CSS files. Serious theme development requires knowledge of Less.

CSS provides a cascading order that determines precedence by assigning greater weight to specificity and proximity of declaration. So a rule applied broadly can be overridden by a rule that is more narrowly targeted. The organization of style rules among Vanilla's less files and within less files takes a similar approach. Values for styles of broadest impact are assigned first and then reassigned element by element with increasing specificity. A new value can be introduced into the cascade to effect styling of particular levels or portions of the course. Consistent styling is maintained across the course, while allowing targeted styling.

The less folder is organized in two groups: the four files (colors.less, fonts.less, generic.less, and paddings.less) and those in the src folder. The four files are used to assign values to less variables. The files contained in the src folder are where these variables are assigned to CSS styles.

Colors, fonts, and paddings have been singled out for variables because their values are frequently repeated throughout Vanilla's design. If Vanilla made use of a variety of border styles, it might have made sense to include a borders.less. The values in these files are assigned to variables which oftentimes are reassigned to other variables. Look for this second layer of assignments to reflect logical groupings of elements or categories of elements. The result is that a value changed in one place affects all the elements that use it. Let's examine item-padding as an example.

In paddings.less a less variable (identified by the initial @) is assigned a value:
@item-padding: 20px;
Later in the same file, this variable is assigned to three groups of variables that share the same value:
@item-padding-top: @item-padding;
@item-padding-bottom: @item-padding;
@item-padding-left: @item-padding;
@item-padding-right: @item-padding;

@drawer-item-padding-top: @item-padding;
@drawer-item-padding-bottom: @item-padding;
@drawer-item-padding-left: @item-padding;
@drawer-item-padding-right: @item-padding;

@menu-block-padding-top: @item-padding;
@menu-block-padding-bottom: @item-padding;
@menu-block-padding-left: @item-padding;
@menu-block-padding-right: @item-padding;

One variable became twelve variables whose names more readily connect them with their targets. These variables are assigned to CSS styles in accordion.less, boxmenu.less, gmcq.less, hotgraphic.less, matching.less, mcq.less, narrative.less, and adapt.less.

The benefit of this organization is realized when you want to make a change. Let's say the bottom padding needs to increase by 5px except in the drawer where it needs to increase by 7. We make changes to the variables in paddings.less file and do not have to touch the eight files with the style rules. Our changes might look like this:

@item-padding: 20px;
@item-padding-bottom: 25px;

@item-padding-top: @item-padding;
@item-padding-bottom: @item-padding-bottom;
@item-padding-left: @item-padding;
@item-padding-right: @item-padding;

@drawer-item-padding-top: @item-padding;
@drawer-item-padding-bottom: 27px;
@drawer-item-padding-left: @item-padding;
@drawer-item-padding-right: @item-padding;

@menu-block-padding-top: @item-padding;
@menu-block-padding-bottom: @item-padding-bottom;
@menu-block-padding-left: @item-padding;
@menu-block-padding-right: @item-padding;

The style rules have been divided among files that are named for their target element. For example, you will find all rules for the navigation bar in navigation.less. This is merely organizational as all files are ultimately combined in build/adapt/css/adapt.css. Should your theme modifications warrant creating new variables, you can create a new .less file if you choose. But with a few variables, you'll find ample room in generic.less.

####templates

The templates folder stores files (Handlebars templates) used to generate portions the HTML for various Adapt modules such as the pages, articles, and blocks, the navigation bar, and the drawer. A subfolder named partials contains templates which are used by other templates throughout Adapt's plug-ins. components.hbs is used by all core components to deliver the display title, the body text, and the instruction. buttons.hbs is used by all question components to ensure common functionality. And state.hbs manages the feedback provided by questions through assistive technologies.

##Limitations

No known limitations.