317 lines
14 KiB
JSON
317 lines
14 KiB
JSON
|
{
|
||
|
|
"__ATTN__": "Do not edit this file; changes belong in the appropriate YAML file.",
|
||
|
|
"overview": "Rationale: this special notation was introduced primarily to allow the dynamic\nloading of partials. The main advantage that this notation offers is to allow\ndynamic loading of partials, which is particularly useful in cases where\npolymorphic data needs to be rendered in different ways. Such cases would\notherwise be possible to render only with solutions that are convoluted,\ninefficient, or both.\n\nExample.\nLet's consider the following data:\n\n items: [\n { content: 'Hello, World!' },\n { url: 'http://example.com/foo.jpg' },\n { content: 'Some text' },\n { content: 'Some other text' },\n { url: 'http://example.com/bar.jpg' },\n { url: 'http://example.com/baz.jpg' },\n { content: 'Last text here' }\n ]\n\nThe goal is to render the different types of items in different ways. The\nitems having a key named `content` should be rendered with the template\n`text.mustache`:\n\n {{!text.mustache}}\n {{content}}\n\nAnd the items having a key named `url` should be rendered with the template\n`image.mustache`:\n\n {{!image.mustache}}\n <img src=\"{{url}}\"/>\n\nThere are already several ways to achieve this goal, here below are\nillustrated and discussed the most significant solutions to this problem.\n\nUsing Pre-Processing\n\nThe idea is to use a secondary templating mechanism to dynamically generate\nthe template that will be rendered.\nThe template that our secondary templating mechanism generates might look\nlike this:\n\n {{!template.mustache}}\n {{items.1.content}}\n <img src=\"{{items.2.url}}\"/>\n {{items.3.content}}\n {{items.4.content}}\n <img src=\"{{items.5.url}}\"/>\n <img src=\"{{items.6.url}}\"/>\n {{items.7.content}}\n\nThis solutions offers the advantages of having more control over the template\nand minimizing the template blocks to the essential ones.\nThe drawbacks are the rendering speed and the complexity that the secondary\ntemplating mechanism requires.\n\nUsing Lambdas\n\nThe idea is to inject functions into the data that will be later called from\nthe template.\nThis way the data will look like this:\n\n items: [\n {\n content: 'Hello, World!',\n html: function() { return '{{>text}}'; }\n },\n {\n url: 'http://example.com/foo.jpg',\n html: function() { return '{{>image}}'; }\n },\n {\n content: 'Some text',\n html: function() { return '{{>text}}'; }\n },\n {\n content: 'Some other text',\n html: function() { return '{{>text}}'; }\n },\n {\n url: 'http://example.com/bar.jpg',\n html: function() { return '{{>image}}'; }\n },\n {\n url: 'http://example.com/baz.jpg',\n html: function() { return '{{>image}}'; }\n },\n {\n content: 'Last text here',\n html: function() { return '{{>text}}'; }\n }\n ]\n\nAnd the template will look like this:\n\n {{!template.mustache}}\n {{#items}}\n {{{html}}}\n {{/items}}\n\nThe advantage this solution offers is to have a light main template.\nThe drawback is that the data needs to embed logic and template tags in\nit.\n\nUsing If-Else Blocks\n\nThe idea is to put some logic into the main template so it can select the\ntemplates at rendering time:\n\n {{!template.mustache}}\n {{#items}}\n {{#url}}\n {{>image}}\n {{/url}}\n {{#content}}\n {{>text}}\n {{/content}}\n {{/items}}\n\nThe main advantage of this solution is that it works without adding any\noverhead fields to the data. It also documents which external templates are\nappropriate for expansion in this position.\nThe drawback is that this solution isn't optimal for heterogeneous data sets\nas the main template grows linearly with the number of polymorphic variants.\n\nUsing Dynamic Names\n\nThis is the solution proposed by this spec.\nThe idea is to load partials dynamically.\nThis way the data items have to be tagged with the corresponding partial name:\n\n items: [\n { content: 'Hello, World!', dyn
|
||
|
|
"tests": [
|
||
|
|
{
|
||
|
|
"name": "Basic Behavior - Partial",
|
||
|
|
"desc": "The asterisk operator is used for dynamic partials.",
|
||
|
|
"data": {
|
||
|
|
"dynamic": "content"
|
||
|
|
},
|
||
|
|
"template": "\"{{>*dynamic}}\"",
|
||
|
|
"partials": {
|
||
|
|
"content": "Hello, world!"
|
||
|
|
},
|
||
|
|
"expected": "\"Hello, world!\""
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Basic Behavior - Name Resolution",
|
||
|
|
"desc": "The asterisk is not part of the name that will be resolved in the context.\n",
|
||
|
|
"data": {
|
||
|
|
"dynamic": "content",
|
||
|
|
"*dynamic": "wrong"
|
||
|
|
},
|
||
|
|
"template": "\"{{>*dynamic}}\"",
|
||
|
|
"partials": {
|
||
|
|
"content": "Hello, world!",
|
||
|
|
"wrong": "Invisible"
|
||
|
|
},
|
||
|
|
"expected": "\"Hello, world!\""
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Context Misses - Partial",
|
||
|
|
"desc": "Failed context lookups should be considered falsey.",
|
||
|
|
"data": {
|
||
|
|
},
|
||
|
|
"template": "\"{{>*missing}}\"",
|
||
|
|
"partials": {
|
||
|
|
"missing": "Hello, world!"
|
||
|
|
},
|
||
|
|
"expected": "\"\""
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Failed Lookup - Partial",
|
||
|
|
"desc": "The empty string should be used when the named partial is not found.",
|
||
|
|
"data": {
|
||
|
|
"dynamic": "content"
|
||
|
|
},
|
||
|
|
"template": "\"{{>*dynamic}}\"",
|
||
|
|
"partials": {
|
||
|
|
"foobar": "Hello, world!"
|
||
|
|
},
|
||
|
|
"expected": "\"\""
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Context",
|
||
|
|
"desc": "The dynamic partial should operate within the current context.",
|
||
|
|
"data": {
|
||
|
|
"text": "Hello, world!",
|
||
|
|
"example": "partial"
|
||
|
|
},
|
||
|
|
"template": "\"{{>*example}}\"",
|
||
|
|
"partials": {
|
||
|
|
"partial": "*{{text}}*"
|
||
|
|
},
|
||
|
|
"expected": "\"*Hello, world!*\""
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Dotted Names",
|
||
|
|
"desc": "The dynamic partial should operate within the current context.",
|
||
|
|
"data": {
|
||
|
|
"text": "Hello, world!",
|
||
|
|
"foo": {
|
||
|
|
"bar": {
|
||
|
|
"baz": "partial"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"template": "\"{{>*foo.bar.baz}}\"",
|
||
|
|
"partials": {
|
||
|
|
"partial": "*{{text}}*"
|
||
|
|
},
|
||
|
|
"expected": "\"*Hello, world!*\""
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Dotted Names - Operator Precedence",
|
||
|
|
"desc": "The dotted name should be resolved entirely before being dereferenced.",
|
||
|
|
"data": {
|
||
|
|
"text": "Hello, world!",
|
||
|
|
"foo": "test",
|
||
|
|
"test": {
|
||
|
|
"bar": {
|
||
|
|
"baz": "partial"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"template": "\"{{>*foo.bar.baz}}\"",
|
||
|
|
"partials": {
|
||
|
|
"partial": "*{{text}}*"
|
||
|
|
},
|
||
|
|
"expected": "\"\""
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Dotted Names - Failed Lookup",
|
||
|
|
"desc": "The dynamic partial should operate within the current context.",
|
||
|
|
"data": {
|
||
|
|
"foo": {
|
||
|
|
"text": "Hello, world!",
|
||
|
|
"bar": {
|
||
|
|
"baz": "partial"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"template": "\"{{>*foo.bar.baz}}\"",
|
||
|
|
"partials": {
|
||
|
|
"partial": "*{{text}}*"
|
||
|
|
},
|
||
|
|
"expected": "\"**\""
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Dotted names - Context Stacking",
|
||
|
|
"desc": "Dotted names should not push a new frame on the context stack.",
|
||
|
|
"data": {
|
||
|
|
"section1": {
|
||
|
|
"value": "section1"
|
||
|
|
},
|
||
|
|
"section2": {
|
||
|
|
"dynamic": "partial",
|
||
|
|
"value": "section2"
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"template": "{{#section1}}{{>*section2.dynamic}}{{/section1}}",
|
||
|
|
"partials": {
|
||
|
|
"partial": "\"{{value}}\""
|
||
|
|
},
|
||
|
|
"expected": "\"section1\""
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Dotted names - Context Stacking Under Repetition",
|
||
|
|
"desc": "Dotted names should not push a new frame on the context stack.",
|
||
|
|
"data": {
|
||
|
|
"value": "test",
|
||
|
|
"section1": [
|
||
|
|
1,
|
||
|
|
2
|
||
|
|
],
|
||
|
|
"section2": {
|
||
|
|
"dynamic": "partial",
|
||
|
|
"value": "section2"
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"template": "{{#section1}}{{>*section2.dynamic}}{{/section1}}",
|
||
|
|
"partials": {
|
||
|
|
"partial": "{{value}}"
|
||
|
|
},
|
||
|
|
"expected": "testtest"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Dotted names - Context Stacking Failed Lookup",
|
||
|
|
"desc": "Dotted names should resolve against the proper context stack.",
|
||
|
|
"data": {
|
||
|
|
"section1": [
|
||
|
|
1,
|
||
|
|
2
|
||
|
|
],
|
||
|
|
"section2": {
|
||
|
|
"dynamic": "partial",
|
||
|
|
"value": "section2"
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"template": "{{#section1}}{{>*section2.dynamic}}{{/section1}}",
|
||
|
|
"partials": {
|
||
|
|
"partial": "\"{{value}}\""
|
||
|
|
},
|
||
|
|
"expected": "\"\"\"\""
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Recursion",
|
||
|
|
"desc": "Dynamic partials should properly recurse.",
|
||
|
|
"data": {
|
||
|
|
"template": "node",
|
||
|
|
"content": "X",
|
||
|
|
"nodes": [
|
||
|
|
{
|
||
|
|
"content": "Y",
|
||
|
|
"nodes": [
|
||
|
|
|
||
|
|
]
|
||
|
|
}
|
||
|
|
]
|
||
|
|
},
|
||
|
|
"template": "{{>*template}}",
|
||
|
|
"partials": {
|
||
|
|
"node": "{{content}}<{{#nodes}}{{>*template}}{{/nodes}}>"
|
||
|
|
},
|
||
|
|
"expected": "X<Y<>>"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Dynamic Names - Double Dereferencing",
|
||
|
|
"desc": "Dynamic Names can't be dereferenced more than once.",
|
||
|
|
"data": {
|
||
|
|
"dynamic": "test",
|
||
|
|
"test": "content"
|
||
|
|
},
|
||
|
|
"template": "\"{{>**dynamic}}\"",
|
||
|
|
"partials": {
|
||
|
|
"content": "Hello, world!"
|
||
|
|
},
|
||
|
|
"expected": "\"\""
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Dynamic Names - Composed Dereferencing",
|
||
|
|
"desc": "Dotted Names are resolved entirely before dereferencing begins.",
|
||
|
|
"data": {
|
||
|
|
"foo": "fizz",
|
||
|
|
"bar": "buzz",
|
||
|
|
"fizz": {
|
||
|
|
"buzz": {
|
||
|
|
"content": null
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"template": "\"{{>*foo.*bar}}\"",
|
||
|
|
"partials": {
|
||
|
|
"content": "Hello, world!"
|
||
|
|
},
|
||
|
|
"expected": "\"\""
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Surrounding Whitespace",
|
||
|
|
"desc": "A dynamic partial should not alter surrounding whitespace; any\nwhitespace preceding the tag should be treated as indentation while any\nwhitespace succeding the tag should be left untouched.\n",
|
||
|
|
"data": {
|
||
|
|
"partial": "foobar"
|
||
|
|
},
|
||
|
|
"template": "| {{>*partial}} |",
|
||
|
|
"partials": {
|
||
|
|
"foobar": "\t|\t"
|
||
|
|
},
|
||
|
|
"expected": "| \t|\t |"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Inline Indentation",
|
||
|
|
"desc": "Whitespace should be left untouched: whitespaces preceding the tag\nshould be treated as indentation.\n",
|
||
|
|
"data": {
|
||
|
|
"dynamic": "partial",
|
||
|
|
"data": "|"
|
||
|
|
},
|
||
|
|
"template": " {{data}} {{>*dynamic}}\n",
|
||
|
|
"partials": {
|
||
|
|
"partial": ">\n>"
|
||
|
|
},
|
||
|
|
"expected": " | >\n>\n"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Standalone Line Endings",
|
||
|
|
"desc": "\"\\r\\n\" should be considered a newline for standalone tags.",
|
||
|
|
"data": {
|
||
|
|
"dynamic": "partial"
|
||
|
|
},
|
||
|
|
"template": "|\r\n{{>*dynamic}}\r\n|",
|
||
|
|
"partials": {
|
||
|
|
"partial": ">"
|
||
|
|
},
|
||
|
|
"expected": "|\r\n>|"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Standalone Without Previous Line",
|
||
|
|
"desc": "Standalone tags should not require a newline to precede them.",
|
||
|
|
"data": {
|
||
|
|
"dynamic": "partial"
|
||
|
|
},
|
||
|
|
"template": " {{>*dynamic}}\n>",
|
||
|
|
"partials": {
|
||
|
|
"partial": ">\n>"
|
||
|
|
},
|
||
|
|
"expected": " >\n >>"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Standalone Without Newline",
|
||
|
|
"desc": "Standalone tags should not require a newline to follow them.",
|
||
|
|
"data": {
|
||
|
|
"dynamic": "partial"
|
||
|
|
},
|
||
|
|
"template": ">\n {{>*dynamic}}",
|
||
|
|
"partials": {
|
||
|
|
"partial": ">\n>"
|
||
|
|
},
|
||
|
|
"expected": ">\n >\n >"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Standalone Indentation",
|
||
|
|
"desc": "Each line of the partial should be indented before rendering.",
|
||
|
|
"data": {
|
||
|
|
"dynamic": "partial",
|
||
|
|
"content": "<\n->"
|
||
|
|
},
|
||
|
|
"template": "\\\n {{>*dynamic}}\n/\n",
|
||
|
|
"partials": {
|
||
|
|
"partial": "|\n{{{content}}}\n|\n"
|
||
|
|
},
|
||
|
|
"expected": "\\\n |\n <\n->\n |\n/\n"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Padding Whitespace",
|
||
|
|
"desc": "Superfluous in-tag whitespace should be ignored.",
|
||
|
|
"data": {
|
||
|
|
"dynamic": "partial",
|
||
|
|
"boolean": true
|
||
|
|
},
|
||
|
|
"template": "|{{> * dynamic }}|",
|
||
|
|
"partials": {
|
||
|
|
"partial": "[]"
|
||
|
|
},
|
||
|
|
"expected": "|[]|"
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|