Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Updated readMe and example.json (fixes #345) #371

Merged
merged 9 commits into from
Dec 14, 2022
Merged

Docs: Updated readMe and example.json (fixes #345) #371

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
363aa27
readme updates
guywillis Nov 18, 2022
7ad1af4
example.json clean up
guywillis Nov 18, 2022
534932c
Fixed color hyperlink
guywillis Nov 22, 2022
4b23238
Merge branch 'master' into issue/345
guywillis Nov 22, 2022
a638e8e
Changed colour to color
guywillis Nov 22, 2022
fc0ca8a
Merge branch 'master' into issue/345
guywillis Dec 7, 2022
0456544
Updated _textAlignment entries
guywillis Dec 7, 2022
53e62e9
Updated example.json values and link
guywillis Dec 8, 2022
965332a
Merge branch 'master' into issue/345
guywillis Dec 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 12 additions & 91 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,108 +31,29 @@ The Adapt framework does not allow the installation of more than one theme at a

Unlike most Adapt plug-ins, the **Vanilla** theme has no attributes that are required to be configured in the course JSON files. There is, however, additional functionality available to apply background images and supporting styles for pages, articles and blocks as desired. These attributes are properly formatted as JSON in [_example.json_](https://github.com/adaptlearning/adapt-contrib-vanilla/blob/master/example.json) and available as configurable attributes in the Adapt authoring tool.

Alongside this, the [_example.json_](https://github.com/adaptlearning/adapt-contrib-vanilla/blob/master/example.json#L86) contains a collection of custom classes that Adapt and the Vanilla theme support as standard. These classes are mostly designed to provide additional visual options to increase flexibility.
Alongside these settings, there's a collection of [custom classes](https://github.com/adaptlearning/adapt-contrib-vanilla/wiki/Custom-Classes) that the Vanilla theme supports as standard. These classes are mostly designed to provide additional visual options to increase flexibility.

The **Vanilla** theme also exposes [_colour variables_](https://github.com/adaptlearning/adapt-contrib-vanilla/blob/master/less/_defaults/colors.less) in the Adapt authoring tool for theme editing. This feature allows you to apply and save 'preset' theme styles.
The **Vanilla** theme also exposes [*color variables*](https://github.com/adaptlearning/adapt-contrib-vanilla/blob/master/less/_defaults/_colors.less) in the Adapt Authoring Tool for theme-by-config editing. This feature allows you to apply and save color presets.

**\_vanilla** (object): The following attributes configure the defaults for **Vanilla**. These include **\_backgroundImage**, **\_backgroundStyles** and **\_minimumHeights**. Global attributes are available at page, article and block level.
## JSON Config and Authoring Tool Options

#### Global text alignment
>**\_textAlignment** (object): The text alignment object that contains values for **\_title**, **\_body**, and **\_instruction**.
An explanation on what properties are available as part of the theme can be found [here](https://github.com/adaptlearning/adapt-contrib-vanilla/wiki/JSON-Config-and-Authoring-Tool-Options)

>>**\_title**: (string): This attribute defines the alignment of the title element. Properties include **left**, **center**, and **right**.
Left: Aligns the title to the left of the container. Center: Aligns the title to the center of the container. Right: Aligns the title to the right of the container. The alignment automatically inverses for right-to-left languages. The default is `` which inherits the natural page direction.
## onScreen Animation

>>**\_body**: (string): This attribute defines the alignment of the body element. Properties include **left**, **center**, and **right**.
Left: Aligns the body to the left of the container. Center: Aligns the body to the center of the container. Right: Aligns the body to the right of the container. The alignment automatically inverses for right-to-left languages. The default is `` which inherits the natural page direction.
Further information regarding the onScreen properties can be found on the [wiki](https://github.com/adaptlearning/adapt-contrib-vanilla/wiki/onScreen-Animation)

>>**\_instruction**: (string): This attribute defines the alignment of the instruction element. Properties include **left**, **center**, and **right**.
Left: Aligns the instruction to the left of the container. Center: Aligns the instruction to the center of the container. Right: Aligns the instruction to the right of the container. The alignment automatically inverses for right-to-left languages. The default is `` which inherits the natural page direction.
## Custom Classes

#### Global background image
All supported custom classes defined in the Vanilla theme are detailed [here](https://github.com/adaptlearning/adapt-contrib-vanilla/wiki/Custom-Classes)

> **\_backgroundImage** (object): The backgroundImage object that contains values for **\_large**, **\_medium** and **\_small**.

> > **\_large** (string): File name (including path) of the image used with large device width. Path should be relative to the _src_ folder (e.g., _course/en/images/origami-menu-one.jpg_).

> > **\_medium** (string): File name (including path) of the image used with medium device width. Path should be relative to the _src_ folder (e.g., _course/en/images/origami-menu-one.jpg_).

> > **\_small** (string): File name (including path) of the image used with small device width. Path should be relative to the _src_ folder (e.g., _course/en/images/origami-menu-one.jpg_).

#### Global background image styles

> **\_backgroundStyles** (object): Additional attributes available to customise how background images display. The backgroundStyles object contains values for **\_backgroundRepeat**, **\_backgroundSize** and **\_backgroundPosition**.

> > **\_backgroundRepeat** (string): This attribute defines how the background image repeats. Properties include **repeat**, **repeat-x**, **repeat-y** and **no-repeat**.
> > Repeat-x: The background image is repeated only horizontally. Repeat-y: The background image is repeated only vertically.

> > **\_backgroundSize** (string): This attribute defines the size the background image display. Properties include **auto**, **cover**, **contain**, and **100% 100%**.
> > Auto: The background image is displayed in its original size. Cover: Resize the background image to cover the entire container, even if it has to stretch or crop the image. Contain: Resize the background image to make sure the image is fully visible. 100% 100%: Resize the background image to match the dimensions of the container.

>>**\_backgroundPosition** (string): This attribute defines the size the background image position. Properties include **left top**, **left center**, **left bottom**, **center top**, **center center**, **center bottom**, **right top**, **right center**, and **right bottom**.
The first value is the horizontal position and the second value is the vertical

#### Global minimum heights

> **\_minimumHeights** (object): The minimum heights attribute group specifies the minimum height of the image container at different device widths (`_large`, `_medium`, and `_small`).

> > **\_large** (number): The minimum height should only be used in instances where the image container height needs to be greater than the content e.g. to prevent a background image being cropped.

> > **\_medium** (number): The minimum height should only be used in instances where the image container height needs to be greater than the content e.g. to prevent a background image being cropped.

> > **\_small** (number): The minimum height should only be used in instances where the image container height needs to be greater than the content e.g. to prevent a background image being cropped.

#### Global responsive classes

> **\_responsiveClasses** (object): The responsive classes object adds the associated CSS class(es) to the container element at different device widths (`_large`, `_medium`, `_small`). The class(es) are removed between each device width. Useful for applying styles for a particular device width only rather than applying a global `_classes` style.

> > **\_large** (string): Custom CSS class that is applied at the large device width.

> > **\_medium** (string): Custom CSS class that is applied at the medium device width.

> > **\_small** (string): Custom CSS class that is applied at the small device width.

#### **contentObject.json**
>**\_pageHeader** (object): The page header object that contains objects for **\_textAlignment**, **\_backgroundImage**, **\_backgroundStyles**, and **\_minimumHeights**.

>>**\_textAlignment** (object): See global text alignment for more details.

>>**\_backgroundImage** (object): See global background image for more details.

>>**\_backgroundStyles** (object): See global background image styles for more details.

>>**\_minimumHeights** (object): See global minimum heights for more details.

#### **blocks.json**

> **\_isDividerBlock** (boolean): Determines whether the CSS class `is-divider-block` will be applied. Acceptable values are `true` and `false`.

> **\_paddingTop** (string): Changes the value of the blocks top spacing. Double: Doubles the blocks top spacing. Standard: Retains the standard blocks top spacing. Half: Halves the blocks top spacing. Remove: Removes the blocks top spacing. The default value is `standard`.

> **\_paddingBottom** (string): Changes the value of the blocks bottom spacing. Double: Doubles the blocks bottom spacing. Standard: Retains the standard blocks bottom spacing. Half: Halves the blocks bottom spacing. Remove: Removes the blocks bottom spacing. The default value is `standard`.

> **\_componentVerticalAlignment** (string): Defines the vertical alignment of the child component(s) in relation to the block.
## Structure

Visit the [**Vanilla** wiki](https://github.com/adaptlearning/adapt-contrib-vanilla/wiki) for more information about how to use and manipulate the theme.
To view a breakdown of the themes structure please visit the [wiki](https://github.com/adaptlearning/adapt-contrib-vanilla/wiki/Structure)

## Structure
## Icons

| Folder/File | Description |
| :----------------------------- | :---------------------------------------------------------- |
| 📁 assets | Optional global assets can be added here |
| 📁 fonts | Optional global fonts can be added here |
| 📁 js | JavaScript files on which the theme depends |
| 📁 less | Location of any [LESS](http://lesscss.org/) based CSS files |
| 📁 less/\_defaults | Location of configuration LESS files |
| 📄 less/\_defaults/colors.less | Location of global colour variables |
| 📁 less/core | Location of Adapt Framework LESS file styles |
| 📁 less/plugins | Location of Adapt plugin LESS file styles |
| 📁 less/project | Location of additional LESS file styles |
| 📁 templates | Optional global template overrides can be added here |

## Templates

**Vanilla** supports customisation for the rendering of various Adapt elements through the use of [Handlebars](http://handlebarsjs.com/) templates. The file name of the template indicates the element it affects.
The [wiki](https://github.com/adaptlearning/adapt-contrib-vanilla/wiki/Icons) features a detailed overview of the icons available within the themes custom font set

## Limitations

Expand Down
Loading