1. Introduction
The Uize.Widget.Population class implements population of contents into a DOM node, by cloning an HTML template using data from a records array.
DEVELOPERS: Chris van Rensburg, original code donated by Zazzle Inc.
The Uize.Widget.Population module defines the Uize.Widget.Population class, a subclass of the Uize base class.
2. Instance Methods
2.1. getHtml
Returns a string, being the HTML markup generated using the template HTML contained in the templateStr set-get property and the record set contained by the items set-get property.
SYNTAX
htmlSTR = myPopulation.getHtml ();
2.2. getOutput
Returns a string, being the output generated using the value of the templateStr set-get property and the record set contained by the items set-get property.
SYNTAX
outputSTR = myPopulation.getOutput ();
2.3. updateUi
Updates the contents of the DOM node specified by the container set-get property, using the getHtml instance method to generate the new HTML markup.
SYNTAX
myPopulation.updateUi ();
NOTES
if the templateStr set-get property is undefined, null, or an empty string at the time that this method first performs its action, then this property value will be set by taking the value of the container node's innerHTML property | |
this method is called automatically whenever there is a change in the values of the templateStr and items set-get properties | |
if the container set-get property is equivalent to false, or if the node specified by this property does not exist in the DOM, then this method will have no action | |
if the enabled set-get property is equivalent to false, then this method will have no action | |
this method is optimized so that if it is called repeatedly and in that time there is no change in the values of the templateStr or items set-get properties, then its action will not be performed repeatedly |
3. Static Methods
3.1. Uize.Widget.Population.makeTemplateItem
Generates a template item, using the specified item and token naming scheme, that can then be used when setting the templateItem set-get property of an instance.
SYNTAX
templateItemOBJ = Uize.Widget.Population.makeTemplateItem (itemOBJ,tokenNamingSTRorFN);
When a string value is specified for the tokenNamingSTRorFN parameter, then the token for any given key will be generated by replacing the text "KEY" in the value of the tokenNamingSTRorFN parameter with the actual name of the key. Consider the following example...
EXAMPLE 1
Uize.Widget.Population.makeTemplateItem (
{
firstName:'Jack',
lastName:'Frost',
cellPhone:'(111) 123-4567',
address:'632 North Haven Drive, Arlington, NC'
},
'##KEY##'
);
The above example would generate the following template item object...
{
firstName:'##firstName##',
lastName:'##lastName##',
cellPhone:'##cellPhone##',
address:'##address##'
}
This template item could then be used by an instance of Uize.Widget.Population when iterating over multiple person items and substituting the tokens of the form ##KEY## in the template string with the values for those keys in each item. If all of the items have the same keys, then one could simply use the first item in the items array to generate the template item with its key-to-token mappings.
Now, if a function reference is specified for the tokenNamingSTRorFN parameter, then the token for any given key will be generated by calling the function and passing in the actual name of the key as a parameter. The value that is returned by the function will then be used as the token. Consider the following example...
EXAMPLE 2
Uize.Widget.Population.makeTemplateItem (
{
firstName:'Jack',
lastName:'Frost',
cellPhone:'(111) 123-4567',
address:'632 North Haven Drive, Arlington, NC'
},
function (key) {return '[ ' + key.toUpperCase () + ' ]'}
);
The above example would generate the following template item object...
{
firstName:'[FIRSTNAME]',
lastName:'[LASTNAME]',
cellPhone:'[CELLPHONE]',
address:'[ADDRESS]'
}
VARIATIONS
templateItemOBJ = Uize.Widget.Population.makeTemplateItem (itemOBJ);
When no tokenNamingSTRorFN parameter is specified, then the token names generated in the template item will be identical to the key names.
4. Set-get Properties
4.1. templateStr
A string, representing the template that should be used when generating output in the getOutput and getHtml instance methods.
If this property is undefined, null, or an empty string at the time that the updateUi instance method first performs its action, then its value will be set by taking the value of the container node's innerHTML property.
NOTES
| the initial value is undefined |