Theme Configuration
Theme configuration allows you to make it easy for clients to customize their website design.
Some example uses include:
- Allow them to upload their own logo.
- Enable clients to manage content in the header and footer that is usually hard-coded in HTML.
- Allow customers to add their own social networking links.
- Turn on or off certain UI elements.
As the website designer/developer, you have full control over what the fields are and how they are organized.
Global variables
Theme settings can also be treated as global variables since they are made available to all templates.
Accessing theme variables in templates
All theme settings are accessed under the _core.theme.settings variable.
For example, if you create a theme setting called "Logo" that allowed someone to upload a new logo, then below is how you could use that image in your templates.
<div class="Header">
{% set _core.theme.settings.logo.alt = _core.theme.settings.companyName %}
{{ _core.theme.settings.logo.tag }}
</div>
Creating theme settings
You set up the theme configuration in the theme.json file. The theme.json file will go inside the theme folder. For example, if your theme's folder is called custom and themes is the name of the folder where themes are stored, then you would have the following directory/file structure:
themes
custom
template
theme.json
Sample code
Below is an example showing all of the different configuration field types. This also shows how to organize fields in groups (tabs) as well as setting default values.
{
"name": "Custom theme",
"settings": {
"groups": [
{
"name": "Group Name",
"description": "Group description",
"fields": [
{
"name": "text_field",
"label": "Text Field",
"description": "Field description",
"type": "text",
"default": "default field value"
},
{
"name": "code_field",
"label": "Code Field",
"type": "code"
},
{
"name": "collection_field",
"label": "Collection Widget Field",
"type": "collectionWidget"
},
{
"name": "color_field",
"label": "Color Field",
"type": "color"
},
{
"name": "contentsnippet_field",
"label": "Content Snippet Field",
"type": "contentSnippet"
},
{
"name": "Decimal field",
"label": "Decimal",
"type": "decimal"
},
{
"name": "embed_url_field",
"label": "Embed URL Field",
"type": "embedUrl"
},
{
"name": "form_field",
"label": "Form Field",
"type": "form"
},
{
"name": "iframe_embed_field",
"label": "Iframe Embed Field",
"type": "iframeEmbed"
},
{
"name": "lat_long_field",
"label": "Latitude Longitude Field",
"type": "latitudeLongitude",
"latitude": "48.8566",
"longitude": "2.3522",
"mapZoom": "8",
"mapType": "satellite"
},
{
"name": "nav_field",
"label": "Navigation Field",
"type": "navigation"
},
{
"name": "Number field",
"label": "Number",
"type": "number"
},
{
"name": "editor_field",
"label": "Rich Text Editor Field",
"type": "richTextEditor"
},
{
"name": "snippet_field",
"label": "Snippet Field",
"type": "snippet"
},
{
"name": "textarea_field",
"label": "Textarea Field",
"description": "Field description",
"type": "textarea",
"attributes": [
{"size": "large"}
]
},
{
"name": "file_upload",
"label": "File Upload",
"description": "file upload description",
"type": "file",
"path": "docs/theme-test"
},
{
"name": "image_upload_default",
"label": "Image Upload With Default",
"description": "Should have a default value of /20thT-2.jpg",
"type": "image",
"path": "images",
"default": "/20thT-2.jpg"
},
{
"name": "image_upload",
"label": "Image Upload",
"description": "No size constraint",
"type": "image",
"path": "images/theme-test"
},
{
"name": "image_upload_resize",
"label": "Image Upload with resize",
"type": "image",
"path": "images/theme-test",
"width": "200",
"height": "300"
},
{
"name": "multi_select_field",
"label": "Multi Select Field",
"type": "multiSelect",
"options": {
"opta": "Option a Label",
"optb": "Option b Label 2",
"optc": "Option c Label 3",
"optd": "Option d Label 4",
"opte": "Option e Label 5",
"optf": "Option f Label 6"
}
},
{
"name": "checkbox_api",
"label": "Checkbox API",
"type": "checkboxApi",
"api": "app.categoryNames",
"apiParams": {
"template": "api-category-filter-ui"
}
},
{
"name": "multi_select_api",
"label": "Multi Select API",
"type": "multiSelectApi",
"api": "app.categoryNames",
"apiParams": {
"template": "api-category-filter-ui"
}
},
{
"name": "select_api",
"label": "Select API",
"type": "selectApi",
"api": "app.categoryNames",
"apiParams": {
"template": "api-category-filter-ui"
}
},
{
"name": "radio_field",
"label": "Radio Field",
"description": "Radio field description",
"type": "radio",
"default": "d",
"options": {
"a": "Option a Label",
"b": "Option b Label 2",
"c": "Option c Label 3",
"d": "Option d Label 4",
"e": "Option e Label 5",
"f": "Option f Label 6"
}
},
{
"name": "checkbox_field",
"label": "Checkbox Field",
"description": "Checkbox field description",
"type": "checkbox",
"default": "d",
"options": {
"a": "Option a Label",
"b": "Option b Label 2",
"c": "Option c Label 3",
"d": "Option d Label 4",
"e": "Option e Label 5",
"f": "Option f Label 6"
}
},
{
"name": "select_field",
"label": "Select Menu Field",
"description": "Field description",
"type": "select",
"default": "option3",
"options": {
"option1": "Option Label",
"option2": "Option Label 2",
"option3": "Option Label 3",
"option4": "Option Label 4",
"option5": "Option Label 5",
"option6": "Option Label 6"
}
},
{
"name": "select_country",
"label": "Select Country Field",
"type": "selectCountry"
},
{
"name": "select_date",
"label": "Select Date Field",
"type": "selectDate",
"yearPast": "30",
"yearFuture": "2",
"yearFirst": "1905",
"yearLast": "2033"
},
{
"name": "select_province",
"label": "Select Province Field",
"type": "selectProvince"
},
{
"name": "select_state",
"label": "Select State Field",
"type": "selectStateProvince"
},
{
"name": "select_state_province",
"label": "Select State Province Field",
"type": "selectStateProvince"
},
{
"name": "url",
"label": "URL Field",
"type": "url"
},
{
"name": "random_number",
"label": "Random number",
"type": "randomNumber",
"min": 0,
"max": 10
},
{
"name": "imageset",
"label": "Image Set",
"type": "imageSet",
"upload": "individual",
"children": [
{
"name": "image_upload_set",
"label": "Image Upload_set",
"description": "No size constraint",
"type": "image",
"path": "/images/theme-set"
},
{
"name": "image_upload_resize_set",
"label": "Image Upload with resize set",
"type": "image",
"path": "images/theme-set",
"width": "200",
"height": "300"
}
]
},
{
"name": "repeating",
"label": "Repeating fields",
"type": "repeating",
"itemName": "Test Repeating Item",
"children": [
{
"name": "text_field",
"label": "Text Field",
"type": "text"
},
{
"name": "code_field",
"label": "Code Field",
"type": "code"
},
{
"name": "imageset",
"label": "Image Set",
"type": "imageSet",
"upload": "individual",
"children": [
{
"name": "image_upload_set",
"label": "Image Upload_set",
"description": "No size constraint",
"type": "image",
"path": "/images/theme-set"
},
{
"name": "image_upload_resize_set",
"label": "Image Upload with resize set",
"type": "image",
"path": "images/theme-set",
"width": "200",
"height": "300"
}
]
},
{
"name": "repeatingchild",
"label": "Repeating child fields",
"type": "repeating",
"itemName": "child",
"children": [
{
"name": "child_text_field",
"label": "Text Field",
"type": "text"
}
]
}
],
"default": [
{
"text_field": "Text field value",
"code_field": "Code field value"
},
{
"text_field": "2 Text field value",
"code_field": "2 Code field value"
}
]
}
]
},
{
"name": "Second Group Name",
"sections": [
{
"name": "Section Name",
"description": "Section description",
"fields": [
{
"name": "text_field2",
"label": "Text Field",
"description": "Field description",
"type": "text",
"default": "default field value"
}
]
},
{
"name": "Section 2 Name",
"fields": [
{
"name": "textarea_field2",
"label": "Textarea Field",
"description": "Field description",
"type": "textarea",
"default": "default field value\n New Line",
"attributes": [
{"size": "small"}
]
},
{
"name": "select_field2",
"label": "Select Menu Field",
"description": "Field description",
"type": "select",
"default": "option_value2",
"options": {
"option_value": "Option Label",
"option_value2": "Option Label 2"
}
}
]
}
]
}
]
}
}