Education Blocks

A set of re-usable Elemental
blocks for Ministry of Education Silverstripe projects. This repository
provides the model, templates, javascript and styles but allows individual
projects to stylize the blocks as they need.

Table of Contents

1. Styling
2. Javascript
3. Configuration
4. Conventions
   • HTML
   • Javascript
   • SCSS
5. Blocks
   • Accordion
   • Banner
   • Chapter
   • Content
   • File
   • Hero
   • Mosaic Grid
   • Row
   • Spacer
   • Tabs
   • Tile
   • Video

Styling

To use the scss styles developed you can either include them one by one into
your file or include the all the styles by importing contents.scss

@import "../../vendor/education/blocks/client/scss/contents.scss";

Individual block styles should be stored within education/blocks/client/scss/blocks.

Note that these styles rely heavy on the styles provided by the (https://github.com/education-nz/silverstripe-ds)[design system]

Javascript

Some blocks require javascript enhancements (e.g Accordions and Tabs). Like the
SCSS, this module does not automatically include the javascript functionality,
the individual site must import it via ES6 includes as needed into their build
process. Each block provides one export to call on document.ready.

import { ready } from "../../../vendor/education/silverstripe-ds/client/js/utils";
import { Accordion } from "../../../vendor/education/blocks/client/js";

ready(() => {
    Accordion();
});

Configuration

Disabling Blocks

If your education project does not require a particular block then disable it
from the content editors.

Page:
  disallowed_elements:
    - Education\Blocks\Hero

Disallowed elements is set on any object that implements elemental, by default
that includes Page but also any subclass of ElementList for things like our
Row block. A common situation in this case is you may want a Hero block on
the page but you don't want someone to put a Hero inside an Accordion list

Page:
  disallowed_elements:
    - Education\Blocks\Hero
Education\Blocks\Accordion:
  disallowed_elements:
    - Education\Blocks\Hero

Re-labelling Blocks

Websites might have specific nomenclature for elements, for instance one project
may refer to a Tile as Image Button or a Chapter element as something like
Featured Text. Blocks can be relabeled via the config YAML API.

Education\Blocks\Tile:
  singular_name: 'Image Button'

Conventions

Each block provides all the required javascript, scss and HTML to function.

HTML

HTML should be written in BEM format. block-name__elem-name_mod-name_mod-val

• Names are written in lowercase Latin letters.
• Words are separated by a hyphen (-).
• The element name is separated from the block name by a double underscore (__).
• The modifier name is separated from the block or element name by a single underscore (_).
• The modifier value is separated from the modifier name by a single underscore (_).
• For boolean modifiers, the value is not included in the name.

Javascript

Javascript should be provided as ES6 and stored in client/js/blocks/{name}.js.

It should export a single default property which is a function.

SCSS

Default SCSS is provided in client/scss/blocks/{name}.scss. Unlike JS which is
automatically included, the SCSS is not - your build process will need to bring
in the SCSS files that you need to use

@import "../../../vendor/education/blocks/client/scss/blocks/video.scss";

Blocks

Below is the list of currently supported blocks provided in this module. They
can be enabled or disabled individually per site.

Accordion

Banner

Full page width, image in the background and a H1 title, optional paragraph

Chapter

A more structured content element which displays the content with a title and a
sidebar.

@todo - image

Content

Basic HTML Content view.

Content Carousel

Carousel of content elements

File

File b

Hero

Full page width title, colour and image.

Mosaic Grid

Displays a grid of photos or links

Quote

Displays a formatted block quote.

Row

Group a list of tiles or other elements such as images

Spacer

Force some space between two elements. For uses where default spacing is not
sufficient.

Tabs

Tile

Designed to be embedded within an Row and links to another page.

Video

Copyright

Copyright 2020. All Rights Reserved Ministry of Education, NZ.