{"_id":"593f7e1f88fd4d00197d9143","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"},"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","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-06-13T05:54:39.238Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"[block:html]\n{\n  \"html\": \"<a name=\\\"schema-json-ref\\\"></a>This entry guides you through designing and adjusting the Theme Editor graphical UI for your theme, by editing your theme's <NOBR><span class=\\\"inline-code\\\">schema.json</span> file.</nobr> It covers these topics:<br>\\n\\n<ul>\\n <li><a href=\\\"#schema-json-EnableTE\\\">Enabling Theme Editor</a></li>\\n <!-- <li><a href=\\\"#schema-json-Files\\\">File-Management Requirements</a></li> -->\\n <li><a href=\\\"#schema-json-BestPrax\\\">Best Practices</a></li>\\n <li><a href=\\\"#schema-json-UI\\\">How .json Entries Govern Theme Editor's UI</a></li> \\n <li><a href=\\\"#schema-json-data-types\\\">Theme Editor Data Types</a></li>  \\n <!-- <li><a href=\\\"#schema-json-Headings\\\">Types versus \\\"heading\\\" Labels</a></li> -->\\n <li><a href=\\\"#schema-json-Structure\\\">Theme Editor/schema.json Data Structure</a></li>\\n <li><a href=\\\"#schema-json-Sequence\\\">Arbitrary UI Scope and Sequence</a></li>\\n <!-- <li><a href=\\\"#schema-json-Reqs\\\">Requirements</a></li> -->\\n <li><a href=\\\"#schema-json-ObjStruct\\\">Object Structure in schema.json:</a>\\n     <ul>  <!-- Begin nested list -->\\n      <li><a href=\\\"#schema-json-Color\\\">Color Example</a></li>\\n \\t\\t\\t<li><a href=\\\"#schema-json-FontSelect\\\">Font and Select (Drop-Down List) Examples</a></li>\\n \\t\\t\\t<li><a href=\\\"#schema-json-FontVsSelect\\\">Font versus Select Types</a></li>\\n \\t\\t\\t<li><a href=\\\"#schema-json-PgLayout\\\">Page Layout Options using Select Elements</a></li>\\n \\t\\t\\t<li><a href=\\\"#schema-json-Chkbox\\\">Checkbox Examples</a></li>\\n \\t\\t\\t<li><a href=\\\"#schema-json-ImageDim\\\">imageDimension Examples</a></li>\\n \\t\\t\\t<li><a href=\\\"#schema-json-OptImage\\\">optimizedCheckout-image Examples</a></li>\\n \\t\\t\\t<li><a href=\\\"#schema-json-text\\\">Text Examples</a></li>\\n \\t\\t\\t<!-- <li><a href=\\\"#schema-json-Radios\\\">Radio Buttons Example</a></li> -->     \\n \\t\\t\\t<!-- <li><a href=\\\"#schema-json-config\\\"> Dependency on config.json</a></li> --> <!-- End nested list -->\\n       </li> <!-- End outer list -->\\n    </ul>\\n</ul>\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"For an end user's view of the Theme Editor UI, please see our [Using the Stencil Theme Editor](https://support.bigcommerce.com/articles/Public/Using-the-Stencil-Theme-Editor) support article. (This is written for merchants, but is relevant to developers using Theme Editor to customize themes.)\",\n  \"title\": \"Exercising the UI\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h2> <a name=\\\"schema-json-EnableTE\\\"></a> Enabling Theme Editor </h2>\\n\\nTo provide merchants with Theme Editor support for your theme's settings, you must declare those settings in the theme's <span class=\\\"inline-code\\\">&lt;theme‑name&gt;/schema.json</span> file. You must also include those settings in your theme's <span class=\\\"inline-code\\\"><a href=\\\"/docs/configjson-reference\\\">config.json</span></a> file, <a href=\\\"/docs/about-the-templates-directory\\\">templates</a>, and <a href=\\\"/docs/settings-directory\\\">Sass/CSS files</a>. The basic division of labor is this:\\n\\n<ul>\\n<li><span class=\\\"inline-code\\\">schema.json</span> is an array of objects, declaring which theme settings are editable in Theme Editor. <NOBR>These objects</nobr> also declare all possible values to display in Theme Editor's GUI.</li>\\n\\n<li><span class=\\\"inline-code\\\">config.json</span> assigns (and updates) a default value for each of the editable settings.</li>\\n\\n<li>Each <span class=\\\"inline-code\\\">schema.json</span> entry has an <span class=\\\"inline-code\\\">id</span> element that maps it to its corresponding <span class=\\\"inline-code\\\">config.json</span> entry. <NOBR>The <span class=\\\"inline-code\\\">id</span> value</nobr> identifies the relevant <span class=\\\"inline-code\\\">config.json</span> key name.</li>\\n\\n<li>For front-matter properties to be editable, your theme's Handlebars template must call certain <NOBR><a href= \\\"/docs/custom-handlebars-helpers\\\">Handlebars helpers</a></nobr> to transform the <span class=\\\"inline-code\\\">config.json</span> entries into JavaScript values.</li>\\n  \\n<li>For fonts to be editable, a <a href=\\\"/docs/settings-directory\\\">Sass stylesheet</a> must call certain <a href=\\\"/docs/custom-sass-functions#FontFamily\\\">custom Sass functions</a> to transform the <span class=\\\"inline-code\\\">config.json</span> font entries into CSS values.</li>\\n\\n<li>For styles to be editable, a <a href=\\\"/docs/settings-directory\\\">Sass stylesheet</a> must call certain <a href=\\\"/docs/custom-handlebars-helpers#stylesheet\\\">custom Handlebars helpers</a> to transform the <span class=\\\"inline-code\\\">config.json</span> entries into CSS values.</li>\\n</ul>\\n\\nAs users select options within the Theme Editor UI (and save their selections), Stencil will automatically rewrite <span class=\\\"inline-code\\\">config.json</span> to record new defaults for the theme<!--'s affected variation-->.\\n\\n\\n<h3> <a name=\\\"schema-json-Files\\\"></a> File-Management Requirements </h3>\\n\\nSee Stencil's default Cornerstone theme for examples that fulfill all of the above requirements. However, remember these:\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"* For any theme setting (such as a Sass variable or a front-matter value) to be merchant-customizable,  \\nthat setting – and its possible values – must be present in `schema.json`. You must manually provide these declarations, according to the structure described here.\\n\\n* Also, each key that you create in `schema.json` must have a corresponding `config.json` key whose name matches its `id` value. This `config.json` key sets the default value (even if that is simply an empty string). A `schema.json` setting without an `id`-matched `config.json` key will not appear to users in the Theme Editor GUI.\",\n  \"title\": \"Hard Requirements\"\n}\n[/block]\n## <a name=\"schema-json-BestPrax\"></a> <a name=\"schema-json-Restrix\"></a> Best Practices\n\nPlease follow these guidelines to head off errors upon theme upload, and to avoid possible loss of customizations made via the Theme Editor GUI at runtime:\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"\",\n  \"body\": \"* **Single-Instance Restriction per Storefront:** We strongly recommend opening only one instance of Theme&#160;Editor, at a time, against each storefront. This is because there is currently no synchronization mechanism to reconcile configuration changes made by multiple Theme Editor instances. So <span class=\\\"inline-code\\\">schema.json</span> will record the last changes made by any instance &ndash; but changes saved earlier by other instances might be lost.\\n\\n* **Single-Storefront Restriction per Editor:** In the current release, users can have only one storefront at a time open in Theme Editor. (A&#160;workaround is to open an \\\"Incognito\\\"/private-browsing window on an additional storefront, to bypass the cookie that imposes this restriction.)\\n\\n* **File  Name, Location, and Structure:** Your theme's `schema.json` file must be named `schema.json`, must reside in the root of your `<theme-name>` subdirectory (e.g.: `/cornerstone/schema.json`), and must be valid JSON.\\n\\n* **File Size:** The maximum allowable size for a theme's `schema.json` file is 64 KB. Exceeding this limit will trigger an error upon uploading the theme to BigCommerce. (Other than this size constraint, there is no limit on the number of keys and values that you can place in a theme's `schema.json`.)\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h2> <a name=\\\"schema-json-UI\\\"></a> How .json Entries Govern Theme Editor's UI </h2>\\n\\nAs you can see from the examples just below, your entries in the  <span class=\\\"inline-code\\\">schema.json</span> and <span class=\\\"inline-code\\\">config.json</span> files directly shape users' options in Theme Editor:<br>\\n\\n<ul>\\n<li>Theme <i>Variations</i> always appear at the top of the Theme Editor panel. These variations are defined only in <span class=\\\"inline-code\\\">config.json</span>, and their definition order in that file governs their display order in Theme Editor.</li>\\n\\n<li>Merchants must select one variation to edit, at a time, in Theme Editor. The selections that they make in the remainder of Theme Editor's UI will apply to only that selected variation.</li>\\n\\n<li>Theme Editor's remaining sequence of top-level (Section) headings corresponds directly to the sequence of top-level (Section) objects that you declare in <span class=\\\"inline-code\\\">schema.json</span>:</li>\\n</ul>\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"<img src=\\\"https://files.readme.io/NXeFUx5cSuyp12DJ4Qcr_Theme-Editor-UI.png\\\" alt=\\\"Theme Editor graphical user interface\\\" height=\\\"724\\\" width=\\\"303\\\">\",\n    \"0-1\": \"<br>[<b>&lt;&lt; Variations</b> are defined<br> only in <span class=\\\"inline-code\\\">config.json</span> <br>(not in <span class=\\\"inline-code\\\">schema.json</span>),<br> but always appear at the<br> top of Theme Editor's UI.]<br><br>\\n\\nThe remaining Sections at left<br> correspond to these Section<br> objects defined in <span class=\\\"inline-code\\\">schema.json</span>:\\n<br>\\n\\n<pre>[\\n  {\\n    \\\"name\\\": \\\"Colors\\\",\\n    \\\"settings\\\": [...]\\n  },\\n  {\\n    \\\"name\\\": \\\"Typography\\\",\\n    \\\"settings\\\": [...]\\n  },\\n  {\\n    \\\"name\\\": \\\"Home page\\\",\\n    \\\"settings\\\": [...]\\n  },\\n  {\\n    \\\"name\\\": \\\"Product page\\\",\\n    \\\"settings\\\": [...]\\n  },\\n  {\\n    \\\"name\\\": \\\"Header\\\",\\n    \\\"settings\\\": [...]\\n  },\\n  {\\n    \\\"name\\\": \\\"Footer\\\",\\n    \\\"settings\\\": [...]\\n  }\\n] </pre>\",\n    \"h-0\": \"Theme Editor UI (What a Merchant Sees)\",\n    \"h-1\": \".json Declarations (What You Define)\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"Also, as you'll see below, the options displayed within these expandable Section headings correspond directly to the keys/values that you nest within <span class=\\\"inline-code\\\">schema.json</span>'s corresponding Section objects.<br><br> \\n\\nIn all, the structure that you give your theme's <span class=\\\"inline-code\\\">config.json</span> and <span class=\\\"inline-code\\\">schema.json</span> files directly governs the UI that Theme Editor exposes to merchants. So these files provide your UI design tools.\\n\\n<h2> <a name=\\\"schema-json-data-types\\\"></a> Theme Editor Data Types </h2>\\n\\nTheme editor supports these data types: \\n<ul>\\n\\t<li><span class=\\\"inline-code\\\">color</span></li>\\n\\t<li><span class=\\\"inline-code\\\">font</span></li>\\n\\t<li><span class=\\\"inline-code\\\">select</span> [drop-down list]</li>\\n\\t<li><span class=\\\"inline-code\\\">checkbox</span></li>\\n\\t<li><span class=\\\"inline-code\\\">imageDimension</span></li>\\n\\t<li><span class=\\\"inline-code\\\">text</span></li>\\n  <!-- <li><span class=\\\"inline-code\\\">image</span></li> -->\\n</ul>\\n\\nWithin <span class=\\\"inline-code\\\">schema.json</span>, each object's data type is declared in a statement like the one highlighted here:<br><br>\\n\\n<pre>\\n      {\\n        <b>\\\"type\\\": \\\"color\\\",</b>\\n        \\\"label\\\": \\\"Text Color\\\",\\n        \\\"id\\\": \\\"body-font-color\\\"\\n      },\\n</pre>\\n\\n<h3> <a name=\\\"schema-json-Headings\\\"></a> Types versus \\\"heading\\\" Labels </h3>\\n\\nWithin <span class=\\\"inline-code\\\">schema.json</span>, you will also see <span class=\\\"inline-code\\\">\\\"type\\\": \\\"heading\\\"</span> statements like this one &ndash; highlighted earlier in the same object used for the above example:<br><br>\\n\\n<pre>\\n  {\\n    \\\"name\\\": \\\"Colors\\\",\\n    \\\"settings\\\": [\\n      {\\n        <b>\\\"type\\\": \\\"heading\\\",</b>\\n        \\\"content\\\": \\\"General\\\"\\n      },\\n      {\\n        \\\"type\\\": \\\"color\\\",\\n        \\\"label\\\": \\\"Text Color\\\",\\n        \\\"id\\\": \\\"body-font-color\\\"\\n      },<!-- \\n      {\\n        \\\"type\\\": \\\"color\\\",\\n        \\\"label\\\": \\\"Link Color\\\",\\n        \\\"id\\\": \\\"color-textLink\\\"\\n      }, -->\\n</pre>\\n\\nThese <span class=\\\"inline-code\\\">\\\"type\\\": \\\"heading\\\"</span> statements do not reference data types. Rather, they declare display captions for the Theme Editor UI's subcategories &ndash; the middle level nested within the Section headings, but outside the individual options from which merchants can select. (Those inner options are designated by <span class=\\\"inline-code\\\">\\\"label\\\": <i>&lt;label-text&gt;</i></span> statements.)<br><br> \\n\\nIn all, the hierarchy looks like this:\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<table>\\n  <tr>\\n    <th class=\\\"\\\">UI Hierarchy</th>\\n    <th class=\\\"\\\">schema.json Elements</th>\\n  </tr>\\n  <tr>\\n    <td class=\\\"\\\" align=\\\"right\\\"><br><p></p>\\nSection (object) label &gt;&gt; <br><br><p></p>\\n\\n\\n     <span class=\\\"indent1\\\">Subcategory label &gt;&gt;</span><br><br><br><br><br>\\n\\n\\n\\n          <span class=\\\"indent2\\\">Option label &gt;&gt;</span></td>\\n    <td class=\\\"\\\"><pre>  {\\n    <b>\\\"name\\\": \\\"Colors\\\",</b>\\n    \\\"settings\\\": [\\n      {\\n        <b>\\\"type\\\": \\\"heading\\\",</b>\\n        \\\"content\\\": \\\"General\\\"\\n      },\\n      {\\n        \\\"type\\\": \\\"color\\\",\\n        <b>\\\"label\\\": \\\"Text Color\\\",</b>\\n        \\\"id\\\": \\\"body-font-color\\\"\\n      }, </pre></td>\\n  </tr>\\n</table>\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h2> <a name=\\\"schema-json-Structure\\\"></a> Theme Editor/schema.json Data Structure </h2>\\n\\nThe <span class=\\\"inline-code\\\">schema.json</span> nesting structure that you just saw maps directly to the Theme Editor UI displayed to merchants: Below the <b>Variations</b> Section (whose data are imported from <span class=\\\"inline-code\\\">config.json</span>), the order and nesting of options in Theme Editor's UI directly matches the order and nesting of your <span class=\\\"inline-code\\\">schema.json</span> entries.<br><br>\\n\\nHere is a live example, showing more of the same <span class=\\\"inline-code\\\">Colors</span> object:\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Theme Editor UI (What a Merchant Sees)\",\n    \"h-1\": \".json Declarations (What You Define)\",\n    \"0-1\": \"<pre>  {\\n    <b>\\\"name\\\": \\\"Colors\\\",</b>\\n    \\\"settings\\\": [\\n      {\\n        <b>\\\"type\\\": \\\"heading\\\",</b>\\n        \\\"content\\\": \\\"General\\\"\\n      },\\n      {\\n        \\\"type\\\": \\\"color\\\",\\n        <b>\\\"label\\\": \\\"Text Color\\\",</b>\\n        \\\"id\\\": \\\"body-font-color\\\"\\n      },\\n      {\\n        \\\"type\\\": \\\"color\\\",\\n        <b>\\\"label\\\": \\\"Link Color\\\",</b> [...]      },\\n      {\\n        \\\"type\\\": \\\"color\\\",\\n        <b>\\\"label\\\": \\\"Heading Text Color\\\",</b>  [...]      },\\n      {\\n        <b>\\\"type\\\": \\\"heading\\\",</b>\\n        \\\"content\\\": \\\"Buttons\\\"      },\\n      {\\n        \\\"type\\\": \\\"color\\\",\\n        <b>\\\"label\\\": \\\"Primary Button Background Color\\\",</b>\\n        \\\"id\\\": \\\"buttonStyle-primary-backgroundColor\\\"    },\\n      {\\n        \\\"type\\\": \\\"color\\\",\\n        <b>\\\"label\\\": \\\"Secondary Button Text Color\\\",</b>\\n        \\\"id\\\": \\\"buttonStyle-default-color\\\"      },\\n      {\\n        \\\"type\\\": \\\"color\\\",\\n        <b>\\\"label\\\": \\\"Secondary Button Background Color\\\",</b>\\n        \\\"id\\\": \\\"buttonStyle-default-backgroundColor\\\"\\n      },</pre>\",\n    \"0-0\": \"<br>\\n\\n<img src=\\\"https://files.readme.io/VVA95OWARoGjLgsgHD4k_Theme-Editor~Colors-headings~291x607.png\\\" alt=\\\"Theme Editor subcategories\\\" height=\\\"607\\\" width=\\\"291\\\">\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h2> <a name=\\\"schema-json-Sequence\\\"></a> Arbitrary UI Scope and Sequence </h2>\\n\\nOnce again: You are free to decide which properties of your theme to make editable in Theme Editor, and in which order to display them. Theme Editor can expose any set of properties, as long as your <span class=\\\"inline-code\\\">schema.json</span> declares them using the <a href=\\\"#schema-json-data-types\\\">data types</a> that Theme Editor supports.<br><br>\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h2> <a name=\\\"schema-json-ObjStruct\\\"></a> Object Structure in schema.json </h2>\\n\\nThe following sections provide <span class=\\\"inline-code\\\">schema.json</span> examples for each of the data types that Theme Editor supports.\\n\\n<h3> <a name=\\\"schema-json-Color\\\"></a> Color Example </h3>\\n\\nReferring back to the default <span class=\\\"inline-code\\\">schema.json</span> file's uppermost <b>Colors</b> object, this excerpt shows the structure of elements for the <span class=\\\"inline-code\\\">color</span>type:<br><br>\\n\\n<table>\\n  <tr>\\n    <th class=\\\"\\\">Purpose</th>\\n    <th class=\\\"\\\">schema.json Elements</th>\\n  </tr>\\n  <tr>\\n    <td class=\\\"\\\"><br><p></p>\\nSection (object) label &gt;&gt; <br><br><br><br><p></p>\\n\\n\\n      <span class=\\\"indent1\\\">Subcategory label &gt;&gt;</span><p></p>\\n\\n          <span class=\\\"indent2\\\">[Elements per subcategory option:] &nbsp; &nbsp; </span><p></p>\\n\\n          <span class=\\\"indent2\\\">Data type declaration &gt;&gt;</span><br>\\n\\n          <span class=\\\"indent2\\\">Display label &gt;&gt;</span><br>\\n\\n          <span class=\\\"indent2\\\">ID = name of matching <span class=\\\"inline-code\\\">config.json</span> &gt;&gt;</span><br> \\n            <span class=\\\"indent3\\\">key that provides default value &nbsp; &nbsp; &nbsp; </span><br><p></p>\\n\\n          <span class=\\\"indent2\\\">[Etc.: &gt;&gt;]</span><br><br><br><br><p></p>\\n\\n          <span class=\\\"indent2\\\">[Etc.: &gt;&gt;]</span>\\n    </td>\\n\\n    <td class=\\\"\\\"><pre>  {\\n    <b>\\\"name\\\": \\\"Colors\\\",</b>\\n    \\\"settings\\\": [\\n     ...\\n      {\\n        \\\"type\\\": \\\"heading\\\",\\n        <b>\\\"content\\\": \\\"Buttons\\\"</b>\\n      },\\n      {\\n        \\\"type\\\": \\\"color\\\",\\n        \\\"label\\\": \\\"Primary Button Background Color\\\",\\n        \\\"id\\\": \\\"buttonStyle-primary-backgroundColor\\\"\\n      },\\n      {\\n        \\\"type\\\": \\\"color\\\",\\n        \\\"label\\\": \\\"Secondary Button Text Color\\\",\\n        \\\"id\\\": \\\"buttonStyle-default-color\\\"\\n      },\\n      {\\n        \\\"type\\\": \\\"color\\\",\\n        \\\"label\\\": \\\"Secondary Button Background Color\\\",\\n        \\\"id\\\": \\\"buttonStyle-default-backgroundColor\\\"\\n      },</pre></td>\\n  </tr>\\n</table>\\n\\nThe code outlined above generates the Theme Editor panel shown here:  \"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<table>\\n  <tr>\\n    <th class=\\\"\\\">Theme Editor UI</th>\\n    <th class=\\\"\\\">schema.json Elements</th>\\n  </tr>\\n  <tr>\\n    <td class=\\\"\\\"> <img src=\\\"https://files.readme.io/vW49lolsQauuUSzSPPXL_Colors-Heading~291w-x-71h.png\\\" alt=\\\"Colors heading\\\">\\n      <br><p></p>      \\n      <span class=\\\"indent1\\\">[...]</span><br><br><br>\\n<img src=\\\"https://files.readme.io/IA1mvTJSJyPfRhzBN5gT_Color-Swatches:::at:::286x248.png\\\" alt=\\\"Color &gt; Buttons UI controls\\\">\\n    </td>\\n\\n    <td class=\\\"\\\"><pre>  {\\n    <b>\\\"name\\\": \\\"Colors\\\",</b>\\n    \\\"settings\\\": [\\n     ...\\n      {\\n        \\\"type\\\": \\\"heading\\\",\\n        <b>\\\"content\\\": \\\"Buttons\\\"</b>\\n      },\\n      {\\n        \\\"type\\\": \\\"color\\\",\\n        \\\"label\\\": \\\"Primary Button Background Color\\\",\\n        \\\"id\\\": \\\"buttonStyle-primary-backgroundColor\\\"\\n      },\\n      {\\n        \\\"type\\\": \\\"color\\\",\\n        \\\"label\\\": \\\"Secondary Button Text Color\\\",\\n        \\\"id\\\": \\\"buttonStyle-default-color\\\"\\n      },\\n      {\\n        \\\"type\\\": \\\"color\\\",\\n        \\\"label\\\": \\\"Secondary Button Background Color\\\",\\n        \\\"id\\\": \\\"buttonStyle-default-backgroundColor\\\"\\n      },</pre></td>\\n  </tr>\\n</table>\\n\\nAbove, each option's color swatch corresponds to the corresponding <span class=\\\"inline-code\\\">config.json</span> key's color value. Theme Editor users can select/click each swatch to open a Color Picker dialog, to redefine the corresponding theme feature's color.<br><br>\\n\\nYou can find more examples of <span class=\\\"inline-code\\\">color</span> elements in the default <span class=\\\"inline-code\\\">schema.json</span> file's <b>Header</b> and <b>Footer</b> objects.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h3> <a name=\\\"schema-json-FontSelect\\\"></a> Font and Select (Drop-Down List) Examples </h3>\\n\\nIn the default Stencil theme's <span class=\\\"inline-code\\\">schema.json</span>, the head of the <b>Typography</b> object shows the structure of both the <span class=\\\"inline-code\\\">font</span> and <span class=\\\"inline-code\\\">select</span> data types, which work similarly:\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<table>\\n  <tr>\\n    <th class=\\\"\\\">Purpose</th>\\n    <th class=\\\"\\\">schema.json Elements</th>\\n  </tr>\\n  <tr>\\n    <td class=\\\"\\\"><br><p></p>\\nSection (object) label &gt;&gt; <br><br><br><p></p>\\n\\n\\n      <span class=\\\"indent1\\\">Subcategory label &gt;&gt;</span><p></p>\\n\\n          <span class=\\\"indent2\\\">[Elements per subcategory option:] &nbsp; &nbsp; </span><p></p>\\n\\n          <span class=\\\"indent2\\\">Data type declaration &gt;&gt;</span><br>\\n\\n          <span class=\\\"indent2\\\">Display label &gt;&gt;</span><br>\\n\\n          <span class=\\\"indent2\\\">ID that matches a <span class=\\\"inline-code\\\">config.json</span> key name &gt;&gt;</span><br> \\n\\n      <span class=\\\"indent2\\\">Options = alternate choices to display &gt;&gt;</span><br> \\n      <span class=\\\"indent3\\\">on drop-down list &nbsp; &nbsp; </span><br><br><br><br><p></p>\\n\\n      <span class=\\\"indent3\\\">Group = option's display position &nbsp; &nbsp; </span><br>\\n      <span class=\\\"indent4\\\">on drop-down list &gt;&gt;</span><br>\\n      \\n      <span class=\\\"indent3\\\">Option's display label &gt;&gt;</span><br>\\n      <span class=\\\"indent3\\\">Corresponding font value, in a <a href=\\\"/docs/configjson-reference#config-json-fonts\\\">defined format</a> &gt;&gt;</span><br><br><p></p>\\n      \\n          <span class=\\\"indent3\\\">[Etc., for remaining options on same &gt;&gt;</span><br>\\n          <span class=\\\"indent4\\\">drop-down list] &nbsp; &nbsp; </span>\\n<br><br><br>\\n<br><br><p></p>\\n      \\n\\n      <span class=\\\"indent2\\\">Data type declaration (for <span class=\\\"inline-code\\\">select</span> type) &gt;&gt;</span><br>\\n\\n          <span class=\\\"indent2\\\">Display label &gt;&gt;</span><br>\\n\\n          <span class=\\\"indent2\\\">ID that matches a <span class=\\\"inline-code\\\">config.json</span> key name &gt;&gt;</span><br> \\n\\n      <span class=\\\"indent2\\\">Options = alternate choices to display &gt;&gt;</span><br> \\n      <span class=\\\"indent3\\\">on drop-down list &nbsp; &nbsp; &nbsp; </span><br><br><br><br>\\n\\n      <span class=\\\"indent3\\\">Value for this option &gt;&gt;</span><br>\\n\\n      <span class=\\\"indent3\\\">Display label for this option &gt;&gt;</span><br><br><br><br>\\n\\n          <span class=\\\"indent3\\\">[Etc., for remaining options on same &gt;&gt;</span><br>\\n          <span class=\\\"indent4\\\">drop-down list] &nbsp; &nbsp; </span>      \\n      \\n</td>\\n\\n    <td class=\\\"\\\"><pre>  {\\n    <b>\\\"name\\\": \\\"Typography\\\",</b>\\n    \\\"settings\\\": [\\n      {\\n        \\\"type\\\": \\\"heading\\\",\\n        <b>\\\"content\\\": \\\"Base typeface\\\"</b>\\n      },\\n      {\\n        <b>\\\"type\\\": \\\"font\\\",\\n        \\\"label\\\": \\\"Font Family\\\",\\n        \\\"id\\\": \\\"body-font\\\",\\n        \\\"options\\\": [</b>\\n          {\\n            \\\"group\\\": \\\"Open Sans\\\",\\n            \\\"label\\\": \\\"Open Sans\\\",\\n            \\\"value\\\": \\\"Google_Open+Sans\\\"\\n          },\\n          {\\n            <b>\\\"group\\\": \\\"Open Sans\\\",\\n            \\\"label\\\": \\\"Open Sans Bold\\\",\\n            \\\"value\\\": \\\"Google_Open+Sans_700\\\"</b>\\n          },\\n          {\\n            \\\"group\\\": \\\"Karla\\\",\\n            \\\"label\\\": \\\"Karla\\\",\\n            \\\"value\\\": \\\"Google_Karla\\\"\\n          }\\n        ]\\n      },\\n      {\\n        <b>\\\"type\\\": \\\"select\\\",\\n        \\\"label\\\": \\\"Font Size\\\",\\n        \\\"id\\\": \\\"fontSize-base\\\",\\n        \\\"options\\\": [</b>\\n          {\\n            \\\"value\\\": 10,\\n            \\\"label\\\": \\\"10px\\\"\\n          },\\n          {\\n            \\\"value\\\": 11,\\n            \\\"label\\\": \\\"11px\\\"\\n          },\\n[...]          \\n          {\\n            \\\"value\\\": 16,\\n            \\\"label\\\": \\\"16px\\\"\\n          }\\n        ]\\n      },\\n</pre></td>\\n  </tr>\\n</table>\\n\\nThe code outlined above generates the set of Theme Editor UI features expanded below:  \"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<table>\\n  <tr>\\n    <th class=\\\"\\\">Theme Editor UI</th>\\n    <th class=\\\"\\\">schema.json Elements</th>\\n  </tr>\\n  <tr>\\n    <td class=\\\"\\\"> <!-- <img src=\\\"https://files.readme.io/aS9AuQyST2p9jG8pBDDO_Typography-long-panel~281w-x-688h.png\\\" alt=\\\"Typography (Fonts) UI controls\\\"> -->\\n      <img src=\\\"https://files.readme.io/7diRZtBaTaBmrWPFkJ37_Typography-Head-only~77h-x-291w.png\\\" alt=\\\"Typography (Fonts) heading\\\">\\n      <br><br><br><br><br><br><br>\\n     <img src=\\\"https://files.readme.io/jFKR3TleTMLY8989AIQj_Typography-Family-only~125h-x-292w.png\\\" alt=\\\"font (family) UI control\\\"> \\n      <br><br><br><br><br><br><br><br><br><br>\\n    <img src=\\\"https://files.readme.io/UvfaM3LBQ0a13DETFUWJ_Typography-Size-only~187h-x-291w.png\\\" alt=\\\"select (font-size) drop-down list\\\">\\n    </td>\\n\\n    <td class=\\\"\\\"><pre>  {\\n    <b>\\\"name\\\": \\\"Typography\\\",</b>\\n    \\\"settings\\\": [\\n[...]<!--              \\n      {\\n        \\\"type\\\": \\\"heading\\\",\\n        \\\"content\\\": \\\"Base typeface\\\"\\n      }, -->\\n      {\\n        <b>\\\"type\\\": \\\"font\\\",</b>\\n        \\\"label\\\": \\\"Font Family\\\",\\n        \\\"id\\\": \\\"body-font\\\",\\n        \\\"options\\\": [\\n          <b>{\\n            \\\"group\\\": \\\"Open Sans\\\",\\n            \\\"label\\\": \\\"Open Sans\\\",\\n            \\\"value\\\": \\\"Google_Open+Sans\\\"\\n          },\\n          {\\n            \\\"group\\\": \\\"Open Sans\\\",\\n            \\\"label\\\": \\\"Open Sans Bold\\\",\\n            \\\"value\\\": \\\"Google_Open+Sans_700\\\"\\n          },\\n          {\\n            \\\"group\\\": \\\"Karla\\\",\\n            \\\"label\\\": \\\"Karla\\\",\\n            \\\"value\\\": \\\"Google_Karla\\\"\\n          }</b>\\n[...]<!--                        \\n        ]\\n      }, -->\\n      {\\n        <b>\\\"type\\\": \\\"select\\\",\\n        \\\"label\\\": \\\"Font Size\\\",</b>\\n        \\\"id\\\": \\\"fontSize-base\\\",\\n        \\\"options\\\": [\\n          <b>{\\n            \\\"value\\\": 10,\\n            \\\"label\\\": \\\"10px\\\"\\n          },\\n          {\\n            \\\"value\\\": 11,\\n            \\\"label\\\": \\\"11px\\\"\\n          },</b>\\n[...] <!--     \\n          {\\n            \\\"value\\\": 12,\\n            \\\"label\\\": \\\"12px\\\"\\n          },\\n          {\\n            \\\"value\\\": 13,\\n            \\\"label\\\": \\\"13px\\\"\\n          },\\n          {\\n            \\\"value\\\": 14,\\n            \\\"label\\\": \\\"14px\\\"\\n          },\\n          {\\n            \\\"value\\\": 15,\\n            \\\"label\\\": \\\"15px\\\"\\n          }, -->\\n          <b>{\\n            \\\"value\\\": 16,\\n            \\\"label\\\": \\\"16px\\\"\\n          }</b>\\n[...] <!--     \\n        ]\\n      }, --></pre></td>\\n  </tr>\\n</table>\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h3> <a name=\\\"schema-json-FontVsSelect\\\"></a> Font versus Select Types </h3>\\n\\nAs you've just seen, <span class=\\\"inline-code\\\">font</span> elements and <span class=\\\"inline-code\\\">select</span> elements each declare drop-down lists. But <span class=\\\"inline-code\\\">font</span> elements have some additional options and requirements:\\n\\n<ul>\\n<li>Within each <span class=\\\"inline-code\\\">font</span> family element, a <span class=\\\"inline-code\\\">group</span> sub-element is recommended (although not required). <NOBR>These <span class=\\\"inline-code\\\">group</span> sub-elements</nobr> promote orderly drop-down lists, as you can see in the screenshot above: <NOBR>They cause</nobr> Theme Editor to group related fonts together, under a subheading that matches their shared <span class=\\\"inline-code\\\">group</span> identifier.</li>\\n\\n<li>For each <span class=\\\"inline-code\\\">font</span> family element, the <span class=\\\"inline-code\\\">id</span>\\nelement must name a <span class=\\\"inline-code\\\">config.json</span> key that sets the default family, <NOBR>in a</nobr> <a href=\\\"/docs/configjson-reference#config-json-fonts\\\">defined format</a>.</li>\\n\\n<li>Your theme's <a href=\\\"/docs/settings-directory#SassFontFns\\\">Sass stylesheet</a> must call Stencil's custom Sass functions to transform the fonts specified in <span class=\\\"inline-code\\\">config.json</span>.</li>\\n</ul>\\n\\n<h3> <a name=\\\"schema-json-PgLayout\\\"></a> Page Layout Options using Select Elements </h3>\\n\\nThe default <span class=\\\"inline-code\\\">schema.json</span> file's <b>Home page</b> and <b>Product page</b> Sections provide examples of how you can use <span class=\\\"inline-code\\\">select</span> elements to offer merchants drop-down lists to customize their storefront pages' layouts.<br><br>\\n\\nThe code excerpts below (note the \\\"<span class=\\\"inline-code\\\">...</span>\\\" ellipses) declare <NOBR><b>Home page</b></nobr> drop-down lists for customizing the number of objects displayed in four page panels. Such controls allow merchants to override your front-matter and Handlebars defaults, without needing to do any coding:\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<table>\\n  <tr>\\n    <th class=\\\"\\\">Theme Editor UI</th>\\n    <th class=\\\"\\\">schema.json Elements</th>\\n  </tr>\\n  <tr>\\n    <td class=\\\"\\\"> <img src=\\\"https://files.readme.io/p2eAJoNRmmRH31FFBqRX_Homepage~Theme-Editor-full-panel~512h-x-289w.png\\\" alt=\\\"Home page UI controls\\\">\\n    </td>\\n\\n    <td class=\\\"\\\"><pre>  {\\n    <b>\\\"name\\\": \\\"Home page\\\",\\n    \\\"settings\\\": [</b>\\n      {\\n        <b>\\\"type\\\": \\\"select\\\",\\n        \\\"label\\\": \\\"Number of Featured Products\\\",</b>\\n        \\\"id\\\": \\\"homepage_featured_products_count\\\",\\n        \\\"options\\\": [ ... <!--\\n          {\\n            \\\"value\\\": 0,\\n            \\\"label\\\": \\\"Disable\\\"\\n          },\\n          {\\n            \\\"value\\\": 1,\\n            \\\"label\\\": \\\"1\\\"\\n          },\\n          {\\n            \\\"value\\\": 2,\\n            \\\"label\\\": \\\"2\\\"\\n          },\\n          {\\n            \\\"value\\\": 3,\\n            \\\"label\\\": \\\"3\\\"\\n          },\\n          {\\n            \\\"value\\\": 4,\\n            \\\"label\\\": \\\"4\\\"\\n          },\\n          {\\n            \\\"value\\\": 5,\\n            \\\"label\\\": \\\"5\\\"\\n          },\\n          {\\n            \\\"value\\\": 6,\\n            \\\"label\\\": \\\"6\\\"\\n          },\\n          {\\n            \\\"value\\\": 7,\\n            \\\"label\\\": \\\"7\\\"\\n          },\\n          {\\n            \\\"value\\\": 8,\\n            \\\"label\\\": \\\"8\\\"\\n          },\\n          {\\n            \\\"value\\\": 9,\\n            \\\"label\\\": \\\"9\\\"\\n          },\\n          {\\n            \\\"value\\\": 10,\\n            \\\"label\\\": \\\"10\\\"\\n          },\\n          {\\n            \\\"value\\\": 11,\\n            \\\"label\\\": \\\"11\\\"\\n          },\\n          {\\n            \\\"value\\\": 12,\\n            \\\"label\\\": \\\"12\\\"\\n          } \\n        -->]\\n      },\\n      {\\n        <b>\\\"type\\\": \\\"select\\\",\\n        \\\"label\\\": \\\"Number of Most Popular Products\\\",</b>\\n        \\\"id\\\": \\\"homepage_top_products_count\\\",\\n        \\\"options\\\": [ ... <!--\\n          {\\n            \\\"value\\\": 0,\\n            \\\"label\\\": \\\"Disable\\\"\\n          },\\n          {\\n            \\\"value\\\": 1,\\n            \\\"label\\\": \\\"1\\\"\\n          },\\n          {\\n            \\\"value\\\": 2,\\n            \\\"label\\\": \\\"2\\\"\\n          },\\n          {\\n            \\\"value\\\": 3,\\n            \\\"label\\\": \\\"3\\\"\\n          },\\n          {\\n            \\\"value\\\": 4,\\n            \\\"label\\\": \\\"4\\\"\\n          },\\n          {\\n            \\\"value\\\": 5,\\n            \\\"label\\\": \\\"5\\\"\\n          },\\n          {\\n            \\\"value\\\": 6,\\n            \\\"label\\\": \\\"6\\\"\\n          },\\n          {\\n            \\\"value\\\": 7,\\n            \\\"label\\\": \\\"7\\\"\\n          },\\n          {\\n            \\\"value\\\": 8,\\n            \\\"label\\\": \\\"8\\\"\\n          },\\n          {\\n            \\\"value\\\": 9,\\n            \\\"label\\\": \\\"9\\\"\\n          },\\n          {\\n            \\\"value\\\": 10,\\n            \\\"label\\\": \\\"10\\\"\\n          },\\n          {\\n            \\\"value\\\": 11,\\n            \\\"label\\\": \\\"11\\\"\\n          },\\n          {\\n            \\\"value\\\": 12,\\n            \\\"label\\\": \\\"12\\\"\\n          }\\n        -->]\\n      },\\n      {\\n        <b>\\\"type\\\": \\\"select\\\",\\n        \\\"label\\\": \\\"Number of New Products\\\",</b>\\n        \\\"id\\\": \\\"homepage_new_products_count\\\",\\n        \\\"options\\\": [ ... <!--\\n          {\\n            \\\"value\\\": 0,\\n            \\\"label\\\": \\\"Disable\\\"\\n          },\\n          {\\n            \\\"value\\\": 1,\\n            \\\"label\\\": \\\"1\\\"\\n          },\\n          {\\n            \\\"value\\\": 2,\\n            \\\"label\\\": \\\"2\\\"\\n          },\\n          {\\n            \\\"value\\\": 3,\\n            \\\"label\\\": \\\"3\\\"\\n          },\\n          {\\n            \\\"value\\\": 4,\\n            \\\"label\\\": \\\"4\\\"\\n          },\\n          {\\n            \\\"value\\\": 5,\\n            \\\"label\\\": \\\"5\\\"\\n          },\\n          {\\n            \\\"value\\\": 6,\\n            \\\"label\\\": \\\"6\\\"\\n          },\\n          {\\n            \\\"value\\\": 7,\\n            \\\"label\\\": \\\"7\\\"\\n          },\\n          {\\n            \\\"value\\\": 8,\\n            \\\"label\\\": \\\"8\\\"\\n          },\\n          {\\n            \\\"value\\\": 9,\\n            \\\"label\\\": \\\"9\\\"\\n          },\\n          {\\n            \\\"value\\\": 10,\\n            \\\"label\\\": \\\"10\\\"\\n          },\\n          {\\n            \\\"value\\\": 11,\\n            \\\"label\\\": \\\"11\\\"\\n          },\\n          {\\n            \\\"value\\\": 12,\\n            \\\"label\\\": \\\"12\\\"\\n          -->}\\n        ]\\n      },\\n      {\\n        <b>\\\"type\\\": \\\"select\\\",\\n        \\\"label\\\": \\\"Number of Blog Posts\\\",</b>\\n        \\\"id\\\": \\\"homepage_blog_posts_count\\\",\\n        \\\"options\\\": [ ... <!--\\n          {\\n            \\\"value\\\": 0,\\n            \\\"label\\\": \\\"Disable\\\"\\n          },\\n          {\\n            \\\"value\\\": 1,\\n            \\\"label\\\": \\\"1\\\"\\n          },\\n          {\\n            \\\"value\\\": 2,\\n            \\\"label\\\": \\\"2\\\"\\n          },\\n          {\\n            \\\"value\\\": 3,\\n            \\\"label\\\": \\\"3\\\"\\n          },\\n          {\\n            \\\"value\\\": 4,\\n            \\\"label\\\": \\\"4\\\"\\n          },\\n          {\\n            \\\"value\\\": 5,\\n            \\\"label\\\": \\\"5\\\"\\n          },\\n          {\\n            \\\"value\\\": 6,\\n            \\\"label\\\": \\\"6\\\"\\n          },\\n          {\\n            \\\"value\\\": 7,\\n            \\\"label\\\": \\\"7\\\"\\n          },\\n          {\\n            \\\"value\\\": 8,\\n            \\\"label\\\": \\\"8\\\"\\n          },\\n          {\\n            \\\"value\\\": 9,\\n            \\\"label\\\": \\\"9\\\"\\n          },\\n          {\\n            \\\"value\\\": 10,\\n            \\\"label\\\": \\\"10\\\"\\n          },\\n          {\\n            \\\"value\\\": 11,\\n            \\\"label\\\": \\\"11\\\"\\n          },\\n          {\\n            \\\"value\\\": 12,\\n            \\\"label\\\": \\\"12\\\"\\n          }\\n        -->]\\n      },\\n    ]\\n  },</pre></td>\\n  </tr>\\n</table>\\n\\nThis next snippet expands more of the code that declares the first (<b>Number of Featured Products</b>) drop-down list. As in the <b>Typography</b> examples, the <span class=\\\"inline-code\\\">id</span> sub-element must name a <span class=\\\"inline-code\\\">config.json</span> key that manages the theme property's default value.<br><br>\\n\\nNote how the initial <span class=\\\"inline-code\\\">\\\"value\\\": 0</span> option is accompanied by a <NOBR><span class=\\\"inline-code\\\">\\\"label\\\": \\\"Disable\\\"</span></nobr> tag, which offers end users a more meaningful display of its numeric value:\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<table>\\n  <tr>\\n    <th class=\\\"\\\">Theme Editor UI</th>\\n    <th class=\\\"\\\">schema.json Elements</th>\\n  </tr>\\n  <tr>\\n    <td class=\\\"\\\"><br> <img src=\\\"https://files.readme.io/g2KFesoFSludlXfiy6sf_Homepage~Theme-Editor-1st-droplist~368h-x-291w.png\\\" alt=\\\"Home page &ndash; Featured Products UI control\\\">\\n    </td>\\n\\n    <td class=\\\"\\\"><pre>  {\\n    <b>\\\"name\\\": \\\"Home page\\\",</b>\\n    \\\"settings\\\": [\\n      {\\n        <b>\\\"type\\\": \\\"select\\\",\\n        \\\"label\\\": \\\"Number of Featured Products\\\",</b>\\n        \\\"id\\\": \\\"homepage_featured_products_count\\\",\\n        <!-- \\\"force_reload\\\": true, -->\\n        \\\"options\\\": [\\n          {\\n            <b>\\\"value\\\": 0,\\n            \\\"label\\\": \\\"Disable\\\"</b>\\n          },\\n          {\\n            \\\"value\\\": 1,\\n            \\\"label\\\": \\\"1\\\"\\n          },\\n          {\\n            \\\"value\\\": 2,\\n            \\\"label\\\": \\\"2\\\"\\n          }, <!--\\n          {\\n            \\\"value\\\": 3,\\n            \\\"label\\\": \\\"3\\\"\\n          },\\n          {\\n            \\\"value\\\": 4,\\n            \\\"label\\\": \\\"4\\\"\\n          },\\n          {\\n            \\\"value\\\": 5,\\n            \\\"label\\\": \\\"5\\\"\\n          },\\n          {\\n            \\\"value\\\": 6,\\n            \\\"label\\\": \\\"6\\\"\\n          },\\n          {\\n            \\\"value\\\": 7,\\n            \\\"label\\\": \\\"7\\\"\\n          },\\n          {\\n            \\\"value\\\": 8,\\n            \\\"label\\\": \\\"8\\\"\\n          },\\n          {\\n            \\\"value\\\": 9,\\n            \\\"label\\\": \\\"9\\\"\\n          },\\n          {\\n            \\\"value\\\": 10,\\n            \\\"label\\\": \\\"10\\\"\\n          },\\n          {\\n            \\\"value\\\": 11,\\n            \\\"label\\\": \\\"11\\\"\\n          }, -->\\n[...]          \\n          {\\n            \\\"value\\\": 12,\\n            \\\"label\\\": \\\"12\\\"\\n          }\\n        ]\\n      },</pre></td>\\n  </tr>\\n</table>\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h3> <a name=\\\"schema-json-Chkbox\\\"></a> Checkbox Examples </h3>\\n\\nThe <span class=\\\"inline-code\\\">checkbox</span> data type displays a check box in the Theme Editor UI, allowing users to toggle a boolean property.<br><p></p>\\n\\n<!-- \\\"(!)\\\" Callout; Titled: \\\"In Development\\\"; Body: \\nAs of this draft, the <span class=\\\"inline-code\\\">checkbox</span> data type is still in development. It *can* be used to display a check box in the Theme Editor UI. However, clicking the check box does not toggle the specified theme property. Rather, it causes the browser window/tab to hang, requiring the user to manually refresh that window/tab. \\nUpon refresh, the selected property will revert to its previous state. -->\\n\\nHere is an example that you could place within your <span class=\\\"inline-code\\\">schema.json</span>'s <b>Home page</b> Section, to enable merchants to easily toggle the theme's image carousel on/off:<br><br>\\n\\n<table>\\n  <tr>\\n    <th class=\\\"\\\">Theme Editor UI</th>\\n    <th class=\\\"\\\">schema.json Elements</th>\\n  </tr>\\n  <tr>\\n    <td class=\\\"\\\"> <img src=\\\"https://files.readme.io/A8Mr4mkTRJoOMlNaayAb_Carousel-UI~only~120h-x-292w.png\\\" alt=\\\"Home page &ndash; Carousel On/Off check box\\\">\\n       <!-- <img src=\\\"https://files.readme.io/EHhnetzUTavIeUS5TBFG_Carousel-UI~isolated~181h-x-291w.png\\\" alt=\\\"Home page &ndash; Carousel On/Off check box\\\">\\n       <img src=\\\"https://files.readme.io/nwEFK3APRDCT6Rq9awBE_Carousel-UI~in-context~252h-x-289-w.png\\\" alt=\\\"Home page &ndash; Carousel On/Off check box\\\"> -->\\n    </td>\\n\\n    <td class=\\\"\\\"><pre>      {\\n        \\\"type\\\": \\\"checkbox\\\",\\n        \\\"id\\\": \\\"homepage_show_carousel\\\",\\n        \\\"label\\\": \\\"Carousel On/Off\\\"\\n      }</pre></td>\\n  </tr>\\n</table>\\n\\n<h4> <a name=\\\"schema-json-config\\\"></a> Dependency on config.json </h4>\\n\\nAs in preceding examples, the <span class=\\\"inline-code\\\">id</span> sub-element must name a <span class=\\\"inline-code\\\">config.json</span> key that manages the theme property's default value. Here, <span class=\\\"inline-code\\\">config.json</span> would assign one of these values to its <span class=\\\"inline-code\\\">homepage_show_carousel</span> key: \\n\\n<ul>\\n\\t<li><span class=\\\"inline-code\\\">true</span> (check box selected, property enabled)</li> \\n  \\n  <li><span class=\\\"inline-code\\\">false</span> (check box deselected, property disabled).</li>\\n</ul>\\n<br>\\n\\n<h4> <a name=\\\"schema-json-config\\\"></a> \\\"Powered by\\\" and Payment Toggle Examples </h4>\\n\\nA common use of the <span class=\\\"inline-code\\\">checkbox</span> type is to allow merchants to toggle on/off the \\\"Powered by BigCommerce\\\" credit in the storefront's footer. Here is the relevant code, which writes to <span class=\\\"inline-code\\\">config.json</span>'s <span class=\\\"inline-code\\\">show_powered_by</span> key:<br><br>\\n\\n<table>\\n  <tr>\\n    <th class=\\\"\\\">Theme Editor UI</th>\\n    <th class=\\\"\\\">schema.json Elements</th>\\n  </tr>\\n  <tr>\\n    <td class=\\\"\\\"> <br><br><img src=\\\"https://files.readme.io/cOsFRG3R67y2gnRvOI9A_25282-Theme-Ed~Powered-By.png\\\" alt=\\\"Footer &ndash; Site credit On/Off check box\\\">\\n    </td>\\n\\n    <td class=\\\"\\\"><pre>      {\\n    \\\"name\\\": \\\"Footer\\\",\\n    \\\"settings\\\": [\\n      {\\n        [...]\\n      },\\n      {\\n        \\\"type\\\": \\\"checkbox\\\",\\n        \\\"label\\\": \\\"Show Powered By\\\",\\n        \\\"force_reload\\\": true,\\n        \\\"id\\\": \\\"show_powered_by\\\"\\n      }\\n    ]\\n  },\\n</pre></td>\\n  </tr>\\n</table>\\n\\n<!-- <img src=\\\"https://files.readme.io/aIVsL7lzS7eNRyqYYaZR_25285-Theme-Ed~Payment-Icons~Cropped.png\\\" alt=\\\"Footer &ndash; Payment Icons check boxes\\\"> -->\\n\\nPayment-method icons can be toggled on/off in the same way, by writing to the <span class=\\\"inline-code\\\">Payment Icons</span>  section's <NOBR><span class=\\\"inline-code\\\">show_accept_paypal</span>,</nobr> <NOBR><span class=\\\"inline-code\\\">show_accept_visa</span>,</nobr> etc., keys.\\n\\n<h3> <a name=\\\"schema-json-ImageDim\\\"></a> imageDimension Examples </h3>\\n\\n<h4> Logo Example </h4>\\n\\nIn the default Stencil theme's <span class=\\\"inline-code\\\">schema.json</span>, the <span class=\\\"inline-code\\\">Logo</span> object demonstrates the <span class=\\\"inline-code\\\">imageDimension</span> data type. <NOBR>This type's</nobr> <span class=\\\"inline-code\\\">schema.json</span> value will normally default to the corresponding <span class=\\\"inline-code\\\">logo_size</span> default value in <span class=\\\"inline-code\\\">config.json</span>. (In this example, the value is <span class=\\\"inline-code\\\">\\\"250x100\\\"</span>, and is labeled <span class=\\\"inline-code\\\">\\\"Optimized for theme\\\"</span>.)<br><p></p>\\n\\nHowever, if the <span class=\\\"inline-code\\\">config.json</span> default is not present in <span class=\\\"inline-code\\\">schema.json</span> as a selectable value, Theme Editor will instead fall back to showing users the <span class=\\\"inline-code\\\">\\\"custom\\\"</span> value (labeled <span class=\\\"inline-code\\\">\\\"Specify dimensions\\\"</span> in the code example below).\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"The <span class=\\\"inline-code\\\">config.json</span> default value for an <span class=\\\"inline-code\\\">imageDimension</span> type is a string. It can be either <span class=\\\"inline-code\\\">\\\"original\\\"</span>, or horizontal x vertical dimensions in the format <span class=\\\"inline-code\\\">\\\"*#* x *#*\\\"</span>.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"The <span class=\\\"inline-code\\\">description</span> field's presence is optional, but if you include it within <span class=\\\"inline-code\\\">schema.json</span>'s <span class=\\\"inline-code\\\">Logo</span> object (to provide user instructions), you must populate it. Theme Editor displays entry boxes that record the user's <i>maximum</i> width and height selections for the image, while enforcing the image's original aspect ratio.<br><br>\\n\\n<table>\\n  <tr>\\n    <th class=\\\"\\\">Theme Editor UI</th>\\n    <th class=\\\"\\\">schema.json Elements</th>\\n  </tr>\\n  <tr>\\n    <td class=\\\"\\\"> [Image to follow.]\\n    </td>\\n\\n    <td class=\\\"\\\"><pre>      {\\n    \\\"name\\\": \\\"Logo\\\",\\n    \\\"settings\\\": [\\n      {\\n        \\\"type\\\": \\\"imageDimension\\\",\\n        \\\"label\\\": \\\"Logo size\\\",\\n        \\\"id\\\": \\\"logo_size\\\",\\n        \\\"description\\\": \\\"Please specify a maximum image size for desktop display. We'll automatically scale down the image for smaller devices.\\\",\\n        \\\"force_reload\\\": true,\\n        \\\"options\\\": [\\n          {\\n            \\\"value\\\": \\\"original\\\",\\n            \\\"label\\\": \\\"Original (as uploaded)\\\"\\n          },\\n          {\\n            \\\"value\\\": \\\"250x100\\\",\\n            \\\"label\\\": \\\"Optimized for theme\\\"\\n          },\\n          {\\n            \\\"value\\\": \\\"custom\\\",\\n            \\\"label\\\": \\\"Specify dimensions\\\"\\n          }\\n        ]\\n      },\\n\\t\\t</pre></td>\\n  </tr>\\n</table>\\n\\n<h4> Product Example </h4>\\n\\nBelow are several more examples of the <span class=\\\"inline-code\\\">imageDimension</span> data type, from the default Stencil theme's <span class=\\\"inline-code\\\">Product</span> object. Here, Theme Editor uses the <span class=\\\"inline-code\\\">imageDimension</span> type to expose and update several default sizes stored in <span class=\\\"inline-code\\\">config.json</span>.<br><p></p>\\n\\nThe <span class=\\\"inline-code\\\">imageDimension</span> type here behaves as in the <span class=\\\"inline-code\\\">Logo</span> example: Theme Editor will normally default to the <span class=\\\"inline-code\\\">\\\"Optimized for theme\\\"</span> value, corresponding to a <span class=\\\"inline-code\\\">config.json</span> default value. However, if the <span class=\\\"inline-code\\\">config.json</span> default is absent in <span class=\\\"inline-code\\\">schema.json</span>, Theme Editor will instead fall back to showing users the <span class=\\\"inline-code\\\">\\\"custom\\\"</span> value. Here again, the entry boxes record maximum dimensions, and Theme Editor enforces the image's original aspect ratio.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Hide \\\"original\\\"–Sized Product Images\",\n  \"body\": \"For the <span class=\\\"inline-code\\\">Product</span> object's contained <span class=\\\"inline-code\\\">imageDimension</span> types, we recommend that your shipped <span class=\\\"inline-code\\\">config.json</span> *not* save <span class=\\\"inline-code\\\">original</span> as the default value, and that your <span class=\\\"inline-code\\\">schema.json</span> *not* display <span class=\\\"inline-code\\\">original</span> as a selectable value. \\n\\nProducts' original images tend to be large, so showing them on the storefront at native resolution would slow pages' load times. The safe choices for Product are <span class=\\\"inline-code\\\">\\\"Optimized for theme\\\"</span> and a judicious <span class=\\\"inline-code\\\">\\\"custom\\\"</span>.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"The <span class=\\\"inline-code\\\">Product</span> object here has a single <span class=\\\"inline-code\\\">content</span> field, which behaves like the <span class=\\\"inline-code\\\">Logo</span> object's <span class=\\\"inline-code\\\">description</span> field: <NOBR>Its presence</nobr> is optional, but if you include it in the object, you must populate it.<br><br>\\n\\n<table>\\n  <tr>\\n    <th class=\\\"\\\">Theme Editor UI</th>\\n    <th class=\\\"\\\">schema.json Elements</th>\\n  </tr>\\n  <tr>\\n    <td class=\\\"\\\"> [Image to follow.]\\n    </td>\\n\\n    <td class=\\\"\\\"><pre>      {\\n        \\\"type\\\": \\\"heading\\\",\\n        \\\"content\\\": \\\"Image sizes\\\"\\n      },\\n      {\\n        \\\"type\\\": \\\"paragraph\\\",\\n        \\\"content\\\": \\\"Please specify a maximum image size for desktop display. We'll automatically scale down the image for smaller devices.\\\"\\n      },\\n      {\\n        \\\"type\\\": \\\"imageDimension\\\",\\n        \\\"label\\\": \\\"Main product images\\\",\\n        \\\"id\\\": \\\"product_size\\\",\\n        \\\"force_reload\\\": true,\\n        \\\"options\\\": [\\n          {\\n            \\\"value\\\": \\\"500x659\\\",\\n            \\\"label\\\": \\\"Optimized for theme\\\"\\n          },\\n          {\\n            \\\"value\\\": \\\"custom\\\",\\n            \\\"label\\\": \\\"Specify dimensions\\\"\\n          }\\n        ]\\n      },\\n      {\\n        \\\"type\\\": \\\"imageDimension\\\",\\n        \\\"label\\\": \\\"Thumbnail image\\\",\\n        \\\"id\\\": \\\"productthumb_size\\\",\\n        \\\"force_reload\\\": true,\\n        \\\"options\\\": [\\n          {\\n            \\\"value\\\": \\\"100x100\\\",\\n            \\\"label\\\": \\\"Optimized for theme\\\"\\n          },\\n          {\\n            \\\"value\\\": \\\"custom\\\",\\n            \\\"label\\\": \\\"Specify dimensions\\\"\\n          }\\n        ]\\n      },\\n      {\\n        \\\"type\\\": \\\"imageDimension\\\",\\n        \\\"label\\\": \\\"Zoomed image\\\",\\n        \\\"id\\\": \\\"zoom_size\\\",\\n        \\\"force_reload\\\": true,\\n        \\\"options\\\": [\\n          {\\n            \\\"value\\\": \\\"1280x1280\\\",\\n            \\\"label\\\": \\\"Optimized for theme\\\"\\n          },\\n          {\\n            \\\"value\\\": \\\"custom\\\",\\n            \\\"label\\\": \\\"Specify dimensions\\\"\\n          }\\n        ]\\n      },\\n      {\\n\\n        \\\"type\\\": \\\"imageDimension\\\",\\n        \\\"label\\\": \\\"Image in gallery view\\\",\\n        \\\"id\\\": \\\"productgallery_size\\\",\\n        \\\"force_reload\\\": true,\\n        \\\"options\\\": [\\n          {\\n            \\\"value\\\": \\\"300x300\\\",\\n            \\\"label\\\": \\\"Optimized for theme\\\"\\n          },\\n          {\\n            \\\"value\\\": \\\"custom\\\",\\n            \\\"label\\\": \\\"Specify dimensions\\\"\\n          }\\n        ]\\n      }\\n    ]\\n  },</pre></td>\\n  </tr>\\n</table>\"\n}\n[/block]\n<h3> <a name=\"schema-json-OptImage\"></a> optimizedCheckout-image Examples </h3>\n\nThe `optimizedCheckout-image` type is used to specify images for the Optimized Checkout page. The example below, from the `schema.json` in Stencil's base Cornerstone theme, handles a background image on that page. \n\nNote the matching `id` values for the `checkbox` vs. `optimizedCheckout-image` components. These allow the checkbox's Theme Editor state to toggle the image's display on or off:\n\n```\n  {\n    \"name\": \"Optimized Checkout\",\n    \"enable\": \"ucoEnabled\",\n    \"settings\": [\n      (...)\n      {\n        \"type\": \"checkbox\",\n        \"label\": \"Use custom background\",\n        \"id\": \"optimizedCheckout-show-backgroundImage\"\n      },\n      {\n        \"type\": \"optimizedCheckout-image\",\n        \"label\": \"1000 x 400px recommended\",\n        \"reference\": \"optimizedCheckout-show-backgroundImage\",\n        \"reference_default\": false,\n        \"id\": \"optimizedCheckout-backgroundImage\"\n      },\n      (...)\n```\n\n#### <span id=\"ref\"> The reference and reference_default Properties </span>\n\nAbove, also note the `reference` and `reference_default` properties. The `reference` property will always point to a unique `id` of its target component. The `reference_default` property's purpose is to specify the value that will _hide_ the image. This property's type will depend on the data type of the `reference` component; in this checkbox example, it is a boolean. \n\nThe next snippet directly follows the above code example in Cornerstone's `Optimized Checkout` section, and governs the same background image. Herem you see another example of the [`imageDimension`](#schema-json-ImageDim) type, expanded to use the `reference` and `reference_default` properties in the same way:\n\n```\n      {\n        \"type\": \"imageDimension\",\n        \"description\": \"Please specify a maximum image size for desktop display. We'll automatically scale down the image for smaller devices.\",\n        \"label\": \"\",\n        \"reference\": \"optimizedCheckout-show-backgroundImage\",\n        \"reference_default\": false,\n        \"id\": \"optimizedCheckout-backgroundImage-size\",\n        \"options\": [\n          {\n            \"value\": \"1000x400\",\n            \"label\": \"Optimized for theme\"\n          },\n          {\n            \"value\": \"custom\",\n            \"label\": \"Specify dimensions\"\n          }\n        ]\n      },\n```      \n\n#### <span id=\"uco-logo\"> Checkout Logo Example </span>\n\nBelow is the next snippet from the same Cornerstone `schema.json` > `Optimized Checkout` section. To govern the checkout page's logo, this creates a drop-down list in Theme Editor with two options, labeled `None` and `Custom`. Here, the `\"reference_default\": \"none\"` value will hide the image when the drop-down list's `none` value (`None` label) is selected:\n\n```\n      {\n        \"type\": \"select\",\n        \"label\": \"Use custom logo\",\n        \"id\": \"optimizedCheckout-show-logo\",\n        \"options\": [\n          {\n            \"value\": \"none\",\n            \"label\": \"None\"\n          },\n          {\n            \"value\": \"custom\",\n            \"label\": \"Custom\"\n          }\n        ]\n      },\n      {\n        \"type\": \"optimizedCheckout-image\",\n        \"label\": \"250 x 100px recommended\",\n        \"reference\": \"optimizedCheckout-show-logo\",\n        \"reference_default\": \"none\",\n        \"force_reload\": true,\n        \"id\": \"optimizedCheckout-logo\"\n      },\n```\n\n<h3> <a name=\"schema-json-text\"></a> Text Examples </h3>\n\nBy exposing the `text` data type in Theme Editor, you can allow merchants to specify short text strings for purposes like:\n\n* Sale badges' labels/wording.\n* \"As low as\" price labels' wording.\n* Pricing text on product detail pages. For example, a merchant could choose to relabel the default `MSRP`,&#160;`Retail`, and `Sale` prices as (respectively) `Street Price`, `Our Price`, and `Sale Price`.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"64-Character Limit\",\n  \"body\": \"Each `text` field is restricted to only 64 characters. This data type is intended for very short text strings, like&#160;labels.\"\n}\n[/block]\n<h4> schema.json Entries </h4>\n\nThe examples below, excerpted from the `schema.json` file in Stencil's base Cornerstone theme, define two labels:\n\n```json\n  {\n    \"name\": \"Footer\",\n    \"settings\": [\n      [...]\n      {\n        \"type\": \"text\",\n        \"label\": \"SSL Common Name\",\n        \"force_reload\": true,\n        \"id\": \"geotrust_ssl_common_name\"\n      },\n      [...]\n    ]\n  },\n  {\n  [...]\n  {\n    \"name\": \"Google AMP (beta)\",\n    \"settings\": [\n      {\n        \"type\": \"text\",\n        \"label\": \"AMP Analytics ID\",\n        \"id\": \"amp_analytics_id\"\n      }\n    ]\n  }\n]\n```\n\n<h4> config.json Entries </h4>\n\nHere are the corresponding keys in Cornerstone's `config.json` file:\n\n```json\n  [...]\n  \"settings\": {\n    \"amp_analytics_id\": \"\",\n    [...]\n    \"geotrust_ssl_common_name\": \"\",    \n    [...]\n```","excerpt":"","slug":"schemajson-metadata-for-theme-editor","type":"basic","title":"schema.json/Theme Editor Metadata"}

schema.json/Theme Editor Metadata


[block:html] { "html": "<a name=\"schema-json-ref\"></a>This entry guides you through designing and adjusting the Theme Editor graphical UI for your theme, by editing your theme's <NOBR><span class=\"inline-code\">schema.json</span> file.</nobr> It covers these topics:<br>\n\n<ul>\n <li><a href=\"#schema-json-EnableTE\">Enabling Theme Editor</a></li>\n <!-- <li><a href=\"#schema-json-Files\">File-Management Requirements</a></li> -->\n <li><a href=\"#schema-json-BestPrax\">Best Practices</a></li>\n <li><a href=\"#schema-json-UI\">How .json Entries Govern Theme Editor's UI</a></li> \n <li><a href=\"#schema-json-data-types\">Theme Editor Data Types</a></li> \n <!-- <li><a href=\"#schema-json-Headings\">Types versus \"heading\" Labels</a></li> -->\n <li><a href=\"#schema-json-Structure\">Theme Editor/schema.json Data Structure</a></li>\n <li><a href=\"#schema-json-Sequence\">Arbitrary UI Scope and Sequence</a></li>\n <!-- <li><a href=\"#schema-json-Reqs\">Requirements</a></li> -->\n <li><a href=\"#schema-json-ObjStruct\">Object Structure in schema.json:</a>\n <ul> <!-- Begin nested list -->\n <li><a href=\"#schema-json-Color\">Color Example</a></li>\n \t\t\t<li><a href=\"#schema-json-FontSelect\">Font and Select (Drop-Down List) Examples</a></li>\n \t\t\t<li><a href=\"#schema-json-FontVsSelect\">Font versus Select Types</a></li>\n \t\t\t<li><a href=\"#schema-json-PgLayout\">Page Layout Options using Select Elements</a></li>\n \t\t\t<li><a href=\"#schema-json-Chkbox\">Checkbox Examples</a></li>\n \t\t\t<li><a href=\"#schema-json-ImageDim\">imageDimension Examples</a></li>\n \t\t\t<li><a href=\"#schema-json-OptImage\">optimizedCheckout-image Examples</a></li>\n \t\t\t<li><a href=\"#schema-json-text\">Text Examples</a></li>\n \t\t\t<!-- <li><a href=\"#schema-json-Radios\">Radio Buttons Example</a></li> --> \n \t\t\t<!-- <li><a href=\"#schema-json-config\"> Dependency on config.json</a></li> --> <!-- End nested list -->\n </li> <!-- End outer list -->\n </ul>\n</ul>" } [/block] [block:callout] { "type": "info", "body": "For an end user's view of the Theme Editor UI, please see our [Using the Stencil Theme Editor](https://support.bigcommerce.com/articles/Public/Using-the-Stencil-Theme-Editor) support article. (This is written for merchants, but is relevant to developers using Theme Editor to customize themes.)", "title": "Exercising the UI" } [/block] [block:html] { "html": "<h2> <a name=\"schema-json-EnableTE\"></a> Enabling Theme Editor </h2>\n\nTo provide merchants with Theme Editor support for your theme's settings, you must declare those settings in the theme's <span class=\"inline-code\">&lt;theme‑name&gt;/schema.json</span> file. You must also include those settings in your theme's <span class=\"inline-code\"><a href=\"/docs/configjson-reference\">config.json</span></a> file, <a href=\"/docs/about-the-templates-directory\">templates</a>, and <a href=\"/docs/settings-directory\">Sass/CSS files</a>. The basic division of labor is this:\n\n<ul>\n<li><span class=\"inline-code\">schema.json</span> is an array of objects, declaring which theme settings are editable in Theme Editor. <NOBR>These objects</nobr> also declare all possible values to display in Theme Editor's GUI.</li>\n\n<li><span class=\"inline-code\">config.json</span> assigns (and updates) a default value for each of the editable settings.</li>\n\n<li>Each <span class=\"inline-code\">schema.json</span> entry has an <span class=\"inline-code\">id</span> element that maps it to its corresponding <span class=\"inline-code\">config.json</span> entry. <NOBR>The <span class=\"inline-code\">id</span> value</nobr> identifies the relevant <span class=\"inline-code\">config.json</span> key name.</li>\n\n<li>For front-matter properties to be editable, your theme's Handlebars template must call certain <NOBR><a href= \"/docs/custom-handlebars-helpers\">Handlebars helpers</a></nobr> to transform the <span class=\"inline-code\">config.json</span> entries into JavaScript values.</li>\n \n<li>For fonts to be editable, a <a href=\"/docs/settings-directory\">Sass stylesheet</a> must call certain <a href=\"/docs/custom-sass-functions#FontFamily\">custom Sass functions</a> to transform the <span class=\"inline-code\">config.json</span> font entries into CSS values.</li>\n\n<li>For styles to be editable, a <a href=\"/docs/settings-directory\">Sass stylesheet</a> must call certain <a href=\"/docs/custom-handlebars-helpers#stylesheet\">custom Handlebars helpers</a> to transform the <span class=\"inline-code\">config.json</span> entries into CSS values.</li>\n</ul>\n\nAs users select options within the Theme Editor UI (and save their selections), Stencil will automatically rewrite <span class=\"inline-code\">config.json</span> to record new defaults for the theme<!--'s affected variation-->.\n\n\n<h3> <a name=\"schema-json-Files\"></a> File-Management Requirements </h3>\n\nSee Stencil's default Cornerstone theme for examples that fulfill all of the above requirements. However, remember these:" } [/block] [block:callout] { "type": "danger", "body": "* For any theme setting (such as a Sass variable or a front-matter value) to be merchant-customizable, \nthat setting – and its possible values – must be present in `schema.json`. You must manually provide these declarations, according to the structure described here.\n\n* Also, each key that you create in `schema.json` must have a corresponding `config.json` key whose name matches its `id` value. This `config.json` key sets the default value (even if that is simply an empty string). A `schema.json` setting without an `id`-matched `config.json` key will not appear to users in the Theme Editor GUI.", "title": "Hard Requirements" } [/block] ## <a name="schema-json-BestPrax"></a> <a name="schema-json-Restrix"></a> Best Practices Please follow these guidelines to head off errors upon theme upload, and to avoid possible loss of customizations made via the Theme Editor GUI at runtime: [block:callout] { "type": "danger", "title": "", "body": "* **Single-Instance Restriction per Storefront:** We strongly recommend opening only one instance of Theme&#160;Editor, at a time, against each storefront. This is because there is currently no synchronization mechanism to reconcile configuration changes made by multiple Theme Editor instances. So <span class=\"inline-code\">schema.json</span> will record the last changes made by any instance &ndash; but changes saved earlier by other instances might be lost.\n\n* **Single-Storefront Restriction per Editor:** In the current release, users can have only one storefront at a time open in Theme Editor. (A&#160;workaround is to open an \"Incognito\"/private-browsing window on an additional storefront, to bypass the cookie that imposes this restriction.)\n\n* **File Name, Location, and Structure:** Your theme's `schema.json` file must be named `schema.json`, must reside in the root of your `<theme-name>` subdirectory (e.g.: `/cornerstone/schema.json`), and must be valid JSON.\n\n* **File Size:** The maximum allowable size for a theme's `schema.json` file is 64 KB. Exceeding this limit will trigger an error upon uploading the theme to BigCommerce. (Other than this size constraint, there is no limit on the number of keys and values that you can place in a theme's `schema.json`.)" } [/block] [block:html] { "html": "<h2> <a name=\"schema-json-UI\"></a> How .json Entries Govern Theme Editor's UI </h2>\n\nAs you can see from the examples just below, your entries in the <span class=\"inline-code\">schema.json</span> and <span class=\"inline-code\">config.json</span> files directly shape users' options in Theme Editor:<br>\n\n<ul>\n<li>Theme <i>Variations</i> always appear at the top of the Theme Editor panel. These variations are defined only in <span class=\"inline-code\">config.json</span>, and their definition order in that file governs their display order in Theme Editor.</li>\n\n<li>Merchants must select one variation to edit, at a time, in Theme Editor. The selections that they make in the remainder of Theme Editor's UI will apply to only that selected variation.</li>\n\n<li>Theme Editor's remaining sequence of top-level (Section) headings corresponds directly to the sequence of top-level (Section) objects that you declare in <span class=\"inline-code\">schema.json</span>:</li>\n</ul>" } [/block] [block:parameters] { "data": { "0-0": "<img src=\"https://files.readme.io/NXeFUx5cSuyp12DJ4Qcr_Theme-Editor-UI.png\" alt=\"Theme Editor graphical user interface\" height=\"724\" width=\"303\">", "0-1": "<br>[<b>&lt;&lt; Variations</b> are defined<br> only in <span class=\"inline-code\">config.json</span> <br>(not in <span class=\"inline-code\">schema.json</span>),<br> but always appear at the<br> top of Theme Editor's UI.]<br><br>\n\nThe remaining Sections at left<br> correspond to these Section<br> objects defined in <span class=\"inline-code\">schema.json</span>:\n<br>\n\n<pre>[\n {\n \"name\": \"Colors\",\n \"settings\": [...]\n },\n {\n \"name\": \"Typography\",\n \"settings\": [...]\n },\n {\n \"name\": \"Home page\",\n \"settings\": [...]\n },\n {\n \"name\": \"Product page\",\n \"settings\": [...]\n },\n {\n \"name\": \"Header\",\n \"settings\": [...]\n },\n {\n \"name\": \"Footer\",\n \"settings\": [...]\n }\n] </pre>", "h-0": "Theme Editor UI (What a Merchant Sees)", "h-1": ".json Declarations (What You Define)" }, "cols": 2, "rows": 1 } [/block] [block:html] { "html": "Also, as you'll see below, the options displayed within these expandable Section headings correspond directly to the keys/values that you nest within <span class=\"inline-code\">schema.json</span>'s corresponding Section objects.<br><br> \n\nIn all, the structure that you give your theme's <span class=\"inline-code\">config.json</span> and <span class=\"inline-code\">schema.json</span> files directly governs the UI that Theme Editor exposes to merchants. So these files provide your UI design tools.\n\n<h2> <a name=\"schema-json-data-types\"></a> Theme Editor Data Types </h2>\n\nTheme editor supports these data types: \n<ul>\n\t<li><span class=\"inline-code\">color</span></li>\n\t<li><span class=\"inline-code\">font</span></li>\n\t<li><span class=\"inline-code\">select</span> [drop-down list]</li>\n\t<li><span class=\"inline-code\">checkbox</span></li>\n\t<li><span class=\"inline-code\">imageDimension</span></li>\n\t<li><span class=\"inline-code\">text</span></li>\n <!-- <li><span class=\"inline-code\">image</span></li> -->\n</ul>\n\nWithin <span class=\"inline-code\">schema.json</span>, each object's data type is declared in a statement like the one highlighted here:<br><br>\n\n<pre>\n {\n <b>\"type\": \"color\",</b>\n \"label\": \"Text Color\",\n \"id\": \"body-font-color\"\n },\n</pre>\n\n<h3> <a name=\"schema-json-Headings\"></a> Types versus \"heading\" Labels </h3>\n\nWithin <span class=\"inline-code\">schema.json</span>, you will also see <span class=\"inline-code\">\"type\": \"heading\"</span> statements like this one &ndash; highlighted earlier in the same object used for the above example:<br><br>\n\n<pre>\n {\n \"name\": \"Colors\",\n \"settings\": [\n {\n <b>\"type\": \"heading\",</b>\n \"content\": \"General\"\n },\n {\n \"type\": \"color\",\n \"label\": \"Text Color\",\n \"id\": \"body-font-color\"\n },<!-- \n {\n \"type\": \"color\",\n \"label\": \"Link Color\",\n \"id\": \"color-textLink\"\n }, -->\n</pre>\n\nThese <span class=\"inline-code\">\"type\": \"heading\"</span> statements do not reference data types. Rather, they declare display captions for the Theme Editor UI's subcategories &ndash; the middle level nested within the Section headings, but outside the individual options from which merchants can select. (Those inner options are designated by <span class=\"inline-code\">\"label\": <i>&lt;label-text&gt;</i></span> statements.)<br><br> \n\nIn all, the hierarchy looks like this:" } [/block] [block:html] { "html": "<table>\n <tr>\n <th class=\"\">UI Hierarchy</th>\n <th class=\"\">schema.json Elements</th>\n </tr>\n <tr>\n <td class=\"\" align=\"right\"><br><p></p>\nSection (object) label &gt;&gt; <br><br><p></p>\n\n\n <span class=\"indent1\">Subcategory label &gt;&gt;</span><br><br><br><br><br>\n\n\n\n <span class=\"indent2\">Option label &gt;&gt;</span></td>\n <td class=\"\"><pre> {\n <b>\"name\": \"Colors\",</b>\n \"settings\": [\n {\n <b>\"type\": \"heading\",</b>\n \"content\": \"General\"\n },\n {\n \"type\": \"color\",\n <b>\"label\": \"Text Color\",</b>\n \"id\": \"body-font-color\"\n }, </pre></td>\n </tr>\n</table>" } [/block] [block:html] { "html": "<h2> <a name=\"schema-json-Structure\"></a> Theme Editor/schema.json Data Structure </h2>\n\nThe <span class=\"inline-code\">schema.json</span> nesting structure that you just saw maps directly to the Theme Editor UI displayed to merchants: Below the <b>Variations</b> Section (whose data are imported from <span class=\"inline-code\">config.json</span>), the order and nesting of options in Theme Editor's UI directly matches the order and nesting of your <span class=\"inline-code\">schema.json</span> entries.<br><br>\n\nHere is a live example, showing more of the same <span class=\"inline-code\">Colors</span> object:" } [/block] [block:parameters] { "data": { "h-0": "Theme Editor UI (What a Merchant Sees)", "h-1": ".json Declarations (What You Define)", "0-1": "<pre> {\n <b>\"name\": \"Colors\",</b>\n \"settings\": [\n {\n <b>\"type\": \"heading\",</b>\n \"content\": \"General\"\n },\n {\n \"type\": \"color\",\n <b>\"label\": \"Text Color\",</b>\n \"id\": \"body-font-color\"\n },\n {\n \"type\": \"color\",\n <b>\"label\": \"Link Color\",</b> [...] },\n {\n \"type\": \"color\",\n <b>\"label\": \"Heading Text Color\",</b> [...] },\n {\n <b>\"type\": \"heading\",</b>\n \"content\": \"Buttons\" },\n {\n \"type\": \"color\",\n <b>\"label\": \"Primary Button Background Color\",</b>\n \"id\": \"buttonStyle-primary-backgroundColor\" },\n {\n \"type\": \"color\",\n <b>\"label\": \"Secondary Button Text Color\",</b>\n \"id\": \"buttonStyle-default-color\" },\n {\n \"type\": \"color\",\n <b>\"label\": \"Secondary Button Background Color\",</b>\n \"id\": \"buttonStyle-default-backgroundColor\"\n },</pre>", "0-0": "<br>\n\n<img src=\"https://files.readme.io/VVA95OWARoGjLgsgHD4k_Theme-Editor~Colors-headings~291x607.png\" alt=\"Theme Editor subcategories\" height=\"607\" width=\"291\">" }, "cols": 2, "rows": 1 } [/block] [block:html] { "html": "<h2> <a name=\"schema-json-Sequence\"></a> Arbitrary UI Scope and Sequence </h2>\n\nOnce again: You are free to decide which properties of your theme to make editable in Theme Editor, and in which order to display them. Theme Editor can expose any set of properties, as long as your <span class=\"inline-code\">schema.json</span> declares them using the <a href=\"#schema-json-data-types\">data types</a> that Theme Editor supports.<br><br>" } [/block] [block:html] { "html": "<h2> <a name=\"schema-json-ObjStruct\"></a> Object Structure in schema.json </h2>\n\nThe following sections provide <span class=\"inline-code\">schema.json</span> examples for each of the data types that Theme Editor supports.\n\n<h3> <a name=\"schema-json-Color\"></a> Color Example </h3>\n\nReferring back to the default <span class=\"inline-code\">schema.json</span> file's uppermost <b>Colors</b> object, this excerpt shows the structure of elements for the <span class=\"inline-code\">color</span>type:<br><br>\n\n<table>\n <tr>\n <th class=\"\">Purpose</th>\n <th class=\"\">schema.json Elements</th>\n </tr>\n <tr>\n <td class=\"\"><br><p></p>\nSection (object) label &gt;&gt; <br><br><br><br><p></p>\n\n\n <span class=\"indent1\">Subcategory label &gt;&gt;</span><p></p>\n\n <span class=\"indent2\">[Elements per subcategory option:] &nbsp; &nbsp; </span><p></p>\n\n <span class=\"indent2\">Data type declaration &gt;&gt;</span><br>\n\n <span class=\"indent2\">Display label &gt;&gt;</span><br>\n\n <span class=\"indent2\">ID = name of matching <span class=\"inline-code\">config.json</span> &gt;&gt;</span><br> \n <span class=\"indent3\">key that provides default value &nbsp; &nbsp; &nbsp; </span><br><p></p>\n\n <span class=\"indent2\">[Etc.: &gt;&gt;]</span><br><br><br><br><p></p>\n\n <span class=\"indent2\">[Etc.: &gt;&gt;]</span>\n </td>\n\n <td class=\"\"><pre> {\n <b>\"name\": \"Colors\",</b>\n \"settings\": [\n ...\n {\n \"type\": \"heading\",\n <b>\"content\": \"Buttons\"</b>\n },\n {\n \"type\": \"color\",\n \"label\": \"Primary Button Background Color\",\n \"id\": \"buttonStyle-primary-backgroundColor\"\n },\n {\n \"type\": \"color\",\n \"label\": \"Secondary Button Text Color\",\n \"id\": \"buttonStyle-default-color\"\n },\n {\n \"type\": \"color\",\n \"label\": \"Secondary Button Background Color\",\n \"id\": \"buttonStyle-default-backgroundColor\"\n },</pre></td>\n </tr>\n</table>\n\nThe code outlined above generates the Theme Editor panel shown here: " } [/block] [block:html] { "html": "<table>\n <tr>\n <th class=\"\">Theme Editor UI</th>\n <th class=\"\">schema.json Elements</th>\n </tr>\n <tr>\n <td class=\"\"> <img src=\"https://files.readme.io/vW49lolsQauuUSzSPPXL_Colors-Heading~291w-x-71h.png\" alt=\"Colors heading\">\n <br><p></p> \n <span class=\"indent1\">[...]</span><br><br><br>\n<img src=\"https://files.readme.io/IA1mvTJSJyPfRhzBN5gT_Color-Swatches@286x248.png\" alt=\"Color &gt; Buttons UI controls\">\n </td>\n\n <td class=\"\"><pre> {\n <b>\"name\": \"Colors\",</b>\n \"settings\": [\n ...\n {\n \"type\": \"heading\",\n <b>\"content\": \"Buttons\"</b>\n },\n {\n \"type\": \"color\",\n \"label\": \"Primary Button Background Color\",\n \"id\": \"buttonStyle-primary-backgroundColor\"\n },\n {\n \"type\": \"color\",\n \"label\": \"Secondary Button Text Color\",\n \"id\": \"buttonStyle-default-color\"\n },\n {\n \"type\": \"color\",\n \"label\": \"Secondary Button Background Color\",\n \"id\": \"buttonStyle-default-backgroundColor\"\n },</pre></td>\n </tr>\n</table>\n\nAbove, each option's color swatch corresponds to the corresponding <span class=\"inline-code\">config.json</span> key's color value. Theme Editor users can select/click each swatch to open a Color Picker dialog, to redefine the corresponding theme feature's color.<br><br>\n\nYou can find more examples of <span class=\"inline-code\">color</span> elements in the default <span class=\"inline-code\">schema.json</span> file's <b>Header</b> and <b>Footer</b> objects." } [/block] [block:html] { "html": "<h3> <a name=\"schema-json-FontSelect\"></a> Font and Select (Drop-Down List) Examples </h3>\n\nIn the default Stencil theme's <span class=\"inline-code\">schema.json</span>, the head of the <b>Typography</b> object shows the structure of both the <span class=\"inline-code\">font</span> and <span class=\"inline-code\">select</span> data types, which work similarly:" } [/block] [block:html] { "html": "<table>\n <tr>\n <th class=\"\">Purpose</th>\n <th class=\"\">schema.json Elements</th>\n </tr>\n <tr>\n <td class=\"\"><br><p></p>\nSection (object) label &gt;&gt; <br><br><br><p></p>\n\n\n <span class=\"indent1\">Subcategory label &gt;&gt;</span><p></p>\n\n <span class=\"indent2\">[Elements per subcategory option:] &nbsp; &nbsp; </span><p></p>\n\n <span class=\"indent2\">Data type declaration &gt;&gt;</span><br>\n\n <span class=\"indent2\">Display label &gt;&gt;</span><br>\n\n <span class=\"indent2\">ID that matches a <span class=\"inline-code\">config.json</span> key name &gt;&gt;</span><br> \n\n <span class=\"indent2\">Options = alternate choices to display &gt;&gt;</span><br> \n <span class=\"indent3\">on drop-down list &nbsp; &nbsp; </span><br><br><br><br><p></p>\n\n <span class=\"indent3\">Group = option's display position &nbsp; &nbsp; </span><br>\n <span class=\"indent4\">on drop-down list &gt;&gt;</span><br>\n \n <span class=\"indent3\">Option's display label &gt;&gt;</span><br>\n <span class=\"indent3\">Corresponding font value, in a <a href=\"/docs/configjson-reference#config-json-fonts\">defined format</a> &gt;&gt;</span><br><br><p></p>\n \n <span class=\"indent3\">[Etc., for remaining options on same &gt;&gt;</span><br>\n <span class=\"indent4\">drop-down list] &nbsp; &nbsp; </span>\n<br><br><br>\n<br><br><p></p>\n \n\n <span class=\"indent2\">Data type declaration (for <span class=\"inline-code\">select</span> type) &gt;&gt;</span><br>\n\n <span class=\"indent2\">Display label &gt;&gt;</span><br>\n\n <span class=\"indent2\">ID that matches a <span class=\"inline-code\">config.json</span> key name &gt;&gt;</span><br> \n\n <span class=\"indent2\">Options = alternate choices to display &gt;&gt;</span><br> \n <span class=\"indent3\">on drop-down list &nbsp; &nbsp; &nbsp; </span><br><br><br><br>\n\n <span class=\"indent3\">Value for this option &gt;&gt;</span><br>\n\n <span class=\"indent3\">Display label for this option &gt;&gt;</span><br><br><br><br>\n\n <span class=\"indent3\">[Etc., for remaining options on same &gt;&gt;</span><br>\n <span class=\"indent4\">drop-down list] &nbsp; &nbsp; </span> \n \n</td>\n\n <td class=\"\"><pre> {\n <b>\"name\": \"Typography\",</b>\n \"settings\": [\n {\n \"type\": \"heading\",\n <b>\"content\": \"Base typeface\"</b>\n },\n {\n <b>\"type\": \"font\",\n \"label\": \"Font Family\",\n \"id\": \"body-font\",\n \"options\": [</b>\n {\n \"group\": \"Open Sans\",\n \"label\": \"Open Sans\",\n \"value\": \"Google_Open+Sans\"\n },\n {\n <b>\"group\": \"Open Sans\",\n \"label\": \"Open Sans Bold\",\n \"value\": \"Google_Open+Sans_700\"</b>\n },\n {\n \"group\": \"Karla\",\n \"label\": \"Karla\",\n \"value\": \"Google_Karla\"\n }\n ]\n },\n {\n <b>\"type\": \"select\",\n \"label\": \"Font Size\",\n \"id\": \"fontSize-base\",\n \"options\": [</b>\n {\n \"value\": 10,\n \"label\": \"10px\"\n },\n {\n \"value\": 11,\n \"label\": \"11px\"\n },\n[...] \n {\n \"value\": 16,\n \"label\": \"16px\"\n }\n ]\n },\n</pre></td>\n </tr>\n</table>\n\nThe code outlined above generates the set of Theme Editor UI features expanded below: " } [/block] [block:html] { "html": "<table>\n <tr>\n <th class=\"\">Theme Editor UI</th>\n <th class=\"\">schema.json Elements</th>\n </tr>\n <tr>\n <td class=\"\"> <!-- <img src=\"https://files.readme.io/aS9AuQyST2p9jG8pBDDO_Typography-long-panel~281w-x-688h.png\" alt=\"Typography (Fonts) UI controls\"> -->\n <img src=\"https://files.readme.io/7diRZtBaTaBmrWPFkJ37_Typography-Head-only~77h-x-291w.png\" alt=\"Typography (Fonts) heading\">\n <br><br><br><br><br><br><br>\n <img src=\"https://files.readme.io/jFKR3TleTMLY8989AIQj_Typography-Family-only~125h-x-292w.png\" alt=\"font (family) UI control\"> \n <br><br><br><br><br><br><br><br><br><br>\n <img src=\"https://files.readme.io/UvfaM3LBQ0a13DETFUWJ_Typography-Size-only~187h-x-291w.png\" alt=\"select (font-size) drop-down list\">\n </td>\n\n <td class=\"\"><pre> {\n <b>\"name\": \"Typography\",</b>\n \"settings\": [\n[...]<!-- \n {\n \"type\": \"heading\",\n \"content\": \"Base typeface\"\n }, -->\n {\n <b>\"type\": \"font\",</b>\n \"label\": \"Font Family\",\n \"id\": \"body-font\",\n \"options\": [\n <b>{\n \"group\": \"Open Sans\",\n \"label\": \"Open Sans\",\n \"value\": \"Google_Open+Sans\"\n },\n {\n \"group\": \"Open Sans\",\n \"label\": \"Open Sans Bold\",\n \"value\": \"Google_Open+Sans_700\"\n },\n {\n \"group\": \"Karla\",\n \"label\": \"Karla\",\n \"value\": \"Google_Karla\"\n }</b>\n[...]<!-- \n ]\n }, -->\n {\n <b>\"type\": \"select\",\n \"label\": \"Font Size\",</b>\n \"id\": \"fontSize-base\",\n \"options\": [\n <b>{\n \"value\": 10,\n \"label\": \"10px\"\n },\n {\n \"value\": 11,\n \"label\": \"11px\"\n },</b>\n[...] <!-- \n {\n \"value\": 12,\n \"label\": \"12px\"\n },\n {\n \"value\": 13,\n \"label\": \"13px\"\n },\n {\n \"value\": 14,\n \"label\": \"14px\"\n },\n {\n \"value\": 15,\n \"label\": \"15px\"\n }, -->\n <b>{\n \"value\": 16,\n \"label\": \"16px\"\n }</b>\n[...] <!-- \n ]\n }, --></pre></td>\n </tr>\n</table>" } [/block] [block:html] { "html": "<h3> <a name=\"schema-json-FontVsSelect\"></a> Font versus Select Types </h3>\n\nAs you've just seen, <span class=\"inline-code\">font</span> elements and <span class=\"inline-code\">select</span> elements each declare drop-down lists. But <span class=\"inline-code\">font</span> elements have some additional options and requirements:\n\n<ul>\n<li>Within each <span class=\"inline-code\">font</span> family element, a <span class=\"inline-code\">group</span> sub-element is recommended (although not required). <NOBR>These <span class=\"inline-code\">group</span> sub-elements</nobr> promote orderly drop-down lists, as you can see in the screenshot above: <NOBR>They cause</nobr> Theme Editor to group related fonts together, under a subheading that matches their shared <span class=\"inline-code\">group</span> identifier.</li>\n\n<li>For each <span class=\"inline-code\">font</span> family element, the <span class=\"inline-code\">id</span>\nelement must name a <span class=\"inline-code\">config.json</span> key that sets the default family, <NOBR>in a</nobr> <a href=\"/docs/configjson-reference#config-json-fonts\">defined format</a>.</li>\n\n<li>Your theme's <a href=\"/docs/settings-directory#SassFontFns\">Sass stylesheet</a> must call Stencil's custom Sass functions to transform the fonts specified in <span class=\"inline-code\">config.json</span>.</li>\n</ul>\n\n<h3> <a name=\"schema-json-PgLayout\"></a> Page Layout Options using Select Elements </h3>\n\nThe default <span class=\"inline-code\">schema.json</span> file's <b>Home page</b> and <b>Product page</b> Sections provide examples of how you can use <span class=\"inline-code\">select</span> elements to offer merchants drop-down lists to customize their storefront pages' layouts.<br><br>\n\nThe code excerpts below (note the \"<span class=\"inline-code\">...</span>\" ellipses) declare <NOBR><b>Home page</b></nobr> drop-down lists for customizing the number of objects displayed in four page panels. Such controls allow merchants to override your front-matter and Handlebars defaults, without needing to do any coding:" } [/block] [block:html] { "html": "<table>\n <tr>\n <th class=\"\">Theme Editor UI</th>\n <th class=\"\">schema.json Elements</th>\n </tr>\n <tr>\n <td class=\"\"> <img src=\"https://files.readme.io/p2eAJoNRmmRH31FFBqRX_Homepage~Theme-Editor-full-panel~512h-x-289w.png\" alt=\"Home page UI controls\">\n </td>\n\n <td class=\"\"><pre> {\n <b>\"name\": \"Home page\",\n \"settings\": [</b>\n {\n <b>\"type\": \"select\",\n \"label\": \"Number of Featured Products\",</b>\n \"id\": \"homepage_featured_products_count\",\n \"options\": [ ... <!--\n {\n \"value\": 0,\n \"label\": \"Disable\"\n },\n {\n \"value\": 1,\n \"label\": \"1\"\n },\n {\n \"value\": 2,\n \"label\": \"2\"\n },\n {\n \"value\": 3,\n \"label\": \"3\"\n },\n {\n \"value\": 4,\n \"label\": \"4\"\n },\n {\n \"value\": 5,\n \"label\": \"5\"\n },\n {\n \"value\": 6,\n \"label\": \"6\"\n },\n {\n \"value\": 7,\n \"label\": \"7\"\n },\n {\n \"value\": 8,\n \"label\": \"8\"\n },\n {\n \"value\": 9,\n \"label\": \"9\"\n },\n {\n \"value\": 10,\n \"label\": \"10\"\n },\n {\n \"value\": 11,\n \"label\": \"11\"\n },\n {\n \"value\": 12,\n \"label\": \"12\"\n } \n -->]\n },\n {\n <b>\"type\": \"select\",\n \"label\": \"Number of Most Popular Products\",</b>\n \"id\": \"homepage_top_products_count\",\n \"options\": [ ... <!--\n {\n \"value\": 0,\n \"label\": \"Disable\"\n },\n {\n \"value\": 1,\n \"label\": \"1\"\n },\n {\n \"value\": 2,\n \"label\": \"2\"\n },\n {\n \"value\": 3,\n \"label\": \"3\"\n },\n {\n \"value\": 4,\n \"label\": \"4\"\n },\n {\n \"value\": 5,\n \"label\": \"5\"\n },\n {\n \"value\": 6,\n \"label\": \"6\"\n },\n {\n \"value\": 7,\n \"label\": \"7\"\n },\n {\n \"value\": 8,\n \"label\": \"8\"\n },\n {\n \"value\": 9,\n \"label\": \"9\"\n },\n {\n \"value\": 10,\n \"label\": \"10\"\n },\n {\n \"value\": 11,\n \"label\": \"11\"\n },\n {\n \"value\": 12,\n \"label\": \"12\"\n }\n -->]\n },\n {\n <b>\"type\": \"select\",\n \"label\": \"Number of New Products\",</b>\n \"id\": \"homepage_new_products_count\",\n \"options\": [ ... <!--\n {\n \"value\": 0,\n \"label\": \"Disable\"\n },\n {\n \"value\": 1,\n \"label\": \"1\"\n },\n {\n \"value\": 2,\n \"label\": \"2\"\n },\n {\n \"value\": 3,\n \"label\": \"3\"\n },\n {\n \"value\": 4,\n \"label\": \"4\"\n },\n {\n \"value\": 5,\n \"label\": \"5\"\n },\n {\n \"value\": 6,\n \"label\": \"6\"\n },\n {\n \"value\": 7,\n \"label\": \"7\"\n },\n {\n \"value\": 8,\n \"label\": \"8\"\n },\n {\n \"value\": 9,\n \"label\": \"9\"\n },\n {\n \"value\": 10,\n \"label\": \"10\"\n },\n {\n \"value\": 11,\n \"label\": \"11\"\n },\n {\n \"value\": 12,\n \"label\": \"12\"\n -->}\n ]\n },\n {\n <b>\"type\": \"select\",\n \"label\": \"Number of Blog Posts\",</b>\n \"id\": \"homepage_blog_posts_count\",\n \"options\": [ ... <!--\n {\n \"value\": 0,\n \"label\": \"Disable\"\n },\n {\n \"value\": 1,\n \"label\": \"1\"\n },\n {\n \"value\": 2,\n \"label\": \"2\"\n },\n {\n \"value\": 3,\n \"label\": \"3\"\n },\n {\n \"value\": 4,\n \"label\": \"4\"\n },\n {\n \"value\": 5,\n \"label\": \"5\"\n },\n {\n \"value\": 6,\n \"label\": \"6\"\n },\n {\n \"value\": 7,\n \"label\": \"7\"\n },\n {\n \"value\": 8,\n \"label\": \"8\"\n },\n {\n \"value\": 9,\n \"label\": \"9\"\n },\n {\n \"value\": 10,\n \"label\": \"10\"\n },\n {\n \"value\": 11,\n \"label\": \"11\"\n },\n {\n \"value\": 12,\n \"label\": \"12\"\n }\n -->]\n },\n ]\n },</pre></td>\n </tr>\n</table>\n\nThis next snippet expands more of the code that declares the first (<b>Number of Featured Products</b>) drop-down list. As in the <b>Typography</b> examples, the <span class=\"inline-code\">id</span> sub-element must name a <span class=\"inline-code\">config.json</span> key that manages the theme property's default value.<br><br>\n\nNote how the initial <span class=\"inline-code\">\"value\": 0</span> option is accompanied by a <NOBR><span class=\"inline-code\">\"label\": \"Disable\"</span></nobr> tag, which offers end users a more meaningful display of its numeric value:" } [/block] [block:html] { "html": "<table>\n <tr>\n <th class=\"\">Theme Editor UI</th>\n <th class=\"\">schema.json Elements</th>\n </tr>\n <tr>\n <td class=\"\"><br> <img src=\"https://files.readme.io/g2KFesoFSludlXfiy6sf_Homepage~Theme-Editor-1st-droplist~368h-x-291w.png\" alt=\"Home page &ndash; Featured Products UI control\">\n </td>\n\n <td class=\"\"><pre> {\n <b>\"name\": \"Home page\",</b>\n \"settings\": [\n {\n <b>\"type\": \"select\",\n \"label\": \"Number of Featured Products\",</b>\n \"id\": \"homepage_featured_products_count\",\n <!-- \"force_reload\": true, -->\n \"options\": [\n {\n <b>\"value\": 0,\n \"label\": \"Disable\"</b>\n },\n {\n \"value\": 1,\n \"label\": \"1\"\n },\n {\n \"value\": 2,\n \"label\": \"2\"\n }, <!--\n {\n \"value\": 3,\n \"label\": \"3\"\n },\n {\n \"value\": 4,\n \"label\": \"4\"\n },\n {\n \"value\": 5,\n \"label\": \"5\"\n },\n {\n \"value\": 6,\n \"label\": \"6\"\n },\n {\n \"value\": 7,\n \"label\": \"7\"\n },\n {\n \"value\": 8,\n \"label\": \"8\"\n },\n {\n \"value\": 9,\n \"label\": \"9\"\n },\n {\n \"value\": 10,\n \"label\": \"10\"\n },\n {\n \"value\": 11,\n \"label\": \"11\"\n }, -->\n[...] \n {\n \"value\": 12,\n \"label\": \"12\"\n }\n ]\n },</pre></td>\n </tr>\n</table>" } [/block] [block:html] { "html": "<h3> <a name=\"schema-json-Chkbox\"></a> Checkbox Examples </h3>\n\nThe <span class=\"inline-code\">checkbox</span> data type displays a check box in the Theme Editor UI, allowing users to toggle a boolean property.<br><p></p>\n\n<!-- \"(!)\" Callout; Titled: \"In Development\"; Body: \nAs of this draft, the <span class=\"inline-code\">checkbox</span> data type is still in development. It *can* be used to display a check box in the Theme Editor UI. However, clicking the check box does not toggle the specified theme property. Rather, it causes the browser window/tab to hang, requiring the user to manually refresh that window/tab. \nUpon refresh, the selected property will revert to its previous state. -->\n\nHere is an example that you could place within your <span class=\"inline-code\">schema.json</span>'s <b>Home page</b> Section, to enable merchants to easily toggle the theme's image carousel on/off:<br><br>\n\n<table>\n <tr>\n <th class=\"\">Theme Editor UI</th>\n <th class=\"\">schema.json Elements</th>\n </tr>\n <tr>\n <td class=\"\"> <img src=\"https://files.readme.io/A8Mr4mkTRJoOMlNaayAb_Carousel-UI~only~120h-x-292w.png\" alt=\"Home page &ndash; Carousel On/Off check box\">\n <!-- <img src=\"https://files.readme.io/EHhnetzUTavIeUS5TBFG_Carousel-UI~isolated~181h-x-291w.png\" alt=\"Home page &ndash; Carousel On/Off check box\">\n <img src=\"https://files.readme.io/nwEFK3APRDCT6Rq9awBE_Carousel-UI~in-context~252h-x-289-w.png\" alt=\"Home page &ndash; Carousel On/Off check box\"> -->\n </td>\n\n <td class=\"\"><pre> {\n \"type\": \"checkbox\",\n \"id\": \"homepage_show_carousel\",\n \"label\": \"Carousel On/Off\"\n }</pre></td>\n </tr>\n</table>\n\n<h4> <a name=\"schema-json-config\"></a> Dependency on config.json </h4>\n\nAs in preceding examples, the <span class=\"inline-code\">id</span> sub-element must name a <span class=\"inline-code\">config.json</span> key that manages the theme property's default value. Here, <span class=\"inline-code\">config.json</span> would assign one of these values to its <span class=\"inline-code\">homepage_show_carousel</span> key: \n\n<ul>\n\t<li><span class=\"inline-code\">true</span> (check box selected, property enabled)</li> \n \n <li><span class=\"inline-code\">false</span> (check box deselected, property disabled).</li>\n</ul>\n<br>\n\n<h4> <a name=\"schema-json-config\"></a> \"Powered by\" and Payment Toggle Examples </h4>\n\nA common use of the <span class=\"inline-code\">checkbox</span> type is to allow merchants to toggle on/off the \"Powered by BigCommerce\" credit in the storefront's footer. Here is the relevant code, which writes to <span class=\"inline-code\">config.json</span>'s <span class=\"inline-code\">show_powered_by</span> key:<br><br>\n\n<table>\n <tr>\n <th class=\"\">Theme Editor UI</th>\n <th class=\"\">schema.json Elements</th>\n </tr>\n <tr>\n <td class=\"\"> <br><br><img src=\"https://files.readme.io/cOsFRG3R67y2gnRvOI9A_25282-Theme-Ed~Powered-By.png\" alt=\"Footer &ndash; Site credit On/Off check box\">\n </td>\n\n <td class=\"\"><pre> {\n \"name\": \"Footer\",\n \"settings\": [\n {\n [...]\n },\n {\n \"type\": \"checkbox\",\n \"label\": \"Show Powered By\",\n \"force_reload\": true,\n \"id\": \"show_powered_by\"\n }\n ]\n },\n</pre></td>\n </tr>\n</table>\n\n<!-- <img src=\"https://files.readme.io/aIVsL7lzS7eNRyqYYaZR_25285-Theme-Ed~Payment-Icons~Cropped.png\" alt=\"Footer &ndash; Payment Icons check boxes\"> -->\n\nPayment-method icons can be toggled on/off in the same way, by writing to the <span class=\"inline-code\">Payment Icons</span> section's <NOBR><span class=\"inline-code\">show_accept_paypal</span>,</nobr> <NOBR><span class=\"inline-code\">show_accept_visa</span>,</nobr> etc., keys.\n\n<h3> <a name=\"schema-json-ImageDim\"></a> imageDimension Examples </h3>\n\n<h4> Logo Example </h4>\n\nIn the default Stencil theme's <span class=\"inline-code\">schema.json</span>, the <span class=\"inline-code\">Logo</span> object demonstrates the <span class=\"inline-code\">imageDimension</span> data type. <NOBR>This type's</nobr> <span class=\"inline-code\">schema.json</span> value will normally default to the corresponding <span class=\"inline-code\">logo_size</span> default value in <span class=\"inline-code\">config.json</span>. (In this example, the value is <span class=\"inline-code\">\"250x100\"</span>, and is labeled <span class=\"inline-code\">\"Optimized for theme\"</span>.)<br><p></p>\n\nHowever, if the <span class=\"inline-code\">config.json</span> default is not present in <span class=\"inline-code\">schema.json</span> as a selectable value, Theme Editor will instead fall back to showing users the <span class=\"inline-code\">\"custom\"</span> value (labeled <span class=\"inline-code\">\"Specify dimensions\"</span> in the code example below)." } [/block] [block:callout] { "type": "warning", "body": "The <span class=\"inline-code\">config.json</span> default value for an <span class=\"inline-code\">imageDimension</span> type is a string. It can be either <span class=\"inline-code\">\"original\"</span>, or horizontal x vertical dimensions in the format <span class=\"inline-code\">\"*#* x *#*\"</span>." } [/block] [block:html] { "html": "The <span class=\"inline-code\">description</span> field's presence is optional, but if you include it within <span class=\"inline-code\">schema.json</span>'s <span class=\"inline-code\">Logo</span> object (to provide user instructions), you must populate it. Theme Editor displays entry boxes that record the user's <i>maximum</i> width and height selections for the image, while enforcing the image's original aspect ratio.<br><br>\n\n<table>\n <tr>\n <th class=\"\">Theme Editor UI</th>\n <th class=\"\">schema.json Elements</th>\n </tr>\n <tr>\n <td class=\"\"> [Image to follow.]\n </td>\n\n <td class=\"\"><pre> {\n \"name\": \"Logo\",\n \"settings\": [\n {\n \"type\": \"imageDimension\",\n \"label\": \"Logo size\",\n \"id\": \"logo_size\",\n \"description\": \"Please specify a maximum image size for desktop display. We'll automatically scale down the image for smaller devices.\",\n \"force_reload\": true,\n \"options\": [\n {\n \"value\": \"original\",\n \"label\": \"Original (as uploaded)\"\n },\n {\n \"value\": \"250x100\",\n \"label\": \"Optimized for theme\"\n },\n {\n \"value\": \"custom\",\n \"label\": \"Specify dimensions\"\n }\n ]\n },\n\t\t</pre></td>\n </tr>\n</table>\n\n<h4> Product Example </h4>\n\nBelow are several more examples of the <span class=\"inline-code\">imageDimension</span> data type, from the default Stencil theme's <span class=\"inline-code\">Product</span> object. Here, Theme Editor uses the <span class=\"inline-code\">imageDimension</span> type to expose and update several default sizes stored in <span class=\"inline-code\">config.json</span>.<br><p></p>\n\nThe <span class=\"inline-code\">imageDimension</span> type here behaves as in the <span class=\"inline-code\">Logo</span> example: Theme Editor will normally default to the <span class=\"inline-code\">\"Optimized for theme\"</span> value, corresponding to a <span class=\"inline-code\">config.json</span> default value. However, if the <span class=\"inline-code\">config.json</span> default is absent in <span class=\"inline-code\">schema.json</span>, Theme Editor will instead fall back to showing users the <span class=\"inline-code\">\"custom\"</span> value. Here again, the entry boxes record maximum dimensions, and Theme Editor enforces the image's original aspect ratio." } [/block] [block:callout] { "type": "warning", "title": "Hide \"original\"–Sized Product Images", "body": "For the <span class=\"inline-code\">Product</span> object's contained <span class=\"inline-code\">imageDimension</span> types, we recommend that your shipped <span class=\"inline-code\">config.json</span> *not* save <span class=\"inline-code\">original</span> as the default value, and that your <span class=\"inline-code\">schema.json</span> *not* display <span class=\"inline-code\">original</span> as a selectable value. \n\nProducts' original images tend to be large, so showing them on the storefront at native resolution would slow pages' load times. The safe choices for Product are <span class=\"inline-code\">\"Optimized for theme\"</span> and a judicious <span class=\"inline-code\">\"custom\"</span>." } [/block] [block:html] { "html": "The <span class=\"inline-code\">Product</span> object here has a single <span class=\"inline-code\">content</span> field, which behaves like the <span class=\"inline-code\">Logo</span> object's <span class=\"inline-code\">description</span> field: <NOBR>Its presence</nobr> is optional, but if you include it in the object, you must populate it.<br><br>\n\n<table>\n <tr>\n <th class=\"\">Theme Editor UI</th>\n <th class=\"\">schema.json Elements</th>\n </tr>\n <tr>\n <td class=\"\"> [Image to follow.]\n </td>\n\n <td class=\"\"><pre> {\n \"type\": \"heading\",\n \"content\": \"Image sizes\"\n },\n {\n \"type\": \"paragraph\",\n \"content\": \"Please specify a maximum image size for desktop display. We'll automatically scale down the image for smaller devices.\"\n },\n {\n \"type\": \"imageDimension\",\n \"label\": \"Main product images\",\n \"id\": \"product_size\",\n \"force_reload\": true,\n \"options\": [\n {\n \"value\": \"500x659\",\n \"label\": \"Optimized for theme\"\n },\n {\n \"value\": \"custom\",\n \"label\": \"Specify dimensions\"\n }\n ]\n },\n {\n \"type\": \"imageDimension\",\n \"label\": \"Thumbnail image\",\n \"id\": \"productthumb_size\",\n \"force_reload\": true,\n \"options\": [\n {\n \"value\": \"100x100\",\n \"label\": \"Optimized for theme\"\n },\n {\n \"value\": \"custom\",\n \"label\": \"Specify dimensions\"\n }\n ]\n },\n {\n \"type\": \"imageDimension\",\n \"label\": \"Zoomed image\",\n \"id\": \"zoom_size\",\n \"force_reload\": true,\n \"options\": [\n {\n \"value\": \"1280x1280\",\n \"label\": \"Optimized for theme\"\n },\n {\n \"value\": \"custom\",\n \"label\": \"Specify dimensions\"\n }\n ]\n },\n {\n\n \"type\": \"imageDimension\",\n \"label\": \"Image in gallery view\",\n \"id\": \"productgallery_size\",\n \"force_reload\": true,\n \"options\": [\n {\n \"value\": \"300x300\",\n \"label\": \"Optimized for theme\"\n },\n {\n \"value\": \"custom\",\n \"label\": \"Specify dimensions\"\n }\n ]\n }\n ]\n },</pre></td>\n </tr>\n</table>" } [/block] <h3> <a name="schema-json-OptImage"></a> optimizedCheckout-image Examples </h3> The `optimizedCheckout-image` type is used to specify images for the Optimized Checkout page. The example below, from the `schema.json` in Stencil's base Cornerstone theme, handles a background image on that page. Note the matching `id` values for the `checkbox` vs. `optimizedCheckout-image` components. These allow the checkbox's Theme Editor state to toggle the image's display on or off: ``` { "name": "Optimized Checkout", "enable": "ucoEnabled", "settings": [ (...) { "type": "checkbox", "label": "Use custom background", "id": "optimizedCheckout-show-backgroundImage" }, { "type": "optimizedCheckout-image", "label": "1000 x 400px recommended", "reference": "optimizedCheckout-show-backgroundImage", "reference_default": false, "id": "optimizedCheckout-backgroundImage" }, (...) ``` #### <span id="ref"> The reference and reference_default Properties </span> Above, also note the `reference` and `reference_default` properties. The `reference` property will always point to a unique `id` of its target component. The `reference_default` property's purpose is to specify the value that will _hide_ the image. This property's type will depend on the data type of the `reference` component; in this checkbox example, it is a boolean. The next snippet directly follows the above code example in Cornerstone's `Optimized Checkout` section, and governs the same background image. Herem you see another example of the [`imageDimension`](#schema-json-ImageDim) type, expanded to use the `reference` and `reference_default` properties in the same way: ``` { "type": "imageDimension", "description": "Please specify a maximum image size for desktop display. We'll automatically scale down the image for smaller devices.", "label": "", "reference": "optimizedCheckout-show-backgroundImage", "reference_default": false, "id": "optimizedCheckout-backgroundImage-size", "options": [ { "value": "1000x400", "label": "Optimized for theme" }, { "value": "custom", "label": "Specify dimensions" } ] }, ``` #### <span id="uco-logo"> Checkout Logo Example </span> Below is the next snippet from the same Cornerstone `schema.json` > `Optimized Checkout` section. To govern the checkout page's logo, this creates a drop-down list in Theme Editor with two options, labeled `None` and `Custom`. Here, the `"reference_default": "none"` value will hide the image when the drop-down list's `none` value (`None` label) is selected: ``` { "type": "select", "label": "Use custom logo", "id": "optimizedCheckout-show-logo", "options": [ { "value": "none", "label": "None" }, { "value": "custom", "label": "Custom" } ] }, { "type": "optimizedCheckout-image", "label": "250 x 100px recommended", "reference": "optimizedCheckout-show-logo", "reference_default": "none", "force_reload": true, "id": "optimizedCheckout-logo" }, ``` <h3> <a name="schema-json-text"></a> Text Examples </h3> By exposing the `text` data type in Theme Editor, you can allow merchants to specify short text strings for purposes like: * Sale badges' labels/wording. * "As low as" price labels' wording. * Pricing text on product detail pages. For example, a merchant could choose to relabel the default `MSRP`,&#160;`Retail`, and `Sale` prices as (respectively) `Street Price`, `Our Price`, and `Sale Price`. [block:callout] { "type": "warning", "title": "64-Character Limit", "body": "Each `text` field is restricted to only 64 characters. This data type is intended for very short text strings, like&#160;labels." } [/block] <h4> schema.json Entries </h4> The examples below, excerpted from the `schema.json` file in Stencil's base Cornerstone theme, define two labels: ```json { "name": "Footer", "settings": [ [...] { "type": "text", "label": "SSL Common Name", "force_reload": true, "id": "geotrust_ssl_common_name" }, [...] ] }, { [...] { "name": "Google AMP (beta)", "settings": [ { "type": "text", "label": "AMP Analytics ID", "id": "amp_analytics_id" } ] } ] ``` <h4> config.json Entries </h4> Here are the corresponding keys in Cornerstone's `config.json` file: ```json [...] "settings": { "amp_analytics_id": "", [...] "geotrust_ssl_common_name": "", [...] ```