📘

Heads up!

Theme settings are only used by the new designer launched in June 2016. Not sure which designer you're using? Check here.

The Cratejoy Designer customizes all site content and styles via simple, configurable strings that we call "settings". These string settings can be accessed in any HTML or CSS file and can be reused across your theme.

You can add, remove, or change these settings to add more functionality to your theme inside the Cratejoy Designer.

Defining Settings

Each component has a settings_schema.json file that defines the different settings options available, their input type, and how they should be grouped in the UI.

Setting Schema

Groups

settings_schema.json is a JSON array made up of setting groups for organization. Each group has the following properties:

PropertyTypeNotes
labelstringThe label shown at the top of the expandable group in the designer
globalbooleanSpecifies whether or not the group should be shown in the "Global Styles" tab or the main content tab
settingsarrayAn array of settings definitions in the form outlined below
[
  {
    "label": "My Group",
    "settings": [
      { ... }
    ]
  }
]

Settings

Each setting has the following properties:

PropertyTypeNotes
idstringKey for accessing the setting's value inside templates and as the storage key in settings_data.json
labelstringLabel for the setting's input inside the designer side panel.
typestringThe type of input that should be presented in the designer side panel.
inheritsstringThe id of another setting to default to
booleanbooleanSpecifies that the setting is used to show or hide content in the theme. Should be true if ever used inside an if/else block

Setting Types

Each setting has a specified type that indicates which UI the user sees.

Type
textA single line text input
richtextA rich text editor that outputs HTML
imageAn image upload, includes a basic image editor and cropping tool
colorA color picker
font_faceA font face dropdown, shows top 200 fonts from Google Fonts
font_sizeA font size picker
linkA single line text input that validates to be a valid URL
switchA boolean on/off switch
dividerA simple horizontal divider in the settings list

Related Setting Groups

Some settings are related to a single element on the page, such as the styles for text or a button. Using special naming conventions will group these settings into a single sub-group within your top level setting group.

The label used for the group is always pulled from the font_face setting.

Font Groups

Font groups can include a font_face, font_size, and color settings, combined into a single group. The convention for this grouping are:

  • <your_name>/font_face
  • <your_name>/font_size
  • <your_name>/color
[
  {
    "label": "Fonts",
    "global": true,
    "settings": [
      {
        "id": "page_heading/font_face",
        "label": "Heading 1",
        "type": "font_face"
      },
      {
        "id": "page_heading/color",
        "type": "color"
      },
      {
        "id": "page_heading/font_size",
        "type": "font_size"
      }
    ]
  }
]
Button Groups

Button groups can include a font_face, font_size, and 4 different color settings, combined into a single group. The convention for this grouping are:

  • <your_name>button/font_face
  • <your_name>button/font_size
  • <your_name>button/color
  • <your_name>button/text_color
  • <your_name>button/hover_color
  • <your_name>button/hover_text_color
[
  {
    "label": "Buttons",
    "global": true,
    "settings": [
      {
        "id": "primary_button/font_face",
        "label": "Primary Button",
        "type": "font_face"
      },
      {
        "id": "primary_button/font_size",
        "type": "font_size"
      },
      {
        "id": "primary_button/color",
        "type": "color",
      },
      {
        "id": "primary_button/text_color",
        "type": "color"
      },
      {
        "id": "primary_button/hover_color",
        "type": "color"
      },
      {
        "id": "primary_button/hover_text_color",
        "type": "color"
      }
    ]
  }
]

Inheritance

Settings can inherit their values from other settings. For example, a theme can define a color palette that other settings can use while still allowing specific settings to be overridden. This makes styling a theme much quicker without loosing fine-grained customizability.

[
  {
    "label": "Color Scheme",
    "global": true,
    "settings": [
      {
        "id": "primary_color",
        "label": "Primary",
        "type": "color"
      },
      {
        "id": "secondary_color",
        "label": "Secondary",
        "type": "color"
      }
    ]
  },
  {
    "label": "Navigation",
    "settings": [
      {
        "id": "logo_color",
        "type": "color",
        "label": "Logo Color",
        "inherits": "primary_color"
      }
    ]
  }
]

Full Example

[
  {
    "label": "Color Scheme",
    "global": true,
    "settings": [
      {
        "id": "primary_color",
        "label": "Primary",
        "type": "color"
      },
      {
        "id": "secondary_color",
        "label": "Secondary",
        "type": "color"
      }
    ]
  },
  {
    "label": "Fonts",
    "global": true,
    "settings": [
      {
        "id": "page_heading/font_face",
        "label": "Heading 1",
        "type": "font_face"
      },
      {
        "id": "page_heading/color",
        "type": "color",
        "inherits": "secondary_color"
      },
      {
        "id": "page_heading/font_size",
        "type": "font_size"
      }
    ]
  },
  {
    "label": "Buttons",
    "global": true,
    "settings": [
      {
        "id": "primary_button/font_face",
        "label": "Primary Button",
        "type": "font_face",
        "inherits": "page_body/font_face"
      },
      {
        "id": "primary_button/font_size",
        "type": "font_size"
      },
      {
        "id": "primary_button/color",
        "type": "color",
        "inherits": "primary_color"
      },
      {
        "id": "primary_button/text_color",
        "type": "color"
      },
      {
        "id": "primary_button/hover_color",
        "type": "color",
        "inherits": "secondary_color"
      },
      {
        "id": "primary_button/hover_text_color",
        "type": "color"
      }
    ]
  },
  {
    "label": "Hero",
    "settings": [
      {
        "id": "hp_hero_image",
        "label": "Image",
        "type": "image"
      },
      {
        "type": "divider"
      },
      {
        "id": "hp_hero_block_color",
        "label": "Background",
        "type": "color",
        "inherits": "secondary_color"
      },
      {
        "type": "divider"
      },
      {
        "id": "hp_hero_content",
        "type": "richtext"
      }
    ]
  }
]