{"_id":"57ad1b413215100e00bcf380","category":{"_id":"566a35b81e08750d00a0c49b","__v":2,"version":"55a6e72f8cc73e0d00096638","pages":["566b4ba6f46dc90d009de81f","568aea8fcbd4ca0d00aebfa9"],"project":"55a6e72e8cc73e0d00096635","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-12-11T02:32:24.723Z","from_sync":false,"order":5,"slug":"theme-editor-configuration-reference","title":"Theme/Editor Configuration"},"user":"55a6caa022cfa321008e01d6","parentDoc":null,"project":"55a6e72e8cc73e0d00096635","version":{"_id":"55a6e72f8cc73e0d00096638","project":"55a6e72e8cc73e0d00096635","hasReference":false,"__v":29,"hasDoc":true,"createdAt":"2015-07-15T23:05:19.125Z","releaseDate":"2015-07-15T23:05:19.125Z","categories":["55a6e7308cc73e0d00096639","55b7ed07aea7c8190058badb","5604567c0c78b00d0039b191","5605e6f23a93940d002b3e4a","5605f2bba4574a0d00811365","5605f309a4574a0d00811366","5608e3b98aedf50d0004cf8f","5608e4318aedf50d0004cf90","5608e6b5a7cc2f0d00d9754d","5608e6d331beb60d001b6560","5608f879a7cc2f0d00d97580","560b097887b71d0d000d3bd9","560b13cbafa0990d00979545","560b5cbec341310d00de2a01","560b5cd0c341310d00de2a02","566a35b81e08750d00a0c49b","566a3e8503b4b20d00d02a4a","567889d307bf6a0d0083edc8","569c8b7c15bb390d00db6f9d","56b254dc65ddf50d0076ba8f","57a8ebc4cdeea20e001d2a63","57e48a4000c8680e00fae6e7","5808216773557d0f00a1e428","58105ad54a8aa50f00aa4cba","58105bf298aea40f00afa3ba","58105f548a4aed0f00d67536","581061b898aea40f00afa3be","584b3de7e5f3a42300df6ef7","596839a75965d400155bb750"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":1,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-08-12T00:41:37.131Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"This entry covers:\n  * [Configuration Files](#section-configuration-files)  \n  * [Managing Keys between Versions](#section-managing-keys-between-versions)\n  * [Persistent Settings Storage](#section-persistent-settings-storage)\n  * [Theme Upgrades and Settings](#section-theme-upgrades-and-settings)\n\n## Configuration Files\n\nEach theme contains two related JSON files of key-value pairs: `config.json` and `schema.json`. These files' keys provide the following features:\n\n- Keys that you include in `schema.json` – together with their corresponding `config.json` default values – define the settings that merchants can customize through the Theme&#160;Editor graphical interface. \n- Other `config.json` keys contain metadata about the theme, such as the theme's name, version, and resource controls.\n- Keys located under the `config.json > variations` object define variations of the theme. For example, a theme might have a \"Light\" variation and a \"Bold\" variation, each with different typography and colors. Each&#160;theme can include as many variations as you like. \n- Keys located under both files' `settings` objects define the theme's look, feel, and functionality.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"If you are developing for your own store, the \\\"merchant\\\"/\\\"store administrator\\\" role mentioned throughout this page overlaps with your developer role.\"\n}\n[/block]\nFor documentation on the principal keys included in Stencil's reference Cornerstone theme, see this section's [config.json Metadata](/docs/configjson-reference) and [schema.json Metadata](/docs/schemajson-metadata-for-theme-editor) entries. For an introduction to the graphical editor, see the \n[What Is Theme Editor](/docs/what-is-theme-editor) entry.\n\n## Managing Keys between Versions\nTo make sure revisions to your theme are backward-compatibile, we generally recommend that you manage keys in both your `config.json` and `schema.json` files in an additive way. Specific recommendations:\n\n- Adding new keys is generally fine. (However, each key in `schema.json` _must_ have a matching default in `config.json`, as outlined in [Enabling Theme Editor](/docs/schemajson-metadata-for-theme-editor#schema-json-EnableTE).)\n- Use caution in deleting any key. Doing so can break your new theme version's backward compatibility.\n- We do not recommend _renaming_ keys. Instead, we recommend introducing a new key, while maintaining the old key until it is no longer in use by anyone using an older version of your theme.  \n-  Each object within your <span class=\"inline-code\">config.json > <a href=\"/docs/configjson-reference#config-variations\">variations</a></span> object defines one theme variation. If you are adapting an existing theme and consciously want to remove one or more variations, you can do so by removing the corresponding key(s).\n\n## Persistent Settings Storage\nWhen store administrators use Theme Editor to customize your theme for their store, the store's resulting configuration settings are saved to a separate configuration service at BigCommerce.\n\n## Theme Upgrades and Settings\nWhen a merchant upgrades your theme to a newer version, all key-value pairs that were saved to the BigCommerce configuration service are carried forward. For example, assume this customization/upgrade scenario:\n\n- You release your Star Glow theme, version 1. This theme's `config.json` includes a key named `logo_size`, establishing a default value of 100x250. The combination of the key and the value compose a `logo_size` _setting_.\n- The merchant uses Theme Editor to change the `logo_size` setting to 175x275. This customized setting is stored in the BigCommerce configuration service.\n- You release Star Glow, version 1.1. In this theme revision, you have changed the `logo_size` to 300x300.\n- When the merchant applies Star Glow version 1.1 to their store, their custom `logo_size` setting of 175x275 remains in effect.\n- If you the merchant creates a second store and applies Star Glow version 1.1 to it, that store has no custom `logo_size` setting – so it will default to the new theme version's 300x300 value.","excerpt":"","slug":"config-overview","type":"basic","title":"Configuration Overview"}

Configuration Overview


This entry covers: * [Configuration Files](#section-configuration-files) * [Managing Keys between Versions](#section-managing-keys-between-versions) * [Persistent Settings Storage](#section-persistent-settings-storage) * [Theme Upgrades and Settings](#section-theme-upgrades-and-settings) ## Configuration Files Each theme contains two related JSON files of key-value pairs: `config.json` and `schema.json`. These files' keys provide the following features: - Keys that you include in `schema.json` – together with their corresponding `config.json` default values – define the settings that merchants can customize through the Theme&#160;Editor graphical interface. - Other `config.json` keys contain metadata about the theme, such as the theme's name, version, and resource controls. - Keys located under the `config.json > variations` object define variations of the theme. For example, a theme might have a "Light" variation and a "Bold" variation, each with different typography and colors. Each&#160;theme can include as many variations as you like. - Keys located under both files' `settings` objects define the theme's look, feel, and functionality. [block:callout] { "type": "info", "body": "If you are developing for your own store, the \"merchant\"/\"store administrator\" role mentioned throughout this page overlaps with your developer role." } [/block] For documentation on the principal keys included in Stencil's reference Cornerstone theme, see this section's [config.json Metadata](/docs/configjson-reference) and [schema.json Metadata](/docs/schemajson-metadata-for-theme-editor) entries. For an introduction to the graphical editor, see the [What Is Theme Editor](/docs/what-is-theme-editor) entry. ## Managing Keys between Versions To make sure revisions to your theme are backward-compatibile, we generally recommend that you manage keys in both your `config.json` and `schema.json` files in an additive way. Specific recommendations: - Adding new keys is generally fine. (However, each key in `schema.json` _must_ have a matching default in `config.json`, as outlined in [Enabling Theme Editor](/docs/schemajson-metadata-for-theme-editor#schema-json-EnableTE).) - Use caution in deleting any key. Doing so can break your new theme version's backward compatibility. - We do not recommend _renaming_ keys. Instead, we recommend introducing a new key, while maintaining the old key until it is no longer in use by anyone using an older version of your theme. - Each object within your <span class="inline-code">config.json > <a href="/docs/configjson-reference#config-variations">variations</a></span> object defines one theme variation. If you are adapting an existing theme and consciously want to remove one or more variations, you can do so by removing the corresponding key(s). ## Persistent Settings Storage When store administrators use Theme Editor to customize your theme for their store, the store's resulting configuration settings are saved to a separate configuration service at BigCommerce. ## Theme Upgrades and Settings When a merchant upgrades your theme to a newer version, all key-value pairs that were saved to the BigCommerce configuration service are carried forward. For example, assume this customization/upgrade scenario: - You release your Star Glow theme, version 1. This theme's `config.json` includes a key named `logo_size`, establishing a default value of 100x250. The combination of the key and the value compose a `logo_size` _setting_. - The merchant uses Theme Editor to change the `logo_size` setting to 175x275. This customized setting is stored in the BigCommerce configuration service. - You release Star Glow, version 1.1. In this theme revision, you have changed the `logo_size` to 300x300. - When the merchant applies Star Glow version 1.1 to their store, their custom `logo_size` setting of 175x275 remains in effect. - If you the merchant creates a second store and applies Star Glow version 1.1 to it, that store has no custom `logo_size` setting – so it will default to the new theme version's 300x300 value.