Glow-project Glow → 2.0

Proposed templating system for Glow.

Provisional api (but still needs discussion):

 /**
@name glow.lang.template
@function
@description Replaces placeholders in a string with data from an object

@param {String} template The string containing {placeholders}
@param {Object} data Object containing the data to be merged in to the template.
    The object can contain nested data objects and arrays, with nested object
    properties and array elements are accessed using dot notation. eg foo.bar
    or foo.0.
    
    Data labels can contain an optional pipe symbol and filter function to use
    from {@link glow.lang.filters}. Eg, for html encoding you would use <code>{dataLabel|h}</code>.
    You can add your own filters via the options object.
    
    The data labels in the object cannot contain characters used in the template
    delimiters, so if the data must be allowed to contain the default { and }
    delimiters, the delimiters must be changed using the option below.
@param {Object} opts Options object
    @param {String} [opts.delimiter="{}"] Alternative label delimiter(s) for the template
        The first character supplied will be the opening delimiter, and the
        second the closing. If only one character is supplied, it will be used
        for both ends.
    @param {Object} [opts.filters] Additional filter functions to use when processing data labels
        These are in addition to those in {@link glow.lang.filters}.
        
        Filter functions take a single parameter and are expected to return a filtered
        parameter.
    @param {Boolean} [opts.escapeHtml] Escape all replaced content for html injection
        Escaping will happen after the element has been filtered. To escape
        individual values, use {placeholder|h}.

@returns {String}

@example
    var data = {
        content: 'This is inside a <div>'
    }
    var template = '<div>{content|h}</div>';
    var result = glow.lang.template(template, data);
    // result == "<div>This is inside a &lt;div&gt;</div>"
    
@example
    var data = {
        val: 1.234
    }
    var template = 'The value is {val|round}';
    var result = glow.lang.template(template, data, {
        filters: {
            round: function(val) {
                return Math.round(val);
            }
        }
    });
    // result == "The value is 1"
*/

/**
@name glow.lang.filters
@namespace
@description Functions which take a simple value and return another

  These can also be used by {@link glow.lang.template}
*/

/**
@name glow.lang.filters.h
@function
@description Returns a string with special HTML characters escaped.

@param {String} str The string to escape

@returns {String} Escaped string

@example
    glow.lang.filters.h('The <canvas> & <section> elements are new to HTML5');
    // returns 'The &lt;canvas&gt; &amp; &lt;section&gt; elements are new to HTML5'
    
@example
    var data = {
        content: 'This is inside a <div>'
    }
    var template = '<div>{content|h}</div>';
    var result = glow.lang.interpolate(template, data);
    // result == "<div>This is inside a &lt;div&gt;</div>"
*/