{"_id":"57d33f9f2239653600498c05","user":"55a6caa022cfa321008e01d6","__v":1,"category":{"_id":"560b5cbec341310d00de2a01","pages":["560b5d0b3616ac17004f1c99","560b5d405148ba0d009bd0c9","560b5d62af40a70d003df332","560b5d953bcbd80d0077d0fd","560b5fa83616ac17004f1c9d","569c8c15d326c80d0068f7b7","56d37d35d3f4650b007495ea","56d4ed5f8001e30b0089700c"],"__v":8,"project":"55a6e72e8cc73e0d00096635","version":"55a6e72f8cc73e0d00096638","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-30T03:53:34.449Z","from_sync":false,"order":14,"slug":"templates-required-directory","title":"Templates Reference"},"parentDoc":null,"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"},"project":"55a6e72e8cc73e0d00096635","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-09-09T23:02:55.453Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":8,"body":"[block:html]\n{\n  \"html\": \"When a merchant changes the theme applied to their store, the Stencil framework assigns custom templates to store pages in different ways, depending on the scenario:\\n\\n<ul>\\n <li><a href=\\\"#bp-to-stencil\\\"> Switching between Blueprint and Stencil Themes </a>\\n  </li>\\n <li><a href=\\\"#stencil-to-stencil\\\"> Switching among Stencil Themes </a>\\n  </li> \\n</ul>\\n\\n<h2> <a name=\\\"bp-to-stencil\\\"></a> Switching between Blueprint and Stencil Themes </h2>\\n\\nThe mapping of custom templates to store pages is stored in different ways for Blueprint versus Stencil themes. Once merchants enter this mapping, BigCommerce retains it separately for each platform.<br><p></p>\\n\\nSo if a merchant using a Blueprint theme has set up custom templates, then the very first time they switch to a Stencil theme, they will need to re-enter their mapping of templates to pages.<br><p></p>\\n\\nHowever, if the merchant later switches back to a Blueprint theme, their original Blueprint mappings will take effect. If they then switch to a Stencil theme, their Stencil mappings will take effect again &ndash; as long as that Stencil theme contains templates with file names identical to those in their first Stencil theme.<br><p></p>\\n\\n\\n<h2> <a name=\\\"stencil-to-stencil\\\"></a> Switching among Stencil Themes </h2>\\n\\nIf a merchant using a Stencil theme switches to a different Stencil theme, custom templates are mapped as follows:<br><p></p>\\n\\nWhere the new Stencil theme has a custom template of the same name, BigCommerce will automatically assign that template to the same store page.<br><p></p>\\n\\nWhere the new Stencil theme lacks a custom template of the same name, the merchant will see a control-panel annotation that BigCommerce is falling back to the new theme's <i>default</i> template for this page. The merchant will have the option of using the assignment drop-down list to select a different custom template available in the new theme.<br><p></p>\\n\\nIf the merchant later switches back to their original Stencil theme, the control panel will show them the names of the custom templates previously assigned to store pages.\\n\\n<!--\\n<h2> Theme Updates </h2>\\n\\nThe Stencil framework supports two theme-update scenarios, in different ways:\\n\\n<ul>\\n\\t<li><b>Custom Templates Conserved:</b> When a merchant updates a Stencil theme to a new version, BigCommerce will retain any mappings of custom templates to store pages, as long as the new version contains custom templates of the same names.<p></p></li>\\n\\n\\t<li><b>Custom Template Withdrawn:</b> Where a theme developer removes a custom template that a merchant has previously applied to store pages, BigCommerce will apply the new theme's <i>default</i> template to affected store pages.</li>\\n(Forthcoming is a control-panel warning about this, offering merchants the opportunity to select a different custom template. This will work the same way as described above for switching between <i>different</i> Stencil themes. But as of 6/17/16, this fallback is silent.)\\n</ul>\\n\\n<h1> <A NAME=\\\"Limits\\\"></a> Limitations </h1>\\n\\nStencil custom templates are constrained by the following limitations:\\n\\n<h2> Manual Assignment Only </h2>\\n\\nWe currently do not support assigning templates to pages via API, nor via bulk CSV export/import. An authorized user must manually assign templates to pages via the store's control panel.\\n\\n<h2> 200-Template Maximum </h2>\\n\\nA Stencil theme's bundle cannot contain more than 200 templates. Both default and custom templates count against that limit.<br><p></p>\\n\\nFor example, Stencil's base Cornerstone theme contains nearly 50 default templates, leaving room for about 150 custom templates. Bundling more than 200 templates will trigger an error message.\\n\\n<h1> <A NAME=\\\"Future\\\"></a> Future Enhancements </h1>\\n\\nAs BigCommerce further develops the Stencil framework, we expect to add further options for handling custom templates:\\n\\n<ul>\\n <li>Once BigCommerce has enabled automatic uploads of custom Stencil themes, we anticipate that merchants will be able to add custom template files to a local version of their theme, <a href=\\\"/docs/bundling-submitting#ship-zip-small\\\">re-bundle their theme</a> (using Stencil CLI), and then re-upload the theme to their store.\\n  </li>\\n \\n  <li>For cases where a merchant applies a new theme that does not support custom templates previously configured for the store, we ultimately plan to provide real-time warnings by popping up a message box.\\n  </li>\\n  \\n <li>We anticipate adding an \\\"Import/Export\\\" user interface, by which merchants will be able to update their mappings of custom templates to store pages. This centralized interface would offer merchants a simpler workflow, compared to updating template assignments in multiple control-panel locations.\\n  </li>\\n</ul>-->\"\n}\n[/block]","excerpt":"","slug":"switching-themes-with-custom-templates","type":"basic","title":"Switching Themes with Custom Templates"}

