path and inserts it as child members of this node.
*/
importTemplate: function( path, selector )
{
selector = selector || 'body';
var tmpl = new markuper.Template( path );
var nodes = tmpl.select( selector );
var html = '';
if( !nodes ) { return; }
// FIXME: need to change the select function
if ( nodes.length )
{
for( var i = 0, node; node = nodes[i]; i++ )
{
html += node.innerHTML;
}
}
else
{
html = nodes.innerHTML;
}
this.innerHTML = html;
},
_template: null
}
/**
* Adds a set of properties from an object to a another specific object.
*
* If the element looksLikeArray then instead of just having the features appended to it, whenever one of the features is called it will be also called, with the same arguments, in every element of the array.
length property and if it can be accessed with [ix] notation.
*
* @param {Object} obj Object to be analysed.
* @returns {boolean} If it can be manipulated as an array or not.
*/
markuper.looksLikeArray = function( obj )
{
return obj instanceof Object
&& !(obj instanceof Node)
&& typeof( obj ) !== 'string'
&& typeof( obj[0] ) !== 'undefined';
}
/**
* Retrieves a specific value from an hierarchy tree of objects where data is the root.
*
* The value retrieved is the object located at key. This key is a String in a dot separated format that represents the path from the root element to the value.
var foo = {
* key1: 'value1',
* key2: {
* key3: 'value3'
* }
*};
*var v1 = getData( foo, 'key1' );
*var v2 = getData( foo, 'key2.key3' );
* In this example v1 will get the value 'value1' and v2 the value 'value3'.
*
* @param {Object} data The root object.
* @param {String} key The path to the value.
* @returns {Object|native} The value found at the path.
*/
markuper.getData = function( data, key )
{
if( key == null || data == undefined ) { return null };
var keys = key.split('.');
if( keys[0] in data )
{
if( keys.length > 1 && data[keys[0]] instanceof Object )
{
return arguments.callee( data[keys[0]], keys.slice(1).join('.') );
}
else
{
return data[keys[0]];
}
}
}
/**
* Sets a specific value in an hierarchy tree of objects where data is the root.
*
* The logic of the parameters is the very same as for {@link #.getData} with the adition of the value parameter which is the value to be setted at key.
* If the value parameter is null then the object at key will be removed from the hierarchy of objects.
*
Note that the value pointed to by key must exist.
textNode will have its textContent right timmed from ix till the end of the string.
* A new text node will be created with the contents of the trimmed text of textNode.textContent left trimmed length characters, and added to the document where textNode resides in a way that will make it the textNode.nextSibling.
*
This new text node will be returned by the function.
* * Example: *var textNode = document.createTextNode( 'This is a long text node' ); *var newNode = splitTextNode( textNode, 5, 3 );* After the function call we will have: *
| Expression | *Value | *
|---|---|
textNode.textContent |
* 'This ' |
*
newNode.textContent |
* 'a long text node' |
*
textNode.nextSibling == newNode |
* true |
*
textNode
* @param {int} length The index used for left trimming the remaing text of textNode's right trim.
* @returns {TextNode} The new text node created.
*/
markuper.splitTextNode = function( textNode, ix, length )
{
length = length || 0;
var document = textNode.ownerDocument;
var newTextContent = textNode.textContent.slice( ix + length );
var node = document.createTextNode( newTextContent );
var nextNode = textNode.nextSibling;
textNode.textContent = textNode.textContent.slice( 0, ix );
if( textNode.parentNode )
{
if( nextNode )
{
textNode.parentNode.insertBefore( node, nextNode );
}
else
{
textNode.parentNode.appendChild( node );
}
}
return node;
}
/**
* An enhanced version of Array.prototype.split.
*
* Besides the splitted values the resulting array will also have the delimiters * between the values that were splitter.
*This can be useful when you want to split using a RegExp but also know at the same time what text was considered a delimiter.
* * Example: **> splitWithDelimiters( 'xxxxaayyyybbzzzz', /aa|bb/ ); *['xxxx', 'aa, 'yyyy', 'bb', 'zzzz'];*/ markuper.splitWithDelimiters = function( str, regexp ) { var result = []; var lastIndex = 0; str.replace( regexp, function(match, offset) { result.push( str.slice( lastIndex, offset ) ); result.push( match ); lastIndex = offset + match.length; }); if( lastIndex < str.length-1 ) result.push( str.substr( lastIndex ) ); return result; } /** * @namespace Functions used for the evaluation of boolean expressions */ markuper.evaluator = {}; // mind the order /** * Operators supported by the expression evaluator. * *
{
* operator, // the text symbol used for the operator. if you want spaces
* // just provide the symbol with spaces.
* numberOp, // number of operands.
* typeOp, // if it's a 1 operand operator this field indicates if it's a 'prefix'
* // or 'suffix' operator.
* operation, // the function with the logic for the operator, it receives as
* // many boolean values as expected number of operands.
* }
*/
markuper.evaluator.operators =
[{
operator : '!',
numberOp : 1,
typeOp : 'prefix',
operation : function(op) { return !op; }
},
{
operator : '&&',
numberOp : 2,
operation : function(left, right) { return left && right; }
},
{
operator : '||',
numberOp : 2,
operation : function(left, right) { return left || right; }
}];
/**
* Field with the regexp used to split a simple boolean expression into an array
*/
markuper.evaluator.operatorsRegExp = (function()
{
var regexpArr = [];
for( var i=0,op; op=markuper.evaluator.operators[i]; i++ )
{
regexpArr.push( op.operator.replace( /[|]/g, '\\$&' ) );
}
// when there are operators that are prefix of another we want the bigger
// ones first, like ['!=', '!'] and not ['!', '!=']
regexpArr.sort().reverse();
return new RegExp( regexpArr.join( '|' ), 'g' );
})();
/**
* A wrapper for {@link markuper.getData} with support for 'true' and 'false' values
*
* @param {Object} data The data object.
* @param {String} key The index for the data object.
* @returns {Object|native} The value found in the data object by indexing it through key.
*/
markuper.evaluator.getBooleanValue = function( data, key )
{
var bools = {'true': true, 'false': false};
if( key.toLowerCase() in bools ) { return bools[key.toLowerCase()]; };
return !!markuper.getData( data, key );
}
/**
* Evaluates a simple boolean expression.
* A simple boolean expression is just like a boolean expression definined in {@link #.evalBooleanExpression} minus the grouping elements, or in other words, without parenthensis
. * Operators List *| Precedence Level | *Associates | *Operator | *Operation | *
|---|---|---|---|
| 1 | *Left | *! | *Logical Not | *
| 2 | *Left | *&& | *Logical And | *
| 3 | *Left | *|| | *Logical Or | *
data.isOwner && data.hasPermission || data.isFile
*
* @param {String} expr The simple boolean expression.
* @param {Data} data The data object to be indexed with the keys found in the expr expression.
* @returns {Boolean} The result of the evaluation of the expr expression.
*
* @see #.evalBooleanExpression
*/
markuper.evaluator.evalBooleanSimpleExpression = function( expr, data )
{
var operators = markuper.evaluator.operators;
var parsedExpr = markuper.splitWithDelimiters( expr, markuper.evaluator.operatorsRegExp );
// remove empty entries
for( var i=parsedExpr.length-1; i >= 0; i-- )
{
if( parsedExpr[i].match( /^\s*$/ ) ) { parsedExpr.splice( i, 1 ); }
}
var ix;
for( var i=0,op; op=operators[i]; i++ )
{
// search for the /op/ operator from left to right and replace it
// and its operands by the result of its evaluation
while( (ix = parsedExpr.indexOf( op.operator )) > -1 )
{
switch( op.numberOp )
{
case 1:
var offset = op.typeOp == 'prefix' ? 1 : -1,
operand = markuper.evaluator.getBooleanValue( data, parsedExpr[ix+offset].trim() ),
bool = op.operation( operand ) ? 'true' : 'false';
// replace the expression by its computed value
parsedExpr.splice( ix+(op.typeOp=='prefix'?0:-1), 2, bool );
break;
case 2:
var left = markuper.evaluator.getBooleanValue( data, parsedExpr[ix-1].trim() ),
right = markuper.evaluator.getBooleanValue( data, parsedExpr[ix+1].trim() ),
bool = op.operation( left, right ) ? 'true' : 'false';
// replace the expression by its computed value
parsedExpr.splice( ix-1, 3, bool );
break;
}
}
}
return markuper.evaluator.getBooleanValue( data, parsedExpr[0] );
}
/**
* Evaluates a boolean expression consisting of keys to the data structure, true, false, &&, || and grouping using parenthensis.
data.isOwner && (data.hasPermission || data.isFile)
* It's also possible to prepend true || to the expression to make it evaluate to true regardless of the rest of the expression.
true || data.isOwner && (data.hasPermission || data.isFile)
*
* @param {String} expr The expression to evalute.
* @param {Object} data The data object to be indexed with the keys found in the expr expression.
* @returns {Boolean} The result of the evaluation of the expr expression.
*
* @see #.evalBooleanSimpleExpression to find out the order of precedence
*/
markuper.evaluator.evalBooleanExpression = function( expr, data )
{
// WARNING: it doesn't short-circuit
// find the deepest group and substitute it for its value
// repeat until no more groups are found
var regexp = /\([^()]+\)/g;
while( expr.search(regexp) > -1 )
{
expr = expr.replace( regexp, function( smallexpr )
{
return markuper.evaluator.evalBooleanSimpleExpression( smallexpr.slice(0,-1).slice(1), data );
});
}
return markuper.evaluator.evalBooleanSimpleExpression( expr, data );
}
/**
* Helper function that searches up the hierarchy of node and tries to find any node parent that has one of the attributes specified in attrs.
*
* @param {Node} node The node that will have its parents searched.
* @param {Array} attrs Attributes to be found on the node's parents.
* @param {Node} [root=node.ownerDocument] If specified the hierarchical search will stop at that node
* @returns {Boolean} The result of the search.
*/
markuper.hasParentWithDataAttribute = function( node, attrs, root )
{
root = root || node.ownerDocument;
while( (node=node.parentNode) && node != root )
{
for( var j = 0, attr; attr = attrs[j]; j++ )
{
if( node.attributes.getNamedItem('data-'+attr) )
{
return true;
}
}
}
return false;
}
/**
* @class Generates HTML from a template file.
*
* This class represents a template engine, it will load an html file and transform it according to specific rules and a set of values.
* The template engine is a DOM based one meaning that all libraries depending on the DOM API, such as jQuery or YUI, and all your DOM based code can be used to manipulate the template as if it were a common web page. *The rules supported by the engine are only concerned with value substitution/binding, be it a
The template engine supports several different kinds of variable substitution/binding:
*{{key}}) syntax. The key part will be used to index the object passed in the constructor to access the value and replace the {{key}} text with it.data-list attribute. A new, cloned, node will be created for each array element, and each node will have access to the respective array element.data-list. A new, cloned, node will be created for each object proerty, and each node will have access to the respective object property.data-remove-if and data-keep-if in order to specify if the node has to be deleted or not.While iterating over arrays or objects, using one of the two methods mentioned above, the contents of each element/property will be available under the key {key, value} form.
These values are passed along in the constructor in the form of a data object, e.g. {key1: 'value1', key2: 'value2'}
index.html
*
* <div class="warning" data-remove-if="hasCookies">
* Cookies are required, after enabled them, please refresh this page.
* </div>
* <h1>Temperatures for {{day}} of {{month}}</h1>
*<ul>
* <li data-list="cities">
* {{cities[].city}}: {{cities[].temperature}} degrees
* </li>
*</ul>
*This week:
*<ul>
* <li data-list="week">
* {{week[].key}}: {{week[].value}}
* </li>
*</ul>
* Code:
* var tmpl = new Markuper( 'index.html',
*{
* day : 24,
* month : 'February',
* hasCookies : true,
* cities : [
* {city: 'Lisbon', temperature: 20},
* {city: 'Oslo' , temperature: -2}
* ],
* week : {
* 'Monday' : 'Sun',
* 'Tuesday' : 'Rain',
* 'Wednesday' : 'Snow'
* }
*});
*tmpl.parse();
*alert( tmpl.html() );
* The alert box will contain:
* <h1>Temperatures for 24 of February</h1> *<ul> * <li> * Lisbon: 20 degrees * </li> * <li> * Oslo: -2 degrees * </li> *</ul> *This week: *<ul> * <li>Monday: Sun</li> * <li>Tuesday: Rain</li> * <li>Wednesday: Snow</li> *</ul>* * Example 2:
this.$j = function()
*{
* return jQuery( arguments[0], _template );
*}
* The previous function allow us to manipulate the template document as if it were a common web page using all power of jQuery.
* var tmpl = new Markuper( 'index.html' ); * /∗ snip ∗/ *tmpl.$j( "input[@type='checkbox']" ).check( 'on' ); *tmpl.$j( "li" ).not( ":has(ul)" ).css( "border", "1px solid black" ); ** *
It's also possible to define our own data- attribute handling code to extend the Markuper library.
* This is done by calling {@link #registerDataAttribute} and passing both attribute name and callback function that will be invoked when handling the nodes found.
* This call will register the attribute and function to be used when calling {@link #parseDataAttributes} and {@link #parseDataAttribute}, both are called by the main {@link #parse} function.
When the nodes are being processed the callback associated with them will be called. After returning, the contents of the node will also be parsed unless the callback returns false.
* Example 3:
* index.html
*
<div data-html-to-text="preview"> * <ul> * <li>Item 1</li> * <li>Item 2</li> * <li>Item 3</li> * <li>Item 4</li> * </ul> *</div>* Code: *
var tmpl = new Markuper( 'index.html',
*{
* preview: true
*});
*tmpl.registerDataAttribute( 'html-to-text', function( node, data, key, value )
*{
* node.removeAttribute( 'html-to-text' );
* if( value )
* {
* node.textContent = node.innerHTML;
* }
*});
* The above code will transform the html of a node into text if data-html-to-text has a true value.
* <div> * <ul> * <li>Item 1</li> * <li>Item 2</li> * <li>Item 3</li> * <li>Item 4</li> * </ul> *</div>* * @param {String} path The path to the template file, should be relative to
/application/.
* @param {Object} _data The object that will be exposed to the template inside the {{key}} elements.
* @param {Object} [options] The object that contains certain specific options that can modify the behaviour of the contructor.
*/
markuper.Template = function( path, _data, options )
{
var _template;
var _lists = [];
var _html = null;
var self = this;
var _dataAttributes = {};
var _dataAttributesName = [];
var _options =
{
};
var _debugSpeed = false;
_data = _data || {};
/**
* Apply options' defaults, load template and import templates if specified.
*
* @param {String} path The path to the template file, should be relative to /application/.
*
* @inner
*/
function init( path )
{
applyDefaults( options );
if( path )
{
open( path );
}
else
{
_html = _options.html || '';
self.reset();
}
setupDataAttributes();
}
/**
* Overwrites _options properties with options.
*
* @param {Object} options The object to merge with _options.
*
* @inner
*/
function applyDefaults( options )
{
for( var key in options )
{
_options[key] = options[key];
}
}
/**
* Opens path for reading and creates a DOM document with its contents
*
* @param {String} path The path to the template file, should be relative to /application/.
* @returns {DOM} The DOM document created.
*
* @inner
*/
function open( path )
{
// TODO: test if exists
var mp = opera.io.filesystem.mountSystemDirectory( 'application' );
var stream = mp.open( path, 'r' );
_html = stream.read( stream.bytesAvailable ).trim();
stream.close();
_template = markuper.HTMLHelper.parseFromString( _html );
// opera.postError('template ' + path + ' loaded');
return _template;
}
/**
* Registers all built-in data- supported attributes
*
* @inner
*/
function setupDataAttributes()
{
self.registerDataAttribute( 'list', fillList );
self.registerDataAttribute( 'dump', fillDump );
self.registerDataAttribute( 'remove-if', function( node, data, key )
{
var value = markuper.evaluator.evalBooleanExpression( key, data );
node.removeAttribute( 'data-remove-if' );
if( value )
{
node.remove();
return false; // don't process the contents of this node
}
});
self.registerDataAttribute( 'keep-if', function( node, data, key )
{
var value = markuper.evaluator.evalBooleanExpression( key, data );
node.removeAttribute( 'data-keep-if' );
if( !value )
{
node.remove();
return false; // don't process the contents of this node
}
});
self.registerDataAttribute( 'import', function( node, data, filename )
{
node.removeAttribute( 'data-import' );
extendElement( node ).importTemplate( filename );
});
}
/**
* Adds the {@link markuper.extendedElement} mixin into the given element along with a template reference as _template.
*
* @param {Element} element The element to extend.
* @returns {Element} The extended element.
*/
function extendElement( element )
{
markuper.addFeaturesToElement( element, markuper.extendedElement );
element._template = self;
return element;
}
/**
* Registers a function for handling nodes with a specifc data- attribute.
*
* Registered attributes will automatically be handled by functions {@link #parseDataAttributes}, {@link #parseDataAttribute} and {@link #parse} while parsing nodes.
*
* The callback function fn will be called with the following arguments:
*
node: the node where the attribute resides.data: the object data currently in use by the template.key: the value of the attribute, a key to the data object.value: the value of pointed by key in data.name part of data-<name>.
* @param {Function} fn The callback function to be called when processing nodes with data-<attribute< attributes.
*
* @see #parseDataAttributes
*/
this.registerDataAttribute = function( attribute, fn )
{
_dataAttributes[attribute] = fn;
_dataAttributesName.push( attribute );
}
/**
* Parses all attributes registered by {@link #registerDataAttribute}.
*
* This function will call {@link #parseDataAttribute} for every attribute registered by {@link #registerDataAttribute}.
* * @param {Object} userData The object with the data to be attached to_data object provided in the constructor.
* @param {Node} root The root element to use instead of the root of the template document.
*
* @see #registerDataAttribute
* @see #parseDataAttribute
*/
this.parseDataAttributes = function( userData, root )
{
/*for( var i=0,attr; attr=_dataAttributesName[i]; i++ )
{
this.parseDataAttribute( attr, userData, root );
}*/
this.parseDataAttribute( _dataAttributesName, userData, root );
}
/**
* Parses a specific attribute, or an array of attributes, that was previous registered by {@link #registerDataAttribute} using the callback function associated with it.
*
* Every attribute will be searched in the template and the corresponding node handled to the callback function with the parameters specificed in {@link #registerDataAttribute}
*The contents of the attributes found is expected to be a key to index the data passed in the constructor in the form of path.to.key.
The actual method signature is parseDataAttribute( attribute, userData, [[node], root])
_data object as _data.data provided in the constructor.
* @param {Node} [node] A specifc node to target instead of searching for attributes through all template.
* @param {Node} [root] The root element to use instead of the root of the template document.
*/
// HINT: maybe this should remove the data-attribute...
this.parseDataAttribute = function( attribute, userData )
{
var oldData = _data.data;
_data.data = userData || _data.data;
if( arguments.length == 3 )
{
Array.prototype.splice.call( arguments, 2, 0, _template );
}
var node = arguments[2],
root = arguments[3];
this.everyDataAttribute( attribute, function( node, attr )
{
var key = node.getAttribute( 'data-'+attr ),
value = markuper.getData( _data, key );
//opera.postError( 'PARSE - data-' + attr + ': ' + node.id );
if( _dataAttributes[attr].call( self, extendElement( node ), _data, key, value ) !== false )
{
node.parse( userData );
}
}, root);
_data.data = oldData;
}
/**
* Internal iterator over nodes with a data-* attribute.
*
* Nodes under other data-* attributed nodes will not be covered.
For each node with a data-<attribute> attribute found in the template the callback function fn will be called with the following arguments:
*
node: the node where the attribute resides.attribute: the name of the data attribute found.data-<attribute> attribute.
* @param {Node} [root] The root element to use instead of the root of the template document.
*/
this.everyDataAttribute = function( attribute, fn, root )
{
root = root || _template.documentElement;
if( !markuper.looksLikeArray(attribute) ) { attribute = [attribute]; };
//var startTime = new Date().getTime();
var nodes = [];
var attrFilter = '[local-name(.) = \'data-' + attribute.join('\' or local-name(.) = \'data-') + '\']';
var nodeFilter = '[@data-' + attribute.join(' or @data-') + ']';
// get all specified attributes from the child nodes of root
var childNodes = self.xpath( './/*' + nodeFilter + '/@*' + attrFilter, root );
// discard all nodes under root that have a parent with one of the
// specified attributes. we only want the outline, i.e., first children
// or great-children with the attributes.
for( var i = 0, node; node = childNodes[i]; i++ )
{
if( markuper.hasParentWithDataAttribute( node.ownerElement, _dataAttributesName, root ) ) continue;
nodes.push( node );
}
//var endTime = new Date().getTime();
for( var i=0,nodes; node=nodes[i]; i++ )
{
fn( node.ownerElement, node.nodeName.match(/^data-(.+)/)[1] );
}
}
/**
* Internal iterator over {{key}} elements of the template.
*
* For each {{key}} element found the callback function fn will be called with the following arguments:
* text: the text found within the {{}} syntax.node: the node containing the {{key}}, can be a TextNode or an Attr.{{key}} will be subtituited with the return value of the callback unless it returns null or undefined.
* The following types of elements can be returned:
* nativeStringNodeNode[]Object: it will be toString()'edThis function provides the user with the proper means to customize the way {{key}}s will be substituted. {@link #fillValues} will substitute them by fetching data from an object, however we can easily create our own version of fillValues that could potentially fetch data from other sources, for instance the internet. As an example imagine that we want to fetch data from the internet for all keys starting with "http://". A possible solution, in pseudocode, could be:
*
markuper.Template.prototype.fillValuesFromInternet = function( userData )
*{
* this.everyValue( function( key, root )
* {
* if ( key.matches( /^http:\/\// ) )
* {
* return getDataFromInternet( key );
* }
* else
* {
* return getData( userData, key );
* }
* });
*}
*
*
* @param {Function} fn The callback function that will be called for each {{key}} found.
* @param {Node} [root] The root element to use instead of the root of the template document.
*/
this.everyValue = function( fn, root )
{
root = root || _template;
var xpathText = ".//text()[contains(.,'{{')]",
xpathAttrs = ".//*/@*[contains(.,'{{')]",
xpathSelfAttrs = "./@*[contains(.,'{{')]",
nodes = this.xpath( xpathText + '|' + xpathAttrs + '|' + xpathSelfAttrs, root );
for( var i = 0, node; node = nodes[i]; i++ )
{
// see CORE-18198
if ( !(node instanceof Text || node instanceof Attr) )
{
continue;
}
var text = node.textContent,
regexp = /\{\{(.+?)\}\}/g,
match;
while( match = regexp.exec( text ) )
{
var value = fn( match[1], node );
if( value === null || value === undefined )
{
continue;
}
// duck typing: Node || array of Nodes
if( value instanceof Node || markuper.looksLikeArray( value ) )
{
if( value instanceof Node )
{
value = [value];
}
var ix = node.textContent.indexOf( match[0] );
node = markuper.splitTextNode( node, ix, match[0].length );
for( var j = 0; j < value.length; j++ )
{
node.parentNode.insertBefore( value[j].cloneNode( true ), node );
}
}
else
{
node.textContent = node.textContent.replace
(
match[0],
value.toString()
);
}
}
}
}
/**
* Substitutes every {{key}} element with the contents of the _data object provided in the constructor along with userData attached as _data.data.
* Each key will be used as a path to find the value in the _data object that will replace the {{key}} text in the template.
*
* Example:It's currently {{data.temperature}} degrees in {{data.city}}, {{data.country}}.
* userData:
* {
* temperature : 20,
* city : 'Lisbon',
* country : 'Portugal'
*}
*
* With this data fillValues will transform the template text into
* It's currently 20 degrees in Lisbon, Portugal.* * @param {Object} userData The object with the data to be attached to
_data object provided in the constructor.
* @param {Node} [root] The root element to use instead of the root of the document.
*
* @see #everyValue for the documentation of which values are supported in the userData object.
*/
this.fillValues = function( userData, root )
{
var oldData = _data.data;
_data.data = userData || _data.data;
this.everyValue( function( key, root )
{
return markuper.getData( _data, key );
}, root);
_data.data = oldData;
}
// TODO: receive a function and put data-select logic in fillOptionList?
/**
* Duplicates a specific node as many times as there are elements in the value specified by the data-list attribute key. This function is useful for creating html lists with the contents of an array where each list item corresponds to an array element.
* This function is not meant to be called directly but rather through handleDataAttribute( 'list', ... ).
If this value is an array, then as many nodes as elements in the array will be created. If it is an object, then as many nodes as object's properties will be created instead.
* After the creation of each node {@link #fillValues} will be called on the node passinguserData as the parameter for the userData argument.
* One aditional field, in the userData object, will be created for each call to node.fillValues that will give access within the template to the corresponding array/object element. This field will be named <data-list>[].
* For example, in a node with data-list="data.cities" there will be a data.cities[]
In the case that the data-list attribute points to an Object this aditional element (<data-list>[]Object with two properties - key and value - that will correspond to each object's property name and value respectively.
Since this function uses {@link #addItemsToList} to create new nodes the list given will be added to an internal array so it can be easily removed by calling {@link #removeListTemplates}.
It is also possible to specify which element will be selected in a list, when the list argument is an <option>, by means of using a data-select attribute with the value of the item that should be selected.
list:
* <li data-list="data.cities">
* {{data.cities[].city}}: {{data.cities[].temperature}} degrees
*</li>
* userData
* {cities: [
* {city: 'Lisbon', temperature: 20},
* {city: 'Oslo' , temperature: -2}
*]}
* The result of calling fillList with these values will be:
* <li id="data.cities-1">
* Lisbon: 20 degrees
*</li>
*<li id="data.cities-2">
* Oslo: -2 degrees
*</li>
*
* Example with an Object:list:
* <li data-list="data.city">
* {{data.cities[].key}}: {{data.cities[].value}}
*</li>
* userData
* {city: {
* City: : 'Lisbon',
* Country : 'Portugal'
* Temperature: : 20
*}}
* The result of calling fillList with these values will be:
* <li id="data.city-1">
* City: 20
*</li>
*<li id="data.city-2">
* Country: Portugal
*</li>
*<li id="data.city-3">
* Temperature: 20
*</li>
*
* @param {Node} list The node with the data-list attribute to be replicated.
* @param {Object} data The data object used in the template.
* @param {String} listDataKey The contents of the data-list attribute.
* @param {Object|native} listData The value of listDataKey in data.
*
* @see #addItemsToList
* @see #setupDataAttributes
* @inner
* @public
*/
function fillList( list, data, listDataKey, listData )
{
if ( !list ) { return null };
var listSelectKey = list.getAttribute( 'data-select' );
var listSelect = markuper.getData( data, listSelectKey );
var listValues = [];
if( listData instanceof Array )
{
listValues = listData;
}
else if( listData instanceof Object )
{
for( var key in listData )
{
listValues.push( {key: key, value: listData[key]} );
}
}
this.addItemsToList( listValues.length, list, function( item, i )
{
markuper.setData( data, listDataKey+'[]', listValues[i] );
if( list.id ) { item.id += '-' + i; };
item.parse( data.data );
if( listSelectKey && item.value == listSelect )
{
item.setAttribute( 'selected', 'selected' );
}
});
markuper.setData( data, listDataKey+'[]', null );
// don't parse the contents of this node
return false;
}
/**
* Duplicates list node by n.
*
* Generic function to duplicate an arbitrary node by an arbitrary ammount. It is meant to be used as an helper function for {@link #fllList}.
* For each duplicate item the callback function fn will be invoked with the following arguments:
* item: the new nodei: index number of the new nodefn will decide if the node will be attached, or not, to the document. The new node will not be attached to the node list if the return value is strictly false.
* Consecutive calls to this function with the same arguments are allowed, making the list grow. However, the i argument of the callback function will not reflect the total list items created by previous calls but rather the node index for the specific call.
The nodes will always be inserted between the last node inserted and the list node given. The first node will be insert before the list node.
The list node given will be stored in an internal array to be used in {@link #removeListTemplates}
n:
* 3*
list:
* <li>
* node:
*</li>
* fn
* function( item, i )
*{
* item.textContent += i + '.';
*}
* The result of calling this function with these values will be:
* <li>
* node: 1.
*</li>
*<li>
* node: 2.
*</li>
*<li>
* node: 3.
*</li>
*
* @see #removeListTemplates
*/
this.addItemsToList = function( n, list, fn )
{
for( var i = 0; i < n; i++ )
{
var item = extendElement( list.cloneNode( true ) );
var addItem = true;
item.removeAttribute( 'data-list' );
if( fn ) { addItem = fn(item, i) };
if( addItem !== false )
{
list.parentNode.insertBefore( item, list );
}
}
_lists.push( list );
}
/**
* Removes all nodes passed as an argument to {@link addItemsToList}.
*
* @see #addItemsToList
*/
this.removeListTemplates = function()
{
for( var i = 0, node; node = _lists[i]; i++ )
{
node.parentNode.removeChild( node );
}
_lists = [];
}
// UGLY: ugly function is ugly
/**
* Dumps an arbitrary object using an html pattern.
*
* All contents of object obj will be dumped using template node as a pattern.
* The template node should be a ul item with a li child and a data-dump attribute. This attribute will mandate which object to dump.
* The li item will be duplicated as many times as properties in the obj object. The corresponding property's name and value will be available, inside the li item, under the keys <data-dump>[].key element will be set to the element's index.
The dump is recursive meaning that the template will be reused for every obj property that is a generic object. A copy of template will be attached as the child of the li item corresponding to that specific property and the same process repeated.
If there are multiple references to the same object, in the object hierarchy, only the first one will be dumped.
*Object properties that are functions will no be dumped.
*The data-dump attribute will be removed from the template node.
template
* <ul data-dump="data.city">
* Object properties:
* <li>name: {{data.city[].key}}; value: {{data.city[].value}}</li>
*</ul>
* obj
* {city: {
* city: : 'Lisbon',
* country : 'Portugal'
* temperature : {celsius: 20},
* hotPlaces : ['Bairro Alto', 'Docas', 'Chiado']
*}}
* Resulting code:
* <ul>
* Object properties:
* <li>name: city; value: Lisbon</li>
* <li>name: country; value: Portugal</li>
* <li>
* name: temperature; value: [object Object]
* <ul>
* Object properties:
* <li>name: celsius; value: 20</li>
* </ul>
* </li>
* <li>
* name: hotPlaces; value: [Array]
* <ul>
* Object properties:
* <li>name: 0; value: Bairro Alto</li>
* <li>name: 1; value: Docas</li>
* <li>name: 2; value: Chiado</li>
* </ul>
* </li>
*</ul>
*
* @param {Node} template The node to use as a pattern.
* @param {Object} data The data object used in the template.
* @param {String} objKey The contents of data-dump attribute.
* @param {Object} obj The object to dump.
* @param {Object} [references={}] List of references to be ignored when dumping obj.
*/
function fillDump( template, data, objKey, obj, references )
{
var list = extendElement( template.cloneNode( true ) );
//var objKey = list.getAttribute( 'data-dump' );
var prop = list.xpath( './li' )[0];
list.removeAttribute( 'data-dump' );
references = references || [];
//obj = obj || getData( data, objKey );
references.push( obj );
template.parentNode.insertBefore( list, template );
for( var key in obj )
{
// disregard functions
if( obj[key] instanceof Object && obj[key].constructor == Function )
{
continue;
}
var item = extendElement( prop.cloneNode( true ) );
var value = obj[key];
if ( value instanceof Object ) { value = value.toString() };
markuper.setData( _data, objKey+'[]', {key: key, value: value} );
item.fillValues();
prop.parentNode.insertBefore( item, prop );
if( obj[key] instanceof Object
&& !references.include( obj[key] )
&& !(obj[key] instanceof Array || obj[key] instanceof String) )
{
var childTemplate = template.cloneNode( true );
item.appendChild( childTemplate );
fillDump( childTemplate, data, objKey, obj[key], references );
}
}
prop.parentNode.removeChild( prop );
template.parentNode.removeChild( template );
markuper.setData( _data, objKey+'[]', null );
return list;
}
/**
* Parses all {{key}}s and nodes with data-* attributes supported by the template engine.
* This function will also remove all nodes used as templates, namely, nodes with data-list and data-dump attributes.
_data object as _data.data provided in the constructor.
*/
this.parse = function( data )
{
//if( ... )
//{
// opera.postError( 'template: ' + path );
// for( var i=0,attr; attr = _dataAttributesName[i]; i++ )
// {
// var startTime = new Date().getTime();
// this.parseDataAttribute( attr, data );
// var endTime = new Date().getTime();
// opera.postError( attr + ': ' + (endTime-startTime)/1000 + 's' );
// }
//}
//else
//{
this.fillValues( data );
//}
this.parseDataAttributes( data );
this.removeListTemplates();
return this;
}
/**
* Constructs an HTML representation of the template's current state.
*
* @returns {String} The HTML representation of the template.
*/
this.html = function()
{
return markuper.HTMLHelper.serializeToString( _template );
}
/**
* Finds elements using a CSS3 selector {@link http://www.w3.org/TR/css3-selectors/}.
*
* @param {String} selector The CSS3 selector to use.
* @param {Node} [root] The root element to use instead of the root of the template document.
* @returns {Array|Node} An array of elements found or a node if only one element was found.
*/
this.select = function( selector, root )
{
if( !selector ) { return extendElement( this.xpath( '//html/body', root )[0].childNodes ); };
root = root || _template;
var nodes = root.querySelectorAll( selector );
if ( nodes.length==0 ) { return null };
for ( var i = 0, node; node = nodes[i]; i++ )
{
extendElement( node );
}
return extendElement( nodes );
}
/**
* Find elements using XPath {@link http://www.w3.org/TR/xpath}.
*
* @param {String} xpath The XPath string.
* @param {Node} [contextNode] The root element to use instead of the root of the template document.
* @returns {Array} An array of elements found.
*/
this.xpath = function( xpath, contextNode )
{
contextNode = contextNode || _template;
// colapse all adjacent text nodes, xpath will only return the first
// node of consecutive nodes even if the text found is in the second
// node.
contextNode.normalize();
return contextNode.selectNodes( xpath );
};
/**
* Resets the template to its initial state.
*
* @param {Object} [data] The object that will be exposed to the template inside the {{key}} elements.
*/
this.reset = function( data )
{
_template = markuper.HTMLHelper.parseFromString( _html );
_data = data || _data;
}
// ensure that all this.functions have already been defined
init( path );
/*
// Version of everyDataAttribute only using XPath
this.everyDataAttributeXPath = function( attribute, fn, root )
{
root = root || _template.documentElement;
var mark = 'data-tmpl-temp-context';
var attributes = '@data-' + _dataAttributesName.join(' or @data-');
var context = '(/*|/*//*)[@' + mark + ']';
/ **
* 1 - we want to process all nodes under a specific node (subtree), we use //*[ancestor::* = //*[@context-node]] for that.
* 2 - and only those with specific attrs //*[@data-attr][ancestor::* = //*[@context-node]]
* 3 - but that don't reside under other data-attrs, so ...
*
* This xpath query will grab all elements with a specific attribute, in this case data-<attribute>, that don't have any node, with a data- attribute, as a parent node (ancestors).
* This query is also engineered in a way that also works under a specifc subtree node of the template, meaning that all nodes above the root node will be disregarded as parent nodes of the node we're looking for.
* The query breakdown:
* './/*[@data-' + attribute + ']'
* This will get us all elements with a data-<attribute> attribute
*
* [ancestor::*[@data-attr1 or @data-attr2 or @data-attr3]]
* This conditional bit will select all ancestors, of the current node, that have at least one attribute out of the list of 'data-' given.
*
* Putting the previous expressions together will get us all elements with a data-<attribute> attribute that have at least one ancestor with a 'data-' attribute. When selecting nodes inside conditional parts ([]) the conditional will be true if there is at least one node in the selector.
* For this particular query we want the opposite, nodes that _dont't_ have ancestors with one of the 'data-' attributes mentioned, hence, a negation is needed:
* [not(ancestor::*[@data-attr1 or @data-attr2 or @data-attr3])]
* And with the two expressions together:
* './/*[@data-' + attribute + '][not(ancestor::*[@data-attr1 or @data-attr2 or @data-attr3])]'
*
* The latter expression will work great if applyed to the entire document, however, if we want to apply this logic only to a subtree of the html document then it will break because the ::ancestor axis will get out of the subtree root element and reach the document root.
* <span id="baz" data-attr1="...">
* <span id="foo">
* <span id="bar" data-attr="...">
* </span>
*</span>
* Using this html hierarchy as an example, if the root node is id="foo", when applying this xpath expression, as it is, id="bar" would not be found because it has an ancestor (id="baz") with a data- attribute.
* It is needed to filter the ancestors to only those under the root node. To achieve this let's imagine there's a context() xpath function that points to the root node.
* To get all nodes under a specific node it will suffice to ask for nodes that have the root node as an ancestor:
* .//*[ancestor::* = context()]
*
* But in this particular case, our nodes are the ancestors of the node with the data-<attribute> attribute, leading to:
* .//*[@data-' + attribute + '][ancestor::*[ancestor::* = context()]]'
*
* Merging this xpath expression with the third one, the one that specifies that the node can't have ancestors with data- attributes, will get the query as:
* .//*[@data-' + attribute + '][not(ancestor::*[@data-attr1 or @data-attr2 or @data-attr3][ancestor::* = context()])]'
*
* There's still on problem remaning, XPath doesn't have support for a function like context() so the idea is to tag the root node in order to easy reference him from the XPath expression. In this case the node is being tagged with a custom made attribute called data-tmpl-temp-context, and the context() is replaced with (./*|./*//*)[@data-tmpl-temp-context].
* /
// different way to think of the query for one attribute
//var xpath = './/*[@data-' + attribute + '][not(ancestor::* = ' + context + '//*[@' + attributes + '])]';
// slightly slower, one attribute only, version
//var xpath = './/*[@data-' + attribute + '][not(ancestor::*[' + attributes + '][ancestor::* = ' + context + '])]';
if( !looksLikeArray(attribute) ) { attribute = [attribute]; };
var attrFilter = 'local-name(.) = \'data-' + attribute.join('\' or local-name(.) = \'data-') + '\'';
var nodeFilter = '[@data-' + attribute.join(' or @data-') + ']';
var xpath = './/*' + nodeFilter + '[not(ancestor::*[' + attributes + '][ancestor::* = ' + context + '])]/@*[' + attrFilter + ']';
root.setAttribute( mark, 'true' );
if( _debugSpeed ) { var startTime = new Date().getTime(); };
var nodes = this.xpath( xpath, root );
if( _debugSpeed ) { var endTime = new Date().getTime(); };
root.removeAttribute( mark );
//if( ... )
//{
// opera.postError( 'XPATH for: ' + attribute + ' - ' + (endTime-startTime)/1000 + 's - ' + nodes.length + ' nodes found.' );
//}
for( var i=0,nodes; node=nodes[i]; i++ )
{
fn( node.ownerElement, node.nodeName.match(/^data-(.+)/)[1] );
}
}
*/
}
window.Markuper = markuper.Template;
/**
* @augments String
* @ignore
*/
String.prototype.trim = function()
{
return this.replace( /^\s+|\s+$/g, '' );
}
/**
* @augments Array
* @ignore
*/
Array.prototype.include = function( obj )
{
return this.indexOf( obj ) !== -1;
}