{"_id":"5608f79f8aedf50d0004cfb4","user":"55a6caa022cfa321008e01d6","__v":33,"category":{"_id":"58105ad54a8aa50f00aa4cba","__v":0,"project":"55a6e72e8cc73e0d00096635","version":"55a6e72f8cc73e0d00096638","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-10-26T07:27:17.418Z","from_sync":false,"order":8,"slug":"front-matter-attributes","title":"Front-Matter Attributes"},"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,"project":"55a6e72e8cc73e0d00096635","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-28T08:17:35.390Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:html]\n{\n  \"html\": \"Front-matter attributes offer you a loosely structured method for declaring specific objects on a given page. <NOBR>This overview</nobr> covers:<br>\\n\\n<ul>\\n  <!-- <li><a href=\\\"#about\\\">About Front-Matter Attributes</a></li> -->\\n  <li><a href=\\\"#InstantNewProd\\\">Declaring Objects</a></li>\\n  <li><a href=\\\"#syntax\\\">YAML Syntax &ndash; Requirements</a></li>\\n <li><a href=\\\"#FilterObj\\\">Filtering Attributes</a></li>\\n <li><a href=\\\"#FrontnHB\\\">Combining Front Matter with Handlebars Attributes</a></li>\\n <li><a href=\\\"#DefvsCustom\\\">Default versus Custom Attributes, per Page</a></li>\\n <li><a href=\\\"#MultInvoke\\\">Declaring Multiple Attributes</a></li>\\n</ul>\\n\\nThe next entry covers:\\n<ul>\\n  <li><a href=\\\"/docs/front-matter-variables\\\">Attributes [Front-Matter] Reference</a></li>\\n</ul>\\n\\n\\n<!-- <h2> <a name=\\\"about\\\"></a>About Front-Matter Attributes</h2> -->\\n\\n<h2> <a name=\\\"InstantNewProd\\\"></a>Declaring Objects</h2> \\n\\nWhen you create a store page that requires access to specific attributes (such as featured products, or customer information), you must first declare the attributes by including a front-matter block at the top of the page's template file.<br>\\n\\n<p></p>For example, you could use the following front matter to declare the <a href=\\\"/docs/product-resources#Product\\\"><span class=\\\"inline-code\\\">products</span> object</a>, with its <span class=\\\"inline-code\\\">new</span> attribute. <NOBR>This would</nobr> allow a storefront page to display a \\\"New Products\\\" section:<br>\\n\\n<p></p><pre>\\n---\\nproducts:\\n    new:\\n---</pre>\\n\\nThe attribute will then be accessible in that page's context: You will be able to access the attribute’s value by including <a href=\\\"/docs/developing-with-handlebars\\\">Handlebars</a> double braces around the attribute’s name in your HTML code.<br>\"\n}\n[/block]\n<h2> <a name=\"syntax\"></a>YAML Syntax – Requirements</h2>\n\nStencil front matter uses the conventions of <a href=\"http://yaml.org/\">YAML</a> (short for the recursive \"YAML Ain't Markup Language\"). Therefore,&#160;here are the YAML conventions you must follow in front matter:\n[block:html]\n{\n  \"html\": \" <!-- However, note that Stencil front matter ain't YAML. Whereas YAML itself allows the instantiation of new objects, Stencil front matter only allows you to invoke existing attributes. -->\"\n}\n[/block]\n  * Place the front-matter block at the top of your template.\n  * Fence the beginning and end of the front-matter block with a row of three hyphens (`---`), as you see in the examples here.\n  * Show attribute > key (or object > property) relationships by indenting the children. \n  * Place a colon (:) directly after each attribute name, and directly after each key name. (Colons separate key:value pairs.)\n  * Identifiers are case-sensitive.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Restrictions\",\n  \"body\": \"* You can use front matter to specify attributes on the tops of pages in your \\n<span class=\\\"inline-code\\\">&lt;theme-name&gt;/templates/pages/</span> subdirectory. \\n\\n* However, you _cannot_ use front matter to accomplish this on pages in your \\n<span class=\\\"inline-code\\\">&lt;theme-name&gt;/templates/components/</span>, \\n<span class=\\\"inline-code\\\">&lt;theme-name&gt;/templates/layout/</span>, or \\n<span class=\\\"inline-code\\\">&lt;theme-name&gt;/templates/pages/custom/</span> subdirectories.\\n\\n* Indent using _only_ spaces, not tabs. (YAML forbids tabs, to avoid inconsistent encoding of tabs across platforms.) An indent of even one space indicates a child.\\n\\n* Front matter on a given page cannot exceed 64 KB.\\n\\n* If a front-matter directive contains an invalid option, Stencil CLI will silently ignore that option.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h2> <A NAME=\\\"FilterObj\\\"></a>Filtering Attributes</h2>\\n\\nSome attributes can accept indented keys, or key-value pairs, to further define the attribute. For example, <span class=\\\"inline-code\\\">limit</span> is a key commonly used to restrict the number of objects to return for an attribute.<br>\\n\\t<p></p>\\nTo return products similar to the product that a customer is currently viewing – with a limit of six – you would declare front matter as follows:<br><p></p>\\n\\n<pre>\\n---\\nproducts:\\n    similar_by_views:\\n        limit: 6\\n---</pre>\\n\\nMost keys have a default value, as listed in the <a href=\\\"/docs/front-matter-variables\\\">Attributes  Reference</a>. Specifying the key without a value will call that default value. The default value for <span class=\\\"inline-code\\\">similar_by_views:limit:</span> happens to be <span class=\\\"inline-code\\\">4</span>, so inserting <span class=\\\"inline-code\\\">limit</span> with no integer will display four products:<br><p></p>\\n\\n<pre>\\n---\\nproducts:\\n    similar_by_views:\\n        limit:\\n---</pre>\\n\\n<!-- <i>(Note:</i> <span class=\\\"inline-code\\\">related_products</span> <i>is another front-matter </i> <a href=\\\"/docs/front-matter-variables#config-theme-settings\\\">global attribute</a><i>.)</i><br> -->\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Filtering for Faster Page Loads\",\n  \"body\": \"To keep your pages lightweight, specify only the attributes you need per page. Also, use the `limit` key (with&#160;appropriate values) for attributes that accept it.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h2> <A NAME=\\\"FrontnHB\\\"></a>Combining Front Matter with Handlebars Attributes</h2>\\n\\nThe next example builds on front-matter object invocation and filtering, by showing a corresponding Handlebars statement in HTML. Here is how you would declare the <span class=\\\"inline-code\\\">products</span> object to return four new products, and to then display each product’s name:<br><p></p>\\n\\n<pre>\\n---\\nproducts:\\n    new:\\n        limit: 4\\n---\\n\\n&lt;h1&gt; This is the HTML for the new-products example &lt;/h1&gt;\\n{{#each products.new}}\\n    &lt;p&gt;{{ name }}&lt;/p&gt;\\n{{/each}}</pre>\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Reading the Handlebars\",\n  \"body\": \"In the above HTML, the <span class=\\\"inline-code\\\">{{ name }}</span> identifier calls an attribute of Stencil’s <a href=\\\"/docs/common-product-card-model\\\">common product card model</a>, which consolidates details about a given product. For this and other objects that you can access through HTML, please see our reference section on  <a href=\\\"/docs/stencil-object-model\\\">Handlebars objects</a>.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h2> <A NAME=\\\"DefvsCustom\\\"></a>Default versus Custom Attributes, per Page</h2>\\n\\nTo make templates readily useful, they automatically include a page’s default attributes. For example, a theme’s <span class=\\\"inline-code\\\">product.html</span> page will automatically include a <span class=\\\"inline-code\\\">product</span> attribute.<br><br>\\n\\nHowever, if you want to include additional attributes on a page, you can declare those attributes in front matter using the conventions shown above. (The <a href=\\\"#InstantNewProd\\\">Declaring Objects</a> example shows the <i>only</i> way to display a \\\"new products\\\" storefront section, which <i>requires</i> front-matter invocation.)<br>\\n\\n<h2> <A NAME=\\\"MultInvoke\\\"></a>Declaring Multiple Attributes</h2>\\n\\nBelow is an example that assumes you want to include a product’s reviews and also related products. To display <i>images</i> for the related products, the HTML statement <NOBR><span class=\\\"inline-code\\\">&lt;img src=\\\"{{getImage image 'gallery'}}\\\"&gt;</span></nobr> relies on Stencil's <span class=\\\"inline-code\\\">{{getImage}}</span> <a href=\\\"/docs/handlebars-helpers-reference#image\\\">custom Handlebars helper</a>:<br><p></p>\\n\\n<pre>\\n---\\nproduct:\\n   reviews:\\n       limit: 9\\n   related_products:\\n       limit: 10\\n---\\n\\n\\n&lt;h2&gt;{{ product.name }}&lt;/h2&gt;\\n{{#each product.reviews.list}}\\n    &lt;p&gt;{{text}}&lt;/p&gt;\\n{{/each}}\\n&lt;h3&gt;Related Products&lt;/h3&gt;\\n{{#each product.related_products}}\\n  &lt;img src=\\\"{{getImage image 'gallery'}}\\\"&gt;\\n  &lt;p&gt;{{ name }}&lt;/p&gt;\\n{{/each}}</pre>\\n\\n\\nNext:\\n<ul>\\n  <li><a href=\\\"/docs/front-matter-variables\\\">Attributes [Front-Matter] Reference</a></li>\\n</ul>\"\n}\n[/block]","excerpt":"","slug":"using-yaml-front-matter","type":"basic","title":"Attributes: Using Front Matter"}