Switching Themes with Custom Templates


[block:html] { "html": "When a merchant changes the theme applied to their store, the Stencil framework assigns custom templates to store pages in different ways, depending on the scenario:\n\n<ul>\n <li><a href=\"#bp-to-stencil\"> Switching between Blueprint and Stencil Themes </a>\n </li>\n <li><a href=\"#stencil-to-stencil\"> Switching among Stencil Themes </a>\n </li> \n</ul>\n\n<h2> <a name=\"bp-to-stencil\"></a> Switching between Blueprint and Stencil Themes </h2>\n\nThe mapping of custom templates to store pages is stored in different ways for Blueprint versus Stencil themes. Once merchants enter this mapping, BigCommerce retains it separately for each platform.<br><p></p>\n\nSo if a merchant using a Blueprint theme has set up custom templates, then the very first time they switch to a Stencil theme, they will need to re-enter their mapping of templates to pages.<br><p></p>\n\nHowever, if the merchant later switches back to a Blueprint theme, their original Blueprint mappings will take effect. If they then switch to a Stencil theme, their Stencil mappings will take effect again &ndash; as long as that Stencil theme contains templates with file names identical to those in their first Stencil theme.<br><p></p>\n\n\n<h2> <a name=\"stencil-to-stencil\"></a> Switching among Stencil Themes </h2>\n\nIf a merchant using a Stencil theme switches to a different Stencil theme, custom templates are mapped as follows:<br><p></p>\n\nWhere the new Stencil theme has a custom template of the same name, BigCommerce will automatically assign that template to the same store page.<br><p></p>\n\nWhere the new Stencil theme lacks a custom template of the same name, the merchant will see a control-panel annotation that BigCommerce is falling back to the new theme's <i>default</i> template for this page. The merchant will have the option of using the assignment drop-down list to select a different custom template available in the new theme.<br><p></p>\n\nIf the merchant later switches back to their original Stencil theme, the control panel will show them the names of the custom templates previously assigned to store pages.\n\n<!--\n<h2> Theme Updates </h2>\n\nThe Stencil framework supports two theme-update scenarios, in different ways:\n\n<ul>\n\t<li><b>Custom Templates Conserved:</b> When a merchant updates a Stencil theme to a new version, BigCommerce will retain any mappings of custom templates to store pages, as long as the new version contains custom templates of the same names.<p></p></li>\n\n\t<li><b>Custom Template Withdrawn:</b> Where a theme developer removes a custom template that a merchant has previously applied to store pages, BigCommerce will apply the new theme's <i>default</i> template to affected store pages.</li>\n(Forthcoming is a control-panel warning about this, offering merchants the opportunity to select a different custom template. This will work the same way as described above for switching between <i>different</i> Stencil themes. But as of 6/17/16, this fallback is silent.)\n</ul>\n\n<h1> <A NAME=\"Limits\"></a> Limitations </h1>\n\nStencil custom templates are constrained by the following limitations:\n\n<h2> Manual Assignment Only </h2>\n\nWe currently do not support assigning templates to pages via API, nor via bulk CSV export/import. An authorized user must manually assign templates to pages via the store's control panel.\n\n<h2> 200-Template Maximum </h2>\n\nA Stencil theme's bundle cannot contain more than 200 templates. Both default and custom templates count against that limit.<br><p></p>\n\nFor example, Stencil's base Cornerstone theme contains nearly 50 default templates, leaving room for about 150 custom templates. Bundling more than 200 templates will trigger an error message.\n\n<h1> <A NAME=\"Future\"></a> Future Enhancements </h1>\n\nAs BigCommerce further develops the Stencil framework, we expect to add further options for handling custom templates:\n\n<ul>\n <li>Once BigCommerce has enabled automatic uploads of custom Stencil themes, we anticipate that merchants will be able to add custom template files to a local version of their theme, <a href=\"/docs/bundling-submitting#ship-zip-small\">re-bundle their theme</a> (using Stencil CLI), and then re-upload the theme to their store.\n </li>\n \n <li>For cases where a merchant applies a new theme that does not support custom templates previously configured for the store, we ultimately plan to provide real-time warnings by popping up a message box.\n </li>\n \n <li>We anticipate adding an \"Import/Export\" user interface, by which merchants will be able to update their mappings of custom templates to store pages. This centralized interface would offer merchants a simpler workflow, compared to updating template assignments in multiple control-panel locations.\n </li>\n</ul>-->" } [/block]