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:
| Property | Type | Notes |
|---|---|---|
label | string | The label shown at the top of the expandable group in the designer |
global | boolean | Specifies whether or not the group should be shown in the "Global Styles" tab or the main content tab |
settings | array | An array of settings definitions in the form outlined below |
[
{
"label": "My Group",
"settings": [
{ ... }
]
}
]
Settings
Each setting has the following properties:
| Property | Type | Notes |
|---|---|---|
id | string | Key for accessing the setting's value inside templates and as the storage key in settings_data.json |
label | string | Label for the setting's input inside the designer side panel. |
type | string | The type of input that should be presented in the designer side panel. |
inherits | string | The id of another setting to default to |
boolean | boolean | Specifies 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 | |
|---|---|
text | A single line text input |
richtext | A rich text editor that outputs HTML |
image | An image upload, includes a basic image editor and cropping tool |
color | A color picker |
font_face | A font face dropdown, shows top 200 fonts from Google Fonts |
font_size | A font size picker |
link | A single line text input that validates to be a valid URL |
switch | A boolean on/off switch |
divider | A 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"
}
]
}
]