{"_id":"57d328da2239653600498bf4","project":"55a6e72e8cc73e0d00096635","__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"},"user":"55a6caa022cfa321008e01d6","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"},"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-09-09T21:25:46.358Z","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\": \"Stencil's Custom Templates workflow defines separate roles for developers versus merchants. Developers perform the steps on this page:\\n\\n<ul>\\n <li><A href=\\\"#Author\\\"> Authoring Templates </a></li>\\n <li><A href=\\\"#Test\\\"> Local Mapping and Testing </a></li>\\n <li><A href=\\\"#Submit\\\"> Theme Submission </a></li>\\n <li><A href=\\\"#Trouble\\\"> Troubleshooting Template Authoring </a></li>\\n</ul>\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"If you are developing for your own store, the \\\"merchant\\\"/\\\"authorized store user\\\" role mentioned throughout these instructions overlaps with your developer role.\",\n  \"title\": \"In-House Developers\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h2> <A NAME=\\\"Author\\\"></a> Authoring Templates </h2>\\n\\nAs a the theme developer, you must first create the template HTML files, and then place them in the appropriate <NOBR><span class=\\\"inline-code\\\">&lt;theme-name&gt;/templates/pages/custom/</span></nobr> subdirectories corresponding to the types listed above. Those subdirectories are shown at the leaf level of the directory tree below:<p></p>\\n\\n<pre>&lt;theme-name&gt;\\n└── templates\\n  ├── pages\\n  │   ├── custom\\n  |   │   ├── brand\\n  |   │   ├── category\\n  |   │   ├── product\\n  |   │   ├── page\\n</pre><p></p>\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Subdirectory/File Permissions Required\",\n  \"body\": \"Be sure to set permission `755` (`drwxr-x-r-x`) on any new subdirectories that you add. \\nAlso, be sure to set permission `644` (`rw-r–r–`) on any new files that you add.\\n\\nWithout these permissions, running your theme locally will fail with multiple error messages.  \\nBundling your theme will also fail, blocking its upload to a store.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h2> <A NAME=\\\"Test\\\"></a> Local Mapping and Testing </h2>\\n\\nTo test your custom templates locally, you must edit your <NOBR><span class=\\\"inline-code\\\">&lt;theme-name&gt;/.stencil</span></nobr> file to create mappings between each local template and a corresponding URL. Within that file, look for the following section:<p></p>\\n\\n<pre>\\n  \\\"customLayouts\\\": {\\n    \\\"product\\\": {},\\n    \\\"search\\\": {},\\n    \\\"brand\\\": {},\\n    \\\"category\\\": {},\\n    \\\"page\\\": {}\\n  }\\n</pre><p></p>\\n\\nIn this section, you would populate keys to create mappings. As a simple example, assume that you have a product custom template named <NOBR><span class=\\\"inline-code\\\">alternate-product.html</span></nobr>, and you want to see that template locally at the URL: <NOBR><span class=\\\"inline-code\\\">http://localhost:3000/test-url/</span></nobr>. In this case, you must populate the <span class=\\\"inline-code\\\">product</span> key as follows:<p></p>\\n\\n<pre>\\n    \\\"product\\\": {\\n    \\t\\\"alternate-product.html\\\":\\\"/test-url/\\\"\\n    },\\n</pre><p></p>\\n\\n<h3> <A NAME=\\\"MapEx\\\"></a> Expanded Mapping Example </h3>\\n\\nHere is a more-complete example in which the <span class=\\\"inline-code\\\">brand</span>, <span class=\\\"inline-code\\\">page</span>, and <span class=\\\"inline-code\\\">category</span> keys are also populated:<p></p>\\n\\n<pre>\\n{\\n  \\\"normalStoreUrl\\\": \\\"http://cornerstone-light-demo.mybigcommerce.com\\\",\\n  \\\"port\\\": 3000,\\n  \\\"username\\\": \\\"stencil\\\",\\n  \\\"token\\\": \\\"xxxxxxxxxxxxxxxxxxxxxxxxxxxxx\\\",\\n  \\\"customLayouts\\\": {\\n    \\\"search\\\": {},\\n    \\\"product\\\": {\\n      \\\"custom_product.html\\\": \\\"/custom-product/\\\"\\n    },\\n    \\\"brand\\\": {\\n      \\\"custom_brand.html\\\": \\\"/brands/custombrand/\\\"\\n    },\\n    \\\"page\\\": {\\n      \\\"custom_page.html\\\": \\\"/custom-page/\\\"\\n    },\\n    \\\"category\\\": {\\n      \\\"custom_category.html\\\": \\\"/custom-category/\\\"\\n    }\\n  }\\n}\\n</pre>\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Mapping Requirements and Options\",\n  \"body\": \"In the `.stencil` mapping examples above:\\n\\n* Each mapped URL must be a URL for a brand, category, product, or static page that is _already configured_ in the store. (So you cannot insert a placeholder URL that is an arbitrary string of letters, such as `/abcdefghijklmnop/`.)\\n* Each URL’s trailing slash is optional.\\n* The HTML files must reside in the specific subdirectories shown above under <a href=\\\"#Author\\\">Authoring</a>.\\n* All brand URLs are nested under the `/brands/` parent. Use URL encoding with brand URLs.\\n* That parent for brand URLs is `/brands/` (plural), while the corresponding subdirectory for HTML files is `/brand/` (singular).\\n* After editing your `.stencil` file, you must restart stencil to see your changes locally. Enter \\n`stencil start` on the command line, appending any appropriate switches for your workflow \\n(e.g.: `stencil start -e -n`).\"\n}\n[/block]\n### Why These URL Requirements?\n\nWhen you create a local custom template page for products, you expect that page to have access to all Stencil product objects. However, the server cannot readily determine the page type of each local custom template. \nSo we must give it a hint: We do so by instructing the server to look at the page type of the _URL to which you have mapped_ the template.\n\nIn the above `.stencil` configuration [example](#MapEx)’s final entry, the server will look at the URL `/custom‑category/` within the store, deduce that the page type is \"category,\" and return a category context to Stencil CLI. This allows Stencil CLI to properly display the page in the browser when you visit [http://localhost:3000/custom‑category/](http://localhost:3000/custom‑category/) locally, or when shoppers visit the corresponding public store page.\n\n### <span id=\"MapArray\"> Mapping Multiple URLs </span>\n\nBeyond the single URL mapped to each template in the [above examples](#MapEx), you have the option of mapping an array of URLs to each template. This is shown in the following example for the `product` template:\n\n```{\n  \"customLayouts\": {\n    \"product\": {\n      \"featured-product.html\": [\"/special-product-one\", \"/special-product-two\"],\n      \"clearance-product.html\": \"/clearance-product\"\n    },\n    \"search\": {},\n    \"brands\": {},\n    \"categories\": {}\n  }\n}```\n[block:html]\n{\n  \"html\": \"<h2 style=\\\"margin-top: 1.5em\\\"> <A NAME=\\\"Submit\\\"></a> Theme Submission </h2>\\n\\nFinally, you must <a href=\\\"/docs/staging-and-submitting-a-theme\\\">bundle and upload</a> the theme to BigCommerce.<br>\\n<p></p>\\n\\n\\n<h2 style=\\\"margin-top: 1.5em\\\"> <A NAME=\\\"Trouble\\\"></a> Troubleshooting Template Authoring </h2>\\n\\nHere are solutions to some known problems in locally authoring and testing custom templates:\\n\\n<!-- In case of problems <a href=\\\"/docs/assigning-templates-to-pages\\\">assigning</a> a custom template in the control panel: Check whether your theme's root directory contains a file named <span class=\\\"inline-code\\\">manifest.json</span>.<br><p></p> \\n\\nIf so, delete the <span class=\\\"inline-code\\\">manifest.json</span> file, then again <a href=\\\"/docs/bundling-submitting#ship-zip-small\\\">bundle</a>, upload, and apply the theme. This should enable assigning the template in the control panel. -->\\n\\n<h3> Viewing Custom Brand Templates Locally </h3> \\n\\nIf you are having trouble viewing custom brand templates locally, ensure that the URL used in your <span class=\\\"inline-code\\\">.stencil</span> file is of the form: <span class=\\\"inline-code\\\">/brands/brandname</span>. This is necessary because all the brand pages are located under the <span class=\\\"inline-code\\\">/brands/</span> URL path.<br><p></p>\\n\\nAlso, bear in mind that currently, all brand URLs are Unicode-encoded. So, for example, you should replace a hyphen with: <span class=\\\"inline-code\\\">%252d</span>.<br><p></p>\\n\\n<h3> Outdated Stencil CLI </h3>\\n\\nIf you have an old version of Stencil CLI installed, it might lack support for custom templates. You can easily update your CLI by executing the following command:<p></p>\\n\\n<pre>npm install -g bigcommerce/stencil-cli\\n</pre>\"\n}\n[/block]","excerpt":"","slug":"authoring-custom-templates","type":"basic","title":"Authoring, Testing, and Uploading Custom Templates"}

