When youdownload a theme, the exported files include a file namedmanifest.json. The file defines the Settings panel of the theme in Guide:
This guide describes the manifest file and what you can do with it. It also provides a reference of its specification. For an example, export your theme and open themanifest.jsonfile in a text editor.
Topics covered:
- Understanding the manifest.json file
- Using settings in manifest.json as variables
- Modifying the manifest.json file
- Manifest object
- Setting object
- Variable object
- Type property
- File type
- List type
- Range type
- Translations
Understanding the manifest.json file
When you export a theme, the exported files include a file namedmanifest.json. You can use the manifest file to define the theme'sSettings panelin Guide.
You can modify existing settings in the panel or create new ones. In the following example, the manifest file assigns a default value of "#30aabc" to thecolor_brand_textsetting:
"settings": [ { "label": "Colors", "variables": [ { "identifier": "color_brand_text", "type": "color", "description": "color_brand_text_description", "label": "color_brand_text_label", "value": "#30aabc" }, ... ] }, ... ]Afterimporting the themeinto Guide, thecolor_brand_textsetting appears in the Settings panel with the labelBrand text color, as specified by the "label" property in the manifest file, and the default hex value of the color picker is #30aabc, as specified by the "value" property:
Using settings in manifest.json as variables
Settings are also calledvariablesbecause you can use a setting's identifier as a variable in the theme's files. Changing a value in the Settings panel updates the value in all the files that use the variable.
You can insert a variable in the theme'sstyle.cssfile using the$identifiersyntax, or in a page template using thesettings.identifierhelper in Curlybars. Examples:
style.css
input:focus { border: 1px solid $color_brand_text; }You can also use single curly brackets to embed the helper in a CSS expression, as follows:
max-width: #{$search_width}px;Page template
Modifying the manifest.json file
Themanifest.jsonfile is not included in the list of files in the Edit Code page in Help Center. To edit themanifest.jsonfile, you must export the theme to files, make changes to the manifest file on your system, then import the theme in Guide.
To export the theme
To import the modified theme
Manifest object
The manifest's document root object has the following properties:
Name
Type
Comment
name
string
Theme name
author
string
The person, team, or organization who created the theme
version
string
Theme version that follows theSemantic versioning 2.0.0standard
api_version
string
Templating API version
settings
array
List of setting objects. SeeSetting object
Example
{ "name": "My second theme", "author": "Jane Doe", "version": "1.0.1", "api_version": 3, "settings": [ ... ] }
Setting object
The settings in both themanifest fileand the Settings panel in Guide are organized into groups such as Colors or Fonts. Each setting group is defined in the manifest file by asetting object. Each object consists of a label and one or more settings, such as Brand Color and Text Color.
You can modify setting objects or create your own. The objects are reflected in the theme's Settings panel when you import the theme in Guide.
Each setting object has the following properties:
Name
Type
Comment
label
string
A translation property name. SeeTranslations. Displays a title for a group of settings.
variables
array
List of settings in the group. Also called variables. SeeVariable object. The manifest file can have a maximum quantity of 200 variable objects.
SeeGuide product limits for your help center(Total number of settings in manifest.json).
Example
"settings": [ { "label": "colors_group_label", "variables": [{...}, ...] }, { "label": "fonts_group_label", "variables": [{...}, ...] }, { "label": "brand_group_label", "variables": [{...}, ...] }, { "label": "banners_group_label", "variables": [{...}, ...] } ]
The example creates the following categories in the Settings panel:
Variable object
Eachsetting objecthas avariables数组列出实际的设置。他们叫ed variables because you can insert them as variables in Help Center templates or in CSS. SeeGuide product limits for your help center(Total number of settings in manifest.json).
You can define any variable you want. However, the manifest file must contain two file variables with the following identifiers: "logo" and "favicon". SeeRequired variables.
Each variable has the following properties:
Name
Type
Comment
identifier
string
Variable name that you can use in CSS or Curlybars expressions. Must be 30 characters or less and contain only alphanumeric characters and _ (underscore)
type
string
UI control in the Settings panel in Guide to get the value from the user. One oftext,list,checkbox,color,file, orrange. SeeType property
label
string
The name of the setting that gets displayed next to the UI control in the Settings panel. Must be 40 characters or less.
To translate this value, use a translation property name. SeeTranslations. Translations do not have a limit of characters.
description
string
A brief descriptionof the setting that gets displayed next to the UI control in the Settings panel. Must be 80 characters or less.
To translate this value, use a translation property name. SeeTranslations. Translations do not have a limit of characters.
value
string
The setting's default value
options
array
For thelisttype only. An array of list items. SeeOption object
min
integer
For therangetype only. The minimum value of the range
max
integer
For therangetype only. The maximum value of the range
Example
"variables": [ { "identifier": "color_brand", "type": "color", "label": "color_brand_label", "description": "color_brand_description", "value": "#0072EF" }, ... ]
The example creates the following label and control in the Settings panel:
Required variables
You must specify the following two variables in the manifest file or the file will be rejected on import:
- logo - the
identifiermust be "logo" and thetypemust be "file"
- favicon - the
identifiermust be "favicon" and thetypemust be "file"
Example
"variables": [ { "identifier": "logo", "type": "file", "description": "logo_description", "label": "logo_label" }, { "identifier": "favicon", "type": "file", "description": "favicon_description", "label": "favicon_label" } ]
Type property
Eachvariable objecthas atypeproperty that specifies a UI control to set the setting value in the Settings panel in Guide. The property can have one of the following values:
text- Text input field. Each text field has a limit of 1000 characters.list- Dropdown list. Includes a list of option objects for the list items. SeeList typecheckbox- Checkbox. SeeCheckbox typecolor- Color pickerfile- File uploader. SeeFile typerange- Range input field. SeeRange type
Example
{ "identifier": "color_headings", "type": "color", ... }
List type
If thetypeof a variable object is "list", then the object includes anoptionsarray to populate the dropdown list. Each option in the list has the following properties:
Name
Type
Comment
label
string
Friendly text displayed for the list item. Must be 40 characters or less.
To translate this value, use a translation property name. SeeTranslations. Translations do not have a limit of characters.
value
string
Underlying value of the list item
You must specify more than one option in the array or importing the theme will fail.The number of options should not exceed 20. SeeGuide product limits for your help center(Total number of options in a list type setting).
Example
{ "identifier": "font_headings", "type": "list", "label": "Heading", "description": "Font for headings", "value": "Arial, 'Helvetica Neue', Helvetica, sans-serif", "options": [ { "label": "Arial", "value": "Arial, 'Helvetica Neue', Helvetica, sans-serif" }, { "label": "Copperplate Light", "value": "'Copperplate Light', 'Copperplate Gothic Light', serif" }, { "label": "Baskerville", "value": "Baskerville, 'Times New Roman', Times, serif" } ] }
Checkbox type
If thetypeof a variable object is "checkbox", use the object'svalueproperty to specify the value that's set when the user selects the checkbox. The value must be a boolean.
Name
Type
Comment
value
boolean
trueorfalse
Example
{ "identifier": "scoped_hc_search", "type": "checkbox", "description": "scoped_help_center_search_description", "label": "scoped_help_center_search_label", "value": true }
File type
A variable object with atypeof "file" adds a file uploader control in the Settings panel. This type of variable doesn't have avalueproperty. Example:
{“标识符”:“community_image”、“类型”:“文件”,"description": "community_image_description", "label": "community_image_label" }
The value is a file URL determined by the system.
You must provide a default file for the theme to use until a user uploads a different file. The name of the default file must match the variable's identifier. Place the file in thesettingsfolder in your theme files. Example:
Use file variables where URLs are expected in the theme files. Examples:
style.css
.community_banner { background-image: url($community_image); }
Page template
Range type
A variable object with a type of "range" adds a slider control in the Settings panel. Example:
A range variable includes aminand amaxproperty to specify the range of values that the user can set when they move the slider. The values must be integers.
Example
{ "identifier": "font_size", "type": "range", "description": "font_size_description", "label": "font_size_label", "min": 70, "max": 150, "value": 100 }
Translations
The visible strings in the Settings panel are all defined intranslations. A translation consists of a property name and value. Example:
"text_color_label": "Text color"
The property names are arbitrary. You can specify any name you like.
The translations are stored in language-specific JSON files in thetranslationsfolder in the theme's root folder:
/ translations - en-us.json - es.json - fr.json - ...
Each file consists of a JSON object with a list of translations:
en-us.json
{ "brand_color_description": "Brand color for major navigational elements", "brand_color_label": "Brand color", ... }
The translations are used to specify the labels and descriptions in the Settings panel.
To specify strings for labels and descriptions
In thetranslationsfolder, locate the JSON file for the default language of your Help Center. Example:en-us.json.
Update the values of existing properties or add new properties. Example:
{ "text_color_label": "Text color", "text_color_description": "Text color for body and heading elements", ... }
In variables, use the translation property name as the value of"label"or"description"attributes.
"variables": [ { "identifier": "color_text", "type": "color", "label": "text_color_label", "description": "text_color_description", "value": "#0072EF" }, ... ]
SeeVariable object. If you create a property or change a property name, make sure to update your variables.
You can localize the labels and descriptions in the Settings panel. You need to provide the localized strings yourself.
To localize labels and descriptions
In thetranslations文件夹,定位为每个额外的langua JSON文件ge you want to support.
Copy the property names defined in your default translation file. Example:
{ "text_color_description": "", "text_color_label": "", ... }
Specify a localized string for each property. Examples:
fr.json
{ "text_color_description": "Couleur du texte pour les éléments du titre et du corps", "text_color_label": "Couleur du texte", ... }
13 Comments
Is there going to support for multiline text areas in the manifest.json settings? Currently my code is:
{
"identifier": "top_tips_1_heading",
"type": "text",
"description": "Heading",
"label": "Top Tip 1 Heading",
"value": "How do I link my bank account to the app?"
},
{
"identifier": "top_tips_1_body",
"type": "multiline",
"description": "Answer",
"label": "Top Tip 1 Answer",
"value": "Test"
},
I saw some articles mention "type" "multiline" so when the theme is imported the editor can enter multi line values instead of putting a sentence all in one line of a text field.
However "multiline" does not seem to be supported I get the following error on import:
If it doesn't match any of the required schemas how can I get it to match? We really need a multi line text area in the settings so our editors can add multi line answers to the settings of our theme. Can you tell me how to achieve this please? See the below screen as an example of us typing in a single field...
Hey@...,
The screenshot of types you posted are for apps. Themes don't support multi-line right now. In this article, you can find which types of settings are available for themes.
Specifically for your use case, we recommend usingdynamic contentinstead, as this supports translating to multiple languages as well. :)
In this help article I found the option to add a text variable to the help center. How can I use it in my html templates?https://support.zendesk.com/hc/en-us/articles/115012547687-Customizing-the-Settings-panel-Guide-Professional-and-Enterprise-#variable-object
Hi Michael,
Thanks for writing! You may want to look into this articleUsing variables in CSS and HTML. It will provide you guidance on how you can use variables in CSS and variables in Curlybars in HTML. Thank you!
Thank you,@.... I already know this guide, but I was looking for an option where I can define a text variable in the settings and then using this variable in my template.
I resolved it by using dynamic content – like this it's also translateable. But maybe there's an even better solution?
Hi Michael,
I'm afraid, there is no other way. Our documentation suggested using the exporting the theme or using style.css file and using curlybars expressions in HTML. Thank you!
Hi@...,
If you add a setting to manifest.json by exporting the theme and making this change locally, you can then access it via{{settings.setting_identifier}}
We have some more info inhttps://developer.zendesk.com/documentation/help_center/help-center-templates/objects/#settings-object
@...Thanks for your answer – the variable was the missing piece in my case. Even though I'm not quite sure if this is the best solution (because there's not way to translate it), this should probably work (not tested yet).
The ever-unhelpful "The property '#/settings/X/variables/X' of type object did not match any of the required schemas" message could still do with an update.
Even a note in this article or similar reminding users that the indexes start at 0 so they can narrow down the cause of the problem.
And giving proper detail on the requirements of fields in the JSON file.
For example, I ran into the error above because I had an empty string in the description of a variable.
I just wanted to post something I just realized about the vague error messages
This error:
Actually does clue us into where the error is
settings/X refers to which "group" contains the error, starting from zero as one. And the variable number is the number corresponding to that variable, also starting with zero as one.
So :
#/settings/2/variables/7'
意味着有一个问题与第三组the 8th variable. It could be a wrong type of variable, a bad value, missing property, or too many characters (or invalid characters).
So in this context, it's a problem in the "brand" group, because brand is the third setting. Then count from zero to 8 to find the variable in question.
Can we look to please add more information to this article around the limits for the following things:
- Total amount of values in an option array (article states minimum 1 but I'm unsure on maximum)
- Character limits for labels and descriptions
- Character limits within text fields (I think this is 999)
- Max quantity of variable objects (I realise this is 200 but would be helpful to have all of this information centralised).
Many thanks
To echo Hamish, can more details be added on the limitations in the manifest file?
Receiving an unhelpful message that reads "The property '#/settings/0/variables/X' of type object did not match any of the required schemas" doesn't give us much to go on.
The limit will be known to you, so adding docs should take a couple of minutes, not months.
Edit to add, the length of descriptions, labels etc. is not flagged by ZAT, so I hope you can understand the frustration that a limit is only being imposed at the last step.
HeyHamish LangandNathan Purcell! Thanks for calling out that the limitations aren't documented as well as they should be in this article. Our Guide team is currently working on updating this article to have more information. In the meantime, I can provide you with this information:
Pleasesign into leave a comment.