can/view/mustache/mustache.js

mustache.js

can.Mustache: The Mustache templating engine. See the Transformation section within Scanning Helpers for a detailed explanation of the runtime render code design. The majority of the Mustache engine implementation occurs within the Transformation scanning helper.

Initialization

Define the view extension.

Setup internal helper variables and functions.

An alias for the context variable used for tracking a stack of contexts. This is also used for passing to helper functions to maintain proper context.

An alias for the variable used for the hash object that can be passed to helpers via options.hash.

An alias for the function that adds a new context to the context stack.

An alias for the most used context stacking call.

Mustache

Support calling Mustache without the constructor. This returns a function that renders the template.

If we get a function directly, it probably is coming from a steal-packaged view.

Set options on self.

Put Mustache on the can object.

Share a singleton scanner for parsing templates.

A hash of strings for the scanner to inject at certain points.

This is the logic to inject at the beginning of a rendered template. This includes initializing the context stack.

Handle helpers with custom contexts (#228)

An ordered token registry for the scanner. This needs to be ordered by priority to prevent token parsing errors. Each token follows the following structure: [ // Which key in the token map to match. "tokenMapName", // A simple token to match, like "{{". "token", // Optional. A complex (regexp) token to match that // overrides the simple token. "[\s\t]*{{", // Optional. A function that executes advanced // manipulation of the matched content. This is // rarely used. function(content){
return content; } ]

Return unescaped

Full line comments

Inline comments

Full line escapes This is used for detecting lines with only whitespace and an escaped tag

Return escaped

Close return unescaped

Close tag

Scanning Helpers