Authoring, Testing, and Uploading Custom Templates


[block:html] { "html": "Stencil's Custom Templates workflow defines separate roles for developers versus merchants. Developers perform the steps on this page:\n\n<ul>\n <li><A href=\"#Author\"> Authoring Templates </a></li>\n <li><A href=\"#Test\"> Local Mapping and Testing </a></li>\n <li><A href=\"#Submit\"> Theme Submission </a></li>\n <li><A href=\"#Trouble\"> Troubleshooting Template Authoring </a></li>\n</ul>" } [/block] [block:callout] { "type": "info", "body": "If you are developing for your own store, the \"merchant\"/\"authorized store user\" role mentioned throughout these instructions overlaps with your developer role.", "title": "In-House Developers" } [/block] [block:html] { "html": "<h2> <A NAME=\"Author\"></a> Authoring Templates </h2>\n\nAs a the theme developer, you must first create the template HTML files, and then place them in the appropriate <NOBR><span class=\"inline-code\">&lt;theme-name&gt;/templates/pages/custom/</span></nobr> subdirectories corresponding to the types listed above. Those subdirectories are shown at the leaf level of the directory tree below:<p></p>\n\n<pre>&lt;theme-name&gt;\n└── templates\n ├── pages\n │ ├── custom\n | │ ├── brand\n | │ ├── category\n | │ ├── product\n | │ ├── page\n</pre><p></p>" } [/block] [block:callout] { "type": "danger", "title": "Subdirectory/File Permissions Required", "body": "Be sure to set permission `755` (`drwxr-x-r-x`) on any new subdirectories that you add. \nAlso, be sure to set permission `644` (`rw-r–r–`) on any new files that you add.\n\nWithout these permissions, running your theme locally will fail with multiple error messages. \nBundling your theme will also fail, blocking its upload to a store." } [/block] [block:html] { "html": "<h2> <A NAME=\"Test\"></a> Local Mapping and Testing </h2>\n\nTo test your custom templates locally, you must edit your <NOBR><span class=\"inline-code\">&lt;theme-name&gt;/.stencil</span></nobr> file to create mappings between each local template and a corresponding URL. Within that file, look for the following section:<p></p>\n\n<pre>\n \"customLayouts\": {\n \"product\": {},\n \"search\": {},\n \"brand\": {},\n \"category\": {},\n \"page\": {}\n }\n</pre><p></p>\n\nIn this section, you would populate keys to create mappings. As a simple example, assume that you have a product custom template named <NOBR><span class=\"inline-code\">alternate-product.html</span></nobr>, and you want to see that template locally at the URL: <NOBR><span class=\"inline-code\">http://localhost:3000/test-url/</span></nobr>. In this case, you must populate the <span class=\"inline-code\">product</span> key as follows:<p></p>\n\n<pre>\n \"product\": {\n \t\"alternate-product.html\":\"/test-url/\"\n },\n</pre><p></p>\n\n<h3> <A NAME=\"MapEx\"></a> Expanded Mapping Example </h3>\n\nHere is a more-complete example in which the <span class=\"inline-code\">brand</span>, <span class=\"inline-code\">page</span>, and <span class=\"inline-code\">category</span> keys are also populated:<p></p>\n\n<pre>\n{\n \"normalStoreUrl\": \"http://cornerstone-light-demo.mybigcommerce.com\",\n \"port\": 3000,\n \"username\": \"stencil\",\n \"token\": \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n \"customLayouts\": {\n \"search\": {},\n \"product\": {\n \"custom_product.html\": \"/custom-product/\"\n },\n \"brand\": {\n \"custom_brand.html\": \"/brands/custombrand/\"\n },\n \"page\": {\n \"custom_page.html\": \"/custom-page/\"\n },\n \"category\": {\n \"custom_category.html\": \"/custom-category/\"\n }\n }\n}\n</pre>" } [/block] [block:callout] { "type": "warning", "title": "Mapping Requirements and Options", "body": "In the `.stencil` mapping examples above:\n\n* Each mapped URL must be a URL for a brand, category, product, or static page that is _already configured_ in the store. (So you cannot insert a placeholder URL that is an arbitrary string of letters, such as `/abcdefghijklmnop/`.)\n* Each URL’s trailing slash is optional.\n* The HTML files must reside in the specific subdirectories shown above under <a href=\"#Author\">Authoring</a>.\n* All brand URLs are nested under the `/brands/` parent. Use URL encoding with brand URLs.\n* That parent for brand URLs is `/brands/` (plural), while the corresponding subdirectory for HTML files is `/brand/` (singular).\n* After editing your `.stencil` file, you must restart stencil to see your changes locally. Enter \n`stencil start` on the command line, appending any appropriate switches for your workflow \n(e.g.: `stencil start -e -n`)." } [/block] ### Why These URL Requirements? When you create a local custom template page for products, you expect that page to have access to all Stencil product objects. However, the server cannot readily determine the page type of each local custom template. So we must give it a hint: We do so by instructing the server to look at the page type of the _URL to which you have mapped_ the template. In the above `.stencil` configuration [example](#MapEx)’s final entry, the server will look at the URL `/custom‑category/` within the store, deduce that the page type is "category," and return a category context to Stencil CLI. This allows Stencil CLI to properly display the page in the browser when you visit [http://localhost:3000/custom‑category/](http://localhost:3000/custom‑category/) locally, or when shoppers visit the corresponding public store page. ### <span id="MapArray"> Mapping Multiple URLs </span> Beyond the single URL mapped to each template in the [above examples](#MapEx), you have the option of mapping an array of URLs to each template. This is shown in the following example for the `product` template: ```{ "customLayouts": { "product": { "featured-product.html": ["/special-product-one", "/special-product-two"], "clearance-product.html": "/clearance-product" }, "search": {}, "brands": {}, "categories": {} } }``` [block:html] { "html": "<h2 style=\"margin-top: 1.5em\"> <A NAME=\"Submit\"></a> Theme Submission </h2>\n\nFinally, you must <a href=\"/docs/staging-and-submitting-a-theme\">bundle and upload</a> the theme to BigCommerce.<br>\n<p></p>\n\n\n<h2 style=\"margin-top: 1.5em\"> <A NAME=\"Trouble\"></a> Troubleshooting Template Authoring </h2>\n\nHere are solutions to some known problems in locally authoring and testing custom templates:\n\n<!-- In case of problems <a href=\"/docs/assigning-templates-to-pages\">assigning</a> a custom template in the control panel: Check whether your theme's root directory contains a file named <span class=\"inline-code\">manifest.json</span>.<br><p></p> \n\nIf so, delete the <span class=\"inline-code\">manifest.json</span> file, then again <a href=\"/docs/bundling-submitting#ship-zip-small\">bundle</a>, upload, and apply the theme. This should enable assigning the template in the control panel. -->\n\n<h3> Viewing Custom Brand Templates Locally </h3> \n\nIf you are having trouble viewing custom brand templates locally, ensure that the URL used in your <span class=\"inline-code\">.stencil</span> file is of the form: <span class=\"inline-code\">/brands/brandname</span>. This is necessary because all the brand pages are located under the <span class=\"inline-code\">/brands/</span> URL path.<br><p></p>\n\nAlso, bear in mind that currently, all brand URLs are Unicode-encoded. So, for example, you should replace a hyphen with: <span class=\"inline-code\">%252d</span>.<br><p></p>\n\n<h3> Outdated Stencil CLI </h3>\n\nIf you have an old version of Stencil CLI installed, it might lack support for custom templates. You can easily update your CLI by executing the following command:<p></p>\n\n<pre>npm install -g bigcommerce/stencil-cli\n</pre>" } [/block]