Themes

Themes are a way to customize the look and feel of Blockly. Currently, we support customizing block colours, category colours and certain components through the Themes class. For any other component we provide the theme name as a class on the injection div. This allows users to change the look of any unsupported components through CSS. Our main goal in creating themes is to empower developers to create Blockly experiences that are more accessible.

However, with great power comes great responsibility. If there is no specific need to control all three style values for blocks (block colour, border colour, and shadow block colour) we highly encourage users to stick with using Blockly colours. It can be difficult to come up with colours that go well together so the easiest way to get started is still to define colours using hues and allow Blockly to calculate the colours of the border and shadow blocks.

Block Style

A block style is currently made up of four fields: colourPrimary, colourSecondary, colourTertiary, and hat.

Block with arrows pointing to primary, secondary and tertiary colour

{
    "colourPrimary": "#4a148c",
    "colourSecondary":"#AD7BE9",
    "colourTertiary":"#CDB6E9"
}

Primary Colour(required) -- This is used as the background colour of the block and can be defined in either hue or hex value.

Secondary Colour(optional) -- This colour is used if the block is a shadow block.

Tertiary Colour(optional) -- In thrasos and zelos renderers, this is the border colour of the block. In the geras renderer the tertiary colour changes the colour of the block's highlight.

Shows border for different renderers

Hat(optional) -- This is used when the user wants to add a hat to their block. Currently, the only option for this value is "cap". Users can find out more information on hats and what they are used for here.

Category Style

A category style currently only holds a colour property.

{
    "colour":"290"
}

Colour(required) -- This is the colour of the category on the flyout. This value can either be defined as a hex value or as a hue. Usually these colours should be the same as the colourPrimary on the majority of blocks in the category. This makes it easy for users to tell what blocks belong in what category.

Component Styles

We currently support changing the colour of the below components:

  • workspaceBackgroundColour: The workspace background colour
  • toolboxBackgroundColour: Toolbox background colour
  • toolboxForegroundColour: Toolbox category text colour
  • flyoutBackgroundColour: Flyout background colour
  • flyoutForegroundColour: Flyout label text colour
  • flyoutOpacity: Flyout opacity
  • scrollbarColour: Scrollbar colour
  • scrollbarOpacity: Scrollbar opacity
  • insertionMarkerColour: The insertion marker colour (Does not accept colour names)
  • insertionMarkerOpacity: The insertion marker opacity
  • markerColour: The colour of the marker displayed in keyboard navigation mode
  • cursorColour: The colour of the cursor displayed in keyboard navigation mode

Most other components can be changed by using the theme name in your CSS. However, if there is a component you would like to change that is not already a part of this list and cannot be changed using CSS, please file an issue with more information here.

Font Styles

A font style is an object that holds the family, weight and size of a font.

{
    "family": "Georgia, serif",
    "weight": "bold",
    "size": 12
}

Start Hats

Defining a start hat on a block style allows a user to control exactly what blocks to set a hat on. Setting it directly on a theme will add a 'hat' on top of all blocks with no previous or output connections. More information on hats and what they are used for can be found here

Using Themes

In order to add a theme to your Blockly application there are three steps that need to be completed:

  • Create a Theme
  • Add Style Names
  • Set Your Theme

Create a Theme

A theme currently takes in a name, a map of block styles, a map of category styles and a map of component styles.

Example Block Styles

{
   "list_blocks": {
      "colourPrimary": "#4a148c",
      "colourSecondary":"#AD7BE9",
      "colourTertiary":"#CDB6E9"
   },
   "logic_blocks": {
      "colourPrimary": "#01579b",
      "colourSecondary":"#64C7FF",
      "colourTertiary":"#C5EAFF"
   }
}

Example Category Styles

{
   "list_category": {
      "colour": "#4a148c"
   },
   "logic_category": {
      "colour": "#01579b",
   }
}

Example Component Styles

{
   "workspaceBackgroundColour": "#1e1e1e",
   "toolboxBackgroundColour": "#333"
}

Create the Theme

A theme can be created using the constructor or by using defineTheme. Using defineTheme makes it easy to extend a pre existing theme and set all values with a single object.

var theme = Blockly.Theme.defineTheme('themeName', {
  'base': oldTheme,
  'blockStyles': blockStyles,
  'categoryStyles': categoryStyles,
  'componentStyles': componentStyles,
  'fontStyle': fontStyle,
  'startHats': true
});

An example of using defineTheme can be found here.

Add Style Names

Now that we have created a theme we need to add the name of the styles to the block and category definitions.

Categories

For categories just add the style tag to the xml.

<category name="Logic" categorystyle="logic_category">
</category>

Blocks

How you define your block determines how you need to add the style name. You can find more on block definitions here.

JSON

"style":"logic_blocks"

JavaScript

 this.setStyle('logic_blocks')

Set your Theme

Now that you have created a theme and connected it to your blocks and categories , it is time to tell Blockly what theme to use.

Blockly Options

The best way to set an initial theme is by including options.theme in your inject call. A user can supply the theme object or the JSON object.

Theme
{
    theme: Blockly.Theme.defineTheme('themeName', {
        'blockStyles': blockStyles,
        'categoryStyles': categoryStyles,
        'componentStyles': componentStyles
    })
}
JSON
{
   theme: {
      'blockStyles' : {
         "list_blocks": {
            "colourPrimary": "#4a148c",
            "colourSecondary":"#AD7BE9",
            "colourTertiary":"#CDB6E9"
         }
      },
      'categoryStyles' : {
         "list_category": {
            "colour": "#4a148c"
         }
      },
      'componentStyles' : {
         'workspaceBackgroundColour': '#1e1e1e'
      }
   }
}

More information on options can be found here. If no theme is provided then it will default to the Classic Theme which can be found in the themes folder here.

Blockly Set Theme

If you want to dynamically change your theme (for instance in the case of allowing users to choose a theme from a dropdown menu) then you can call yourWorkspace.setTheme(theme).

Create Block Styles Script

This script will take in a map of hues or hex values and will calculate the secondary and tertiary colours for them. The script can be found in the theme_script folder.

Accessibility

We currently have added a high contrast theme in order to increase readability. This style is not finalized and is subject to change. We have also added the Deuteranopia/Pritanopia and Tritanopia themes for different kinds of colour vision deficiency.