This is an array of helpers that transform content that is within escaped tags like {{token}}. These helpers are solely for the scanning phase; they are unrelated to Mustache/Handlebars helpers which execute at render time. Each helper has a definition like the following: { // The content pattern to match in order to execute. // Only the first matching helper is executed. name: /pattern to match/, // The function to transform the content with. // @param {String} content The content to transform. // @param {Object} cmd Scanner helper data. // { // insert: "insert command", // tagName: "div", // status: 0 // } fn: function(content, cmd) { return 'for text injection' || { raw: 'to bypass text injection' }; } }

Partials

Partials begin with a greater than sign, like {{> box}}. Partials are rendered at runtime (as opposed to compile time), so recursive partials are possible. Just avoid infinite loops. For example, this template and partial: base.mustache:

Names

Get the template name and call back into the render method, passing the name and the current context.

Data Hookup

This will attach the data property of this to the element its found on using the first argument as the data attribute key. For example:

return a function which calls can.data on the element with the attribute name with the current context.

Transformation (default)

This transforms all content to its interpolated equivalent, including calls to the corresponding helpers as applicable. This outputs the render code for almost all cases.

Definitions

• context - This is the object that the current rendering context operates within. Each nested template adds a new context to the context stack.
• stack - Mustache supports nested sections, each of which add their own context to a stack of contexts. Whenever a token gets interpolated, it will check for a match against the last context in the stack, then iterate through the rest of the stack checking for matches. The first match is the one that gets returned.
• Mustache.txt - This serializes a collection of logic, optionally contained within a section. If this is a simple interpolation, only the interpolation lookup will be passed. If this is a section, then an options object populated by the truthy (options.fn) and falsey (options.inverse) encapsulated functions will also be passed. This section handling exists to support the runtime context nesting that Mustache supports.
• Mustache.get - This resolves an interpolation reference given a stack of contexts.
• options - An object containing methods for executing the inner contents of sections or helpers.
  options.fn - Contains the inner template logic for a truthy section.
  options.inverse - Contains the inner template logic for a falsey section.
  options.hash - Contains the merged hash object argument for custom helpers.

Design

This covers the design of the render code that the transformation helper generates.

Pseudocode

A detailed explanation is provided in the following sections, but here is some brief pseudocode that gives a high level overview of what the generated render code does (with a template similar to
"{{#a}}{{b.c.d.e.name}}{{/a}}" == "Phil"). Initialize the render code. view = [] context = [] stack = fn { context.concat([this]) } Render the root section. view.push( "string" ) view.push( can.view.txt( Render the nested section with can.Mustache.txt. txt( Add the current context to the stack. stack(), Flag this for truthy section mode. "#", Interpolate and check the a variable for truthyness using the stack with can.Mustache.get. get( "a", stack() ), Include the nested section's inner logic. The stack argument is usually the parent section's copy of the stack, but it can be an override context that was passed by a custom helper. Sections can nest 0..n times -- NESTCEPTION. { fn: fn(stack) { Render the nested section (everything between the {{#a}} and {{/a}} tokens). view = [] view.push( "string" ) view.push( Add the current context to the stack. stack(), Flag this as interpolation-only mode. null, Interpolate the b.c.d.e.name variable using the stack. get( "b.c.d.e.name", stack() ), ) view.push( "string" ) Return the result for the nested section. return view.join() }} ) )) view.push( "string" ) Return the result for the root section, which includes all nested sections. return view.join()

Initialization

Each rendered template is started with the following initialization code: var v1ew = []; var _c0nt3xt = []; c0nt3xt.st4ck = true; var st4ck = function(context, self) { var s; if (arguments.length == 1 && context) { s = !context.st4ck ? [context] : context; } else { s = context && context.st4ck ? context.concat([self]) : st4ck(context).concat([self]); } return (s.__st4ck = true) && s; }; The ___v1ew is the the array used to serialize the view. The ___c0nt3xt is a stacking array of contexts that slices and expands with each nested section. The ___st4ck function is used to more easily update the context stack in certain situations. Usually, the stack function simply adds a new context (self/this) to a context stack. However, custom helpers will occasionally pass override contexts that need their own context stack.

Sections

Each section, {{#section}} content {{/section}}, within a Mustache template generates a section context in the resulting render code. The template itself is treated like a root section, with the same execution logic as any others. Each section can have 0..n nested sections within it. Here's an example of a template without any descendent sections.
Given the template: "{{a.b.c.d.e.name}}" == "Phil"
Would output the following render code: v1ew.push("\""); _v1ew.push(can.view.txt(1, '', 0, this, function() { return can.Mustache.txt(st4ck(c0nt3xt, this), null, can.Mustache.get("a.b.c.d.e.name", st4ck(c0nt3xt, this)) ); })); v1ew.push("\" == \"Phil\""); The simple strings will get appended to the view. Any interpolated references (like {{a.b.c.d.e.name}}) will be pushed onto the view via can.view.txt in order to support live binding. The function passed to can.view.txt will call can.Mustache.txt, which serializes the object data by doing a context lookup with can.Mustache.get. can.Mustache.txt's first argument is a copy of the context stack with the local context this added to it. This stack will grow larger as sections nest. The second argument is for the section type. This will be "#" for truthy sections, "^" for falsey, or null if it is an interpolation instead of a section. The third argument is the interpolated value retrieved with can.Mustache.get, which will perform the context lookup and return the approriate string or object. Any additional arguments, if they exist, are used for passing arguments to custom helpers. For nested sections, the last argument is an options object that contains the nested section's logic. Here's an example of a template with a single nested section.
Given the template: "{{#a}}{{b.c.d.e.name}}{{/a}}" == "Phil"
Would output the following render code: v1ew.push("\""); v1ew.push(can.view.txt(0, '', 0, this, function() { return can.Mustache.txt(st4ck(c0nt3xt, this), "#", can.Mustache.get("a", st4ck(c0nt3xt, this)), [{ : function() { return _v1ew.join(""); } }, { fn: function(c0nt3xt) { var v1ew = []; v1ew.push(can.view.txt(1, '', 0, this, function() { return can.Mustache.txt( st4ck(c0nt3xt, this), null, can.Mustache.get("b.c.d.e.name", st4ck(c0nt3xt, this)) ); } )); return v1ew.join(""); } }] ) })); __v1ew.push("\" == \"Phil\""); This is specified as a truthy section via the "#" argument. The last argument includes an array of helper methods used with options. These act similarly to custom helpers: options.fn will be called for truthy sections, options.inverse will be called for falsey sections. The options._ function only exists as a dummy function to make generating the section nesting easier (a section may have a fn, inverse, or both, but there isn't any way to determine that at compilation time). Within the fn function is the section's render context, which in this case will render anything between the {{#a}} and {{/a}} tokens. This function has ___c0nt3xt as an argument because custom helpers can pass their own override contexts. For any case where custom helpers aren't used, ___c0nt3xt will be equivalent to the ___st4ck(___c0nt3xt, this) stack created by its parent section. The inverse function works similarly, except that it is added when {{^a}} and {{else}} are used. var ___v1ew = [] is specified in fn and inverse to ensure that live binding in nested sections works properly. All of these nested sections will combine to return a compiled string that functions similar to EJS in its uses of can.view.txt.

Implementation

Trim the content so we don't have any trailing whitespace.

Determine what the active mode is. * # - Truthy section * ^ - Falsey section * / - Close the prior section * else - Inverted section (only exists within a truthy/falsey section)

Open a new section.

Close the prior section.

Trim the mode off of the content.

else helpers are special and should be skipped since they don't have any logic aside from kicking off an inverse function.

Parse the helper arguments. This needs uses this method instead of a split(/\s/) so that strings with spaces can be correctly parsed.

Start the content render block.

Iterate through the helper arguments, if there are any.

Check for special helper arguments (string/number/boolean/hashes).

Found a native type like string/number/boolean.

Found a hash object.

Open the hash object.

Add the key/value.

Close the hash if this was the last argument.

Otherwise output a normal interpolation reference.

Include the reference name.

Then the stack of context.

Flag as a helper method to aid performance, if it is a known helper (anything with > 0 arguments).

Create an option object for sections of code.

Truthy section

If/else section Falsey section

Not a section

Return a raw result if there was a section, otherwise return the default string.

Add in default scanner helpers first. We could probably do this differently if we didn't 'break' on every match.

Grab the extra arguments to pass to helpers.

Create a default options object to pass to the helper.

Check for a registered helper or a helper-like function.

Use the most recent context as this for the helper.

Update the options with a function/inverse (the inner templates of a section).

Add the hash to options if one exists

Call the helper.

if a compute, get the value

An array of arguments to check for truthyness when evaluating sections.

Whether the arguments meet the condition of the section.

Validate the arguments based on the section mode.

Array-like objects are falsey if their length = 0.

Use .attr to trigger binding on empty lists returned from function

Otherwise just check if it is truthy or not.

Otherwise interpolate like normal.

Truthy section.

Iterate over arrays

Add the reference to the list in the contexts.

Ensure that live update works on observable lists

Normal case.

Falsey section.

Add + '' to convert things like numbers to strings. This can cause issues if you are trying to eval on the length but this is the more common case.

Split the reference (like a.b.c) into an array of key names.

Assume the local object is the last context in the stack.

Assume the parent context is the second to last context in the stack.

if we walk up and don't find a property, we default to listening on an undefined property of the first context that is an observe

Handle this references for list iteration: {{.}} or {{this}}

If context isn't an object, then it was a value passed by a helper so use it as an override.

Otherwise just return the closest object.

Handle object resolution (like a.b.c).

Reverse iterate through the contexts (last in, first out).

Check the context for the reference

Make sure the context isn't a failed object before diving into it.

Keep running up the tree while there are matches.

If it's undefined, still match if the parent is an Observe.

Found a matched reference.

Don't execute functions if they are parameters for a helper and are not a can.compute Need to bind it to the original context so that that information doesn't get lost by the helper

Support functions stored in objects.

Invoke the length to ensure that Observe.List events fire.

Add support for observes

if there's not a helper by this name and no attribute with this name

Support helper-like functions as anonymous helpers

Support helpers without arguments, but only if there wasn't a matching data reference.

Helpers

Helpers are functions that can be called from within a template. These helpers differ from the scanner helpers in that they execute at runtime instead of during compilation. Custom helpers can be added via can.Mustache.registerHelper, but there are also some built-in helpers included by default. Most of the built-in helpers are little more than aliases to actions that the base version of Mustache simply implies based on the passed in object. Built-in helpers: * data - data is a special helper that is implemented via scanning helpers. It hooks up the active element to the active data object: <div {{data "key"}} /> * if - Renders a truthy section: {{#if var}} render {{/if}} * unless - Renders a falsey section: {{#unless var}} render {{/unless}} * each - Renders an array: {{#each array}} render {{this}} {{/each}} * with - Opens a context section: {{#with var}} render {{/with}}

Find the correct helper

Make sure the partial being passed in isn't a variable like { partial: "foo.mustache" }

Call into can.view.render passing the partial and context.

The built-in Mustache helpers.

Implements the if built-in helper.

Implements the unless built-in helper.

Implements the each built-in helper.

Implements the with built-in helper.

Registration

Registers Mustache with can.view.

Returns a function that renders the view.