Attributes: Using Front Matter


[block:html] { "html": "Front-matter attributes offer you a loosely structured method for declaring specific objects on a given page. <NOBR>This overview</nobr> covers:<br>\n\n<ul>\n <!-- <li><a href=\"#about\">About Front-Matter Attributes</a></li> -->\n <li><a href=\"#InstantNewProd\">Declaring Objects</a></li>\n <li><a href=\"#syntax\">YAML Syntax &ndash; Requirements</a></li>\n <li><a href=\"#FilterObj\">Filtering Attributes</a></li>\n <li><a href=\"#FrontnHB\">Combining Front Matter with Handlebars Attributes</a></li>\n <li><a href=\"#DefvsCustom\">Default versus Custom Attributes, per Page</a></li>\n <li><a href=\"#MultInvoke\">Declaring Multiple Attributes</a></li>\n</ul>\n\nThe next entry covers:\n<ul>\n <li><a href=\"/docs/front-matter-variables\">Attributes [Front-Matter] Reference</a></li>\n</ul>\n\n\n<!-- <h2> <a name=\"about\"></a>About Front-Matter Attributes</h2> -->\n\n<h2> <a name=\"InstantNewProd\"></a>Declaring Objects</h2> \n\nWhen you create a store page that requires access to specific attributes (such as featured products, or customer information), you must first declare the attributes by including a front-matter block at the top of the page's template file.<br>\n\n<p></p>For example, you could use the following front matter to declare the <a href=\"/docs/product-resources#Product\"><span class=\"inline-code\">products</span> object</a>, with its <span class=\"inline-code\">new</span> attribute. <NOBR>This would</nobr> allow a storefront page to display a \"New Products\" section:<br>\n\n<p></p><pre>\n---\nproducts:\n new:\n---</pre>\n\nThe attribute will then be accessible in that page's context: You will be able to access the attribute’s value by including <a href=\"/docs/developing-with-handlebars\">Handlebars</a> double braces around the attribute’s name in your HTML code.<br>" } [/block] <h2> <a name="syntax"></a>YAML Syntax – Requirements</h2> Stencil front matter uses the conventions of <a href="http://yaml.org/">YAML</a> (short for the recursive "YAML Ain't Markup Language"). Therefore,&#160;here are the YAML conventions you must follow in front matter: [block:html] { "html": " <!-- However, note that Stencil front matter ain't YAML. Whereas YAML itself allows the instantiation of new objects, Stencil front matter only allows you to invoke existing attributes. -->" } [/block] * Place the front-matter block at the top of your template. * Fence the beginning and end of the front-matter block with a row of three hyphens (`---`), as you see in the examples here. * Show attribute > key (or object > property) relationships by indenting the children. * Place a colon (:) directly after each attribute name, and directly after each key name. (Colons separate key:value pairs.) * Identifiers are case-sensitive. [block:callout] { "type": "warning", "title": "Restrictions", "body": "* You can use front matter to specify attributes on the tops of pages in your \n<span class=\"inline-code\">&lt;theme-name&gt;/templates/pages/</span> subdirectory. \n\n* However, you _cannot_ use front matter to accomplish this on pages in your \n<span class=\"inline-code\">&lt;theme-name&gt;/templates/components/</span>, \n<span class=\"inline-code\">&lt;theme-name&gt;/templates/layout/</span>, or \n<span class=\"inline-code\">&lt;theme-name&gt;/templates/pages/custom/</span> subdirectories.\n\n* Indent using _only_ spaces, not tabs. (YAML forbids tabs, to avoid inconsistent encoding of tabs across platforms.) An indent of even one space indicates a child.\n\n* Front matter on a given page cannot exceed 64 KB.\n\n* If a front-matter directive contains an invalid option, Stencil CLI will silently ignore that option." } [/block] [block:html] { "html": "<h2> <A NAME=\"FilterObj\"></a>Filtering Attributes</h2>\n\nSome attributes can accept indented keys, or key-value pairs, to further define the attribute. For example, <span class=\"inline-code\">limit</span> is a key commonly used to restrict the number of objects to return for an attribute.<br>\n\t<p></p>\nTo return products similar to the product that a customer is currently viewing – with a limit of six – you would declare front matter as follows:<br><p></p>\n\n<pre>\n---\nproducts:\n similar_by_views:\n limit: 6\n---</pre>\n\nMost keys have a default value, as listed in the <a href=\"/docs/front-matter-variables\">Attributes Reference</a>. Specifying the key without a value will call that default value. The default value for <span class=\"inline-code\">similar_by_views:limit:</span> happens to be <span class=\"inline-code\">4</span>, so inserting <span class=\"inline-code\">limit</span> with no integer will display four products:<br><p></p>\n\n<pre>\n---\nproducts:\n similar_by_views:\n limit:\n---</pre>\n\n<!-- <i>(Note:</i> <span class=\"inline-code\">related_products</span> <i>is another front-matter </i> <a href=\"/docs/front-matter-variables#config-theme-settings\">global attribute</a><i>.)</i><br> -->" } [/block] [block:callout] { "type": "info", "title": "Filtering for Faster Page Loads", "body": "To keep your pages lightweight, specify only the attributes you need per page. Also, use the `limit` key (with&#160;appropriate values) for attributes that accept it." } [/block] [block:html] { "html": "<h2> <A NAME=\"FrontnHB\"></a>Combining Front Matter with Handlebars Attributes</h2>\n\nThe next example builds on front-matter object invocation and filtering, by showing a corresponding Handlebars statement in HTML. Here is how you would declare the <span class=\"inline-code\">products</span> object to return four new products, and to then display each product’s name:<br><p></p>\n\n<pre>\n---\nproducts:\n new:\n limit: 4\n---\n\n&lt;h1&gt; This is the HTML for the new-products example &lt;/h1&gt;\n{{#each products.new}}\n &lt;p&gt;{{ name }}&lt;/p&gt;\n{{/each}}</pre>" } [/block] [block:callout] { "type": "info", "title": "Reading the Handlebars", "body": "In the above HTML, the <span class=\"inline-code\">{{ name }}</span> identifier calls an attribute of Stencil’s <a href=\"/docs/common-product-card-model\">common product card model</a>, which consolidates details about a given product. For this and other objects that you can access through HTML, please see our reference section on <a href=\"/docs/stencil-object-model\">Handlebars objects</a>." } [/block] [block:html] { "html": "<h2> <A NAME=\"DefvsCustom\"></a>Default versus Custom Attributes, per Page</h2>\n\nTo make templates readily useful, they automatically include a page’s default attributes. For example, a theme’s <span class=\"inline-code\">product.html</span> page will automatically include a <span class=\"inline-code\">product</span> attribute.<br><br>\n\nHowever, if you want to include additional attributes on a page, you can declare those attributes in front matter using the conventions shown above. (The <a href=\"#InstantNewProd\">Declaring Objects</a> example shows the <i>only</i> way to display a \"new products\" storefront section, which <i>requires</i> front-matter invocation.)<br>\n\n<h2> <A NAME=\"MultInvoke\"></a>Declaring Multiple Attributes</h2>\n\nBelow is an example that assumes you want to include a product’s reviews and also related products. To display <i>images</i> for the related products, the HTML statement <NOBR><span class=\"inline-code\">&lt;img src=\"{{getImage image 'gallery'}}\"&gt;</span></nobr> relies on Stencil's <span class=\"inline-code\">{{getImage}}</span> <a href=\"/docs/handlebars-helpers-reference#image\">custom Handlebars helper</a>:<br><p></p>\n\n<pre>\n---\nproduct:\n reviews:\n limit: 9\n related_products:\n limit: 10\n---\n\n\n&lt;h2&gt;{{ product.name }}&lt;/h2&gt;\n{{#each product.reviews.list}}\n &lt;p&gt;{{text}}&lt;/p&gt;\n{{/each}}\n&lt;h3&gt;Related Products&lt;/h3&gt;\n{{#each product.related_products}}\n &lt;img src=\"{{getImage image 'gallery'}}\"&gt;\n &lt;p&gt;{{ name }}&lt;/p&gt;\n{{/each}}</pre>\n\n\nNext:\n<ul>\n <li><a href=\"/docs/front-matter-variables\">Attributes [Front-Matter] Reference</a></li>\n</ul>" } [/block]