When you export a theme, the exported files include a file named manifest.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 the manifest.json file 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 named manifest.json. You can use the manifest file to define the theme's Settings panel in 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 the color_brand_text setting:
"settings": [
{
"label": "Colors",
"variables": [
{
"identifier": "color_brand_text",
"type": "color",
"description": "color_brand_text_description",
"label": "color_brand_text_label",
"value": "#30aabc"
},
...
]
},
...
]
After importing the theme into Guide, the color_brand_text setting appears in the Settings panel with the label Brand 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 called variables because 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's style.css file using the $identifier
syntax, or in a page template using the settings.identifier
helper 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
<div style="background-color:{{settings.color_brand_text}}">
Modifying the manifest.json file
The manifest.json file is not included in the list of files in the Edit Code page in Help Center. To edit the manifest.json file, 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
- On the Themes page, click the gear icon on the lower right of a theme pane, and select Export.
To import the modified theme
- On the Themes page, click Import on the upper-right side.
Manifest object
The manifest's document root object has the following properties:
Name | Type | Comment |
---|---|---|
name | string | Theme name |
author | string | The person who created the theme |
version | string | Theme version that follows the Semantic versioning 2.0.0 standard |
api_version | string | Templating API version |
settings | array | List of setting objects. See Setting object |
Example
{
"name": "My second theme",
"author": "Jane Doe",
"version": "1.0.1",
"api_version": 1,
"settings": [
...
]
}
Setting object
The settings in both the manifest root object and the Settings panel in Guide are organized into groups such as Colors or Fonts. Each setting group is defined in the manifest file by a setting 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. See Translations. Displays a title for a group of settings |
variables | array | List of settings in the group. Also called variables. See Variable object |
Example
"settings": [
{
"label": "colors_group_label",
"variables": [{...}, ...]
},
{
"label": "fonts_group_label",
"variables": [{...}, ...]
},
{
"label": "brand_group_label",
"variables": [{...}, ...]
},
{
"label": "banners_group_label",
"variables": [{...}, ...]
}
]
Note: The value of the "label"
properties are translation property names. See Translations.
The example creates the following categories in the Settings panel:
Variable object
Each setting object has a variables
array that lists the actual settings. They're called variables because you can insert them as variables in Help Center templates or in CSS.
You can define any variable you want. However, the manifest file must contain two file variables with the following identifiers: "logo" and "favicon". See Required 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 |
type | string | UI control in the Settings panel in Guide to get the value from the user. One of text , list , checkbox , color , file , or range . See Type property
|
label | string | A translation property name. See Translations. Displays the translation value next to the UI control in the Settings panel |
description | string | A translation property name. See Translations. Displays the translation value as a brief description of the setting |
value | string | The setting's default value |
options | array | For the list type only. An array of list items. See Option object
|
min | integer | For the range type only. The minimum value of the range |
max | integer | For the range type 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
identifier
must be "logo" and thetype
must be "file" - favicon - the
identifier
must be "favicon" and thetype
must 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
Each variable object has a type
property 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 -
list
- Dropdown list. Includes a list of option objects for the list items. See List type -
checkbox
- Checkbox. See Checkbox type -
color
- Color picker -
file
- File uploader. See File type -
range
- Range input field. See Range type
Example
{
"identifier": "color_headings",
"type": "color",
...
}
List type
If the type of a variable object is "list", then the object includes an options
array 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 |
value | string | Underlying value of the list item |
You must specify more than one option in the array or importing the theme will fail.
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 the type of a variable object is "checkbox", use the object's value property to specify the value that's set when the user selects the checkbox. The value must be a boolean.
Name | Type | Comment |
---|---|---|
value | boolean |
true or false
|
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 a type of "file" adds a file uploader control in the Settings panel. This type of variable doesn't have a value property. Example:
{
"identifier": "community_image",
"type": "file",
"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 the settings folder 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
<img src="{{settings.community_image}}">
Range type
A variable object with a type of "range" adds a slider control in the Settings panel. Example:
A range variable includes a min and a max property 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 in translations. 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 the translations folder 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 the translations folder, 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" }, ... ]
See Variable 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 the translations folder, locate the JSON file for each extra language 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", ... }
40 Comments
Where do I find the `manifest.json` file? I thought it would be in the assets, but cannot find it.
Thank you!
Hi Brad,
Again, you've caught me without the doc ready! I'm working on a Export doc.
But here's what you do:
Click the options (gear) menu on the theme, then select Export.
When you finished editing the manifest file, you can re-import it by clicking Import in the upper-right of the Themes page.
Brad, I edited my commend to add the all-important import step, if you edit the manifest file.
Okay, so there is no way to modify that single file, but rather I have to export/import to modify the manifest.json. Correct?
Thank you for your help!
That's right, Brad. You have to export the theme to modify the manifest file.
It will be good idea to have examples on range, and text types.
Please also document the rules that you run.
We noticed, if we use "list" type with only one option, manifest won't pass validation stage (while theme is being imported after upload). It took a while to find out this which I think is decision by design (i.e a list with one option shouldn't be allowed anyway).
Thank you
Is there a way to make a hidden type of variables? For example, it would be good to save the media queries breakpoints which are not needed to be editable in the Theming Center?
Thanks for the great update!
@Trapta,
We are woking on adding better error messages on import. These will tell you the exact reason why Import failed.
@Stas,
Our vision with the Theming Center (TC) variables is to allow less experienced people to do smaller tweaks in the theme that don't require a theme developer.
It feels you are looking for SCSS variables :) We currently don't support SCSS compilation in TC but you can still compile SCSS into CSS offline and then import it. We have an example of that in https://github.com/zendesk/copenhagen_theme
@Augusto Cravo Silva,
I have a different update here :)
I just spent a while trying to figure out why I couldn't add any new variables to my manifest.json file. Each time I got this cryptic import error:
The property '#/settings/0/variables/0' of type object did not match any of the required schemas
I finally figured out you can't put raw text into "label" and "description" fields. Instead you have to add a translation key to AT LEAST the default locale in the translations directory and point "label" and "description" to that newly created key.
It would be great if you could add this caveat to the documentation - it wasn't clear.
Thanks!
Thanks for the heads up on that, Devorah! I'll pass your feedback along in our Documentation team!
I'm getting the same error:
The property '#/settings/0/variables/0' of type object did not match any of the required schemas
Do you really have to create a translations folder and then place all of the strings into it to get it to import correctly? That is a lot of extra work that shouldn't be required. There are examples above that do not follow this method and when I exported my theme to make alterations to it, it didn't have these translation folder/files to begin with. Would this mean I would need to export, make all of the translation changes, to get it to import again?
Hi @Brad,
Sorry to hear you're experiencing issues. We need to look into improving this error message.
What it means is that the 1st variable of the 1st group of settings is not correctly defined.
You don't need to create translations if you do not want to provide this functionality. If we can't find a translation, we will show what is set in the manifest. However, you should be aware that the label string length is limited to 40 characters, when not using the translation file. This might be the issue. Which type of setting are you trying to add?
I had exported the default, Zendesk-provided theme. I then modified it and then attempted to reupload it and then experienced the error. I created the translation file and it worked without any issues. Also, as an FYI, none of the label strings had more than 40 characters.
The first variable of the first group of settings was:
Hi @Brad, thanks for providing those details.
I think we would need to have a look at the ZIP file to understand what the problem could be.
If you are still experiencing issues, please send us a Support request with the ZIP file.
Thanks
@Augusto, @Brand: I also got stuck here for a while, despite finding this thread and shortening my attribute lengths.
In my case I discovered it was whenever I used a identifier longer than 30 chars.
Please add this to the documentation now, so we can skip the guesswork. It seems your schema is very restrictive (30 chars, that's fairly short) with its validation as well as its error output. Schema should be useful both to the client and server, IMO...
And I'd like if we could allow for longer values. Guess I'm just that verbose ;)
What is the max lengh of the 'value' property in the manifest.json file for a field of type 'text' ?
My use case is to hold a list of comma-separated form id that my theme uses, thinking the Zendesk admin could maintain these through the theme settings, instead of editing the theme code directly, where there is always the risk they break something editing the html or javascript.
I'm unsure how well this would scale for those accounts that have forms though, in case the value field cannot hold that much data...
@Joel
I added to 30-character limit to the identifier property in the doc.
Thanks.
@Charles: thanks. But what about the max length of the value property for text fields?
Also can we add to the reference table that there is a 40 char limit, unless you use translation files, i.e. as this comment from Augusto Cravo Silva explained:
However, you should be aware that the label string length is limited to 40 characters, when not using the translation file.
This limit also applies to the description field.
Thank you so much appreciated thanks
Hello,
I have a question concerning the use of the manifest.json file in parallel of SASS variables.
manifest.json allows users to define default and custom variables, that you can change directly from the Guide Admin user interface (as shown in this tutorial), and that's great.
But if you use SASS files for your theme, you got a _variables.scss file with the same variables (brand_color, text_color...etc).
Which file override the other ? And what happens if I define some variables in my _variables.scss file, and then change them from the guide admin interface ?
For more context, I work with this kind of boilerplate, that allow me to work with SASS/ES6...etc and compiles the all theme inside a /dist folder.
Thank you !
EDIT :
I think the solution is to use this to get the variables from Zendesk settings. So in your _variables.scss file, it should look like this :
Hi Charles
This page would be a good place to document the limits with some example. For example, we have discussed how label field is restricted to have N number of characters. Similarly, there is a limit on number of settings, why not give an example what does a setting mean, and how do you calculate the total number of settings?
At Diziana, we are having hard time to have our own settings along with what Zendesk exposes in Copenhagen? We have worked with thousands of customers, and they want more flexibility. I am sure Zendesk is working to improve theming experience, I like Shopify a lot for their tools and theming experience.
I am requesting following features, and will appreciate if you can at least discuss it internally and think of doing these:
Theme authors and Zendesk customers spent thousands of hours to figure out things, solve basic things, and build abstractions on top of Zendesk templating language and tools. That all can change by adding little more smartness in tools, and templating language. Once again Shopify is a good example to look at.
Thank you
Team Diziana
Hi Abdul,
This is excellent feedback. You might also want to share it in the Guide product feedback forum, which the product team monitors more closely:
https://support.zendesk.com/hc/en-us/community/topics/360000029847
Other users can add their support to get these ideas on the product roadmap.
Thanks.
Is this shared in the developer documentation at all? I really struggled to locate details regarding the manifest file.
Is Guide really the appropriate place for technical documentation?
I would like to add a slider to the settings panel and save the value when I move the slider. The save button was not enabled when I changed the slider. I am able to save the state if I use a checkbox. Could you let me know what can be done to save the new value of a range type?
Hello Allen,
Could you possibly provide a little more information on what you are trying to construct? Also, any images you can include as well as the steps you took thus far would be extremely helpful in troubleshooting this for you.
Hello Allen,
One of our developers was able to reproduce the issue you were running into. I've gone ahead and created a ticket for you so we can troubleshoot this w/ in more depth.
identifier has to be lowercase or you will get an error like:
The property '#/settings/0/variables/0' of type object did not match any of the required schemas
Does the manifest control the thumbnail image for the theme on the theme workbench? We want to change the image to what the theme really looks like. Thank you.
^^^ Almost immediately after posting I noticed the thumbnail.png file from exporting. I replaced the image, imported again, and boom!
Please sign in to leave a comment.