The Uize.Template module supports the concept of an encoding.

An encoding is defined in an encoding profile, which defines how to encode to and decode from the encoding. The Uize.Template module defines many built-in standard encodings, such as the json, urlParams, tagAttributeValue, and other encodings. Encodings can be conveniently used inside templating assignment statements, as shown in the following example...

EXAMPLE

<%= {hello:'world',foo:'bar'} -> urlParams %>

The above example is encoding the URL query parameters object to a URL parameters string by using the urlParams encoding, producing the string result 'hello=world&foo=bar'.

Encodings can also be used in the Uize.Template.encode and Uize.Template.decode static methods. Consider the following example...

EXAMPLE

var urlParamsStr = Uize.Template.encode ({hello:'world',foo:'bar'},'urlParams');

After the above code has been executed, the value of the urlParamsStr variable will be the string 'hello=world&foo=bar'.

1.1.1.1. Modules Required to Support Encodings

The Uize.Template module supports the concept of an encodings chain, which is a set of multiple encodings that are to be chained together and performed in sequence.

EXAMPLE

<a href="search?<% .searchParams -> urlParams -> tagAttributeValue %>">
  <% .searchParams.category %>
</a>

In the above example, the searchParams property of the template's input object is a reference to an object that contains properties for various search parameters. The Uize.Template.encode method is being used to first encode this object to a URL query paramaters string using the urlParams encoding, after which it is then encoded to a tag attribute value using the tagAttributeValue encoding.

The Uize.Template.encode and Uize.Template.decode static methods also allow an Encodings Chain to be specified for their encodingsChainSTR parameter, as shown in the example below...

EXAMPLE

var searchUrlParamsTagAttributeValue = Uize.Template.encode (
  searchParamsObj,
  'urlParams -> tagAttributeValue'
);

An encoding is defined using an encoding profile, which is an object containing definitions for the encoder and decoder for the encoding.

SYNTAX

{
  to:{
    required  : encoderRequiredModulesSTRorARRAY,
    expansion : encoderExpansionFUNC
  },
  from:{
    required  : decoderRequiredModulesSTRorARRAY,
    expansion : decoderExpansionFUNC
  }
}

The to property of the Encoding Profile object defines how to encode to the encoding, while the from property defines how to decode from the encoding. Both the to and from properties' values should be objects containing required and expansion properties, where the required property's value can be a string or array specifying the name(s) of one or more modules required by the encoder/decoder, and where the expansion property's value should be a function that should accept value string and encoding options string parameters and output an expanded expression that can be evaluated to perform the encoding or decoding. This is best illustrated with an example...

EXAMPLE

Uize.Template.encodings.json = {
  to:{
    required:'Uize.Json',
    expansion:function (_valueStr,_optionsStr) {
      return 'Uize.Json.to (' + _valueStr + (_optionsStr && ',') + _optionsStr + ')';
    }
  },
  from:{
    required:'Uize.Json',
    expansion:function (_valueStr) {
      return 'Uize.Json.from (' + _valueStr + ')';
    }
  }
}

In the above example, the json encoding is being defined. Notice that both the encoder (to) and decoder (from) both require the Uize.Json module. The expansion function for the encoder is constructing a snippet of code that calls the Uize.Json.to static method, plugging in the values of its _valueStr and _optionsStr parameters. If the value of the _optionsStr parameter is an empty string, then the second parameter is omitted from the Uize.Json.to method call that is being constructed. Similarly, the expansion function for the decoder is constructing a snippet of code that calls the Uize.Json.from static method, but this function ignores its second parameter since the Uize.Json.from method doesn't support any encoding options.

A standard encoding is an encoding whose encoder and decoder functions are static methods of the same module, and where those static methods accept as their first parameter a value to encode or decode, and as their optional second parameter encoding options.

A standard encoding can be conveniently defined using the Uize.Template.defineStandardEncoding static method, by only specifying a few parameters and without having to flesh out the entire encoding profile. The majority of encodings that are built into the Uize.Template module are standard encodings. As an example, the json encoding can easily be defined with the statement...

Uize.Template.defineStandardEncoding ('json','Uize.Json','to','from');

The features listed in this section have been introduced in this module.

STATIC METHODS

Uize.Template.compile | Uize.Template.decode | Uize.Template.defineStandardEncoding | Uize.Template.encode

STATIC PROPERTIES

Uize.Template.encodings | Uize.Template.moduleName | Uize.Template.pathToResources

No features have been overridden in this module.

This module has no inherited features.

Uize.Template.Module

The Uize.Template module is unit tested by the Uize.Test.Uize.Template test module.

A single module can be declareed as a dependency for the template by specifying the module's name for the moduleNameSTR parameter.

SYNTAX

<%@ required (moduleNameSTR) %>

EXAMPLE

<%@ required ('Uize.Xml') %>

In the above example, the @required directive declares that the template needs the Uize.Xml module for its processing.

Multiple modules can be declareed as dependencies for the template by specifying the names of the modules in the comma-separated string for the moduleNamesSTR parameter.

SYNTAX

<%@ required (moduleNamesSTR) %>

EXAMPLE

<%@ required ('Uize.Xml,Uize.Color,Uize.Data') %>

In the above example, the @required directive declares that the Uize.Xml, Uize.Color, and Uize.Data modules are needed for the module's processing.

Multiple modules can be declareed as dependencies for the template by specifying an array of module names for the moduleNamesARRAY parameter.

SYNTAX

<%@ required (moduleNamesARRAY) %>

EXAMPLE

<%@ required (['Uize.Xml','Uize.Color','Uize.Data']) %>

In the above example, the @required directive declares that the Uize.Xml, Uize.Color, and Uize.Data modules are needed for the module's processing.

Multiple modules can be declareed as dependencies for the template by specifying the module names as an arbitrarily long list of string arguments.

SYNTAX

<%@ required (module1NameSTR,module2NameSTR,module3NameSTR,...) %>

EXAMPLE

<%@ required ('Uize.Xml','Uize.Color','Uize.Data') %>

In the above example, the @required directive declares that the Uize.Xml, Uize.Color, and Uize.Data modules are needed for the module's processing.

You can call the @required directive multiple times inside the same template, which will have a cumulative effect in building up the required modules list.

So, for example, the following template code...

<%@ required ('Uize.Xml') %>
<%@ required ('Uize.Date') %>

...is equivalent to...

<%@ required (['Uize.Xml','Uize.Date']) %>

When building up the canonical list of modules required by a template being compiled, the @required directive makes sure to ignore any duplicate instances of required modules.

This applies both to duplicates that may occur within a single @required call, as well as duplicates that may arise across multiple @required calls. While duplicates are not a very likely occurrence, this protection does exist to prevent duplicates in the required property of the Uize.Template.compile method's full form result object.

EXAMPLE

<%@ required ('Uize.Xml,Uize.Json,Uize.Color,Uize.Xml') %>
<%@ required ('Uize.Color') %>
<%@ required (['Uize.Date','Uize.Str.Trim','Uize.Date']) %>

In the above example, the very first @required call has two entries for the Uize.Xml module. Then, the second call repeats the Uize.Color module that occurred in the first call. Finally, the third call, while using the array form for specifying the required modules, has a duplicate entry for the Uize.Date module. In this example, the final list of required modules would be ['Uize.Xml','Uize.Json','Uize.Color','Uize.Date','Uize.Str.Trim'].

The templateOptionsOBJ parameter lets you specify options for how the template should be compiled, and has properties as follows...

PROPERTIES

{
  openerToken:openerTokenSTR,            // optional, defaults to <%
  closerToken:closerTokenSTR,            // optional, defaults to %>
  gobbleWhitespace:gobbleWhitespaceBOOL, // optional, defaults to true
  result:resultTypeSTR                   // 'function' (default) | 'full'
};

3.1.1.1. openerToken

3.1.1.2. closerToken

3.1.1.3. gobbleWhitespace

3.1.1.4. result

{
  input:inputProfileOBJ,        // a profile of the input handled by the template
  required:moduleNamesARRAY,    // a list of modules required by the template
  code:templateCodeSTR,         // implementation code for the template function
  templateFunction:templateFUNC // a reference to the compiled template function
}

The Uize.Template.decode method allows encoding options to be specified for encodings in the encodingsChainSTR parameter, in the same way one would do so in templating assignment statements.

EXAMPLE

var attributesObj = Uize.Template.decode (
  'hello="world" foo="bar"',
  'tagAttributes{nameCase:\'upper\'}'
);

After the above code has executed, the value of the attributesObj variable will be the attributes object {HELLO:'world',FOO:'bar'}. This is because the value 'upper' is being specified for the nameCase encoding option of the tagAttributes encoding. Encoding options for an encoding are specified in curly braces after the encoding's name.

The Uize.Template.decode method allows an encodings chain to be specified in the encodingsChainSTR parameter, using the same syntax one would use for templating assignment statements.

EXAMPLE

var searchParamsObj = Uize.Template.decode (
  searchUrlParamsTagAttributeValue,
  'urlParams -> tagAttributeValue'
);

In the above example, the value of the searchUrlParamsTagAttributeValue variable is a string that contains URL query paramaters that have been encoded to a string using the urlParams encoding, and have been further encoded to a tag attribute value using the tagAttributeValue encoding.

The value 'urlParams -> tagAttributeValue' for the encodingsChainSTR parameter specifies the encodings that were applied to the value that is being decoded - the encodings that will have to be reversed in order to decode from the 'urlParams -> tagAttributeValue' compound encoding. The Uize.Template.decode method here is decoding the string by reversing the direction of the 'urlParams -> tagAttributeValue' encodings chain, producing as its result a URL query paramaters object.

It's worth pointing out that you could accomplish the same effect by using the Uize.Template.encode method and reversing the order of encodings in the chain, as well as reversing the direction of the individual encodings by toggling the "!" prefix in front of the encodings. So, the following example using the Uize.Template.encode method would have the same outcome as the example using the Uize.Template.decode method that is shown above...

var searchParamsObj = Uize.Template.encode (
  searchUrlParamsTagAttributeValue,
  '!tagAttributeValue -> !urlParams'
);

The benefit of using the Uize.Template.decode method is that it does the reverse mapping for you, which is especially useful if you have a specific encodings chain stored in some string variable and you want to easily encode to and decode from that compound encoding.

3.3.1.1. encodingNameSTR

3.3.1.2. moduleNameSTR

3.3.1.3. encoderMethodNameSTR

3.3.1.4. decoderMethodNameSTR

The Uize.Template.encode method allows encoding options to be specified for encodings in the encodingsChainSTR parameter, in the same way one would do so in templating assignment statements.

EXAMPLE

var attributeValuesStr = Uize.Template.encode (
  {HELLO:'world',FOO:'bar'},
  'tagAttributes{nameCase:\'lower\'}'
);

After the above code has executed, the value of the attributeValuesStr variable will be the string 'hello="world" foo="bar"'. This is because the value 'lower' is being specified for the nameCase encoding option of the tagAttributes encoding. Encoding options for an encoding are specified in curly braces after the encoding's name.

The Uize.Template.encode method allows an encodings chain to be specified in the encodingsChainSTR parameter, using the same syntax one would use for templating assignment statements.

EXAMPLE

var searchUrlParamsTagAttributeValue = Uize.Template.encode (
  searchParamsObj,
  'urlParams -> tagAttributeValue'
);

In the above example, the searchParams variable is a reference to an object that contains properties for various search parameters. The Uize.Template.encode method is being used to first encode this object to a URL query paramaters string using the urlParams encoding, after which it is then encoded to a tag attribute value using the tagAttributeValue encoding.

An encoding profile for the iso8601 encoding.

An encoding profile for the json encoding.

An encoding profile for the miniJson encoding.

An encoding profile for the indent encoding.

An encoding profile for the tagAttributes encoding.

An encoding profile for the tagAttributeValue encoding.

An encoding profile for the url encoding.

An encoding profile for the urlParams encoding.

An encoding profile for the urlPiece encoding.

When encoding, the value can be of any type that can be resolved to a Date object by the Uize.Date.resolve static method of the Uize.Date module.

SYNTAX

<%= dateSTRorOBJorNUM -> iso8601 %>

Using this encoding in the forward direction is equivalent to using the Uize.Date.toIso8601 static method of the Uize.Date module.

EXAMPLE

<%= 'Tue Sep 11 2001' -> is8601 %>

OUTPUT

2001-09-11

When decoding, the value should be a string, in ISO8601 format.

SYNTAX

<%= dateIso8601STR -> !iso8601 %>

Using this encoding in the reverse direction (i.e. decoding by using the "!" prefix) is equivalent to using the Uize.Date.fromIso8601 static method of the Uize.Date module.

EXAMPLE

<%= '2001-09-11' -> !iso8601 -> urlPiece %>

OUTPUT

Tue%20Sep%2011%202001%2000%3A00%3A00%20GMT-0700%20(Pacific%20Daylight%20Time)

When encoding, the value to encode can be a string, boolean, number, object, array, null, undefined, or a regular expression.

SYNTAX

<%= valueANYTYPE -> json %>

Using this encoding in the forward direction is equivalent to using the Uize.Json.to static method of the Uize.Json module.

EXAMPLE

<%= {hello:'world',foo:'bar'} -> json %>

OUTPUT

{
  hello:'world',
  foo:'bar'
}

5.2.1.1. json Encoding Options

<%= valueANYTYPE -> json{encodingOptionsOBJ} %>

<%= {hello:'world',foo:'bar'} -> json{keyDelimiter:' : ',padKeys:true} %>

{
  hello : 'world',
  foo   : 'bar'
}

When decoding, the value to decode should be a string in JSON format, and the decoded value can be a string, boolean, number, object, array, null, undefined, or a regular expression.

SYNTAX

<%= jsonSTR -> !json %>

Using this encoding in the reverse direction (i.e. decoding by using the "!" prefix) is equivalent to using the Uize.Json.from static method of the Uize.Json module.

EXAMPLE

<%= '{hello:"world",foo:"bar"}' -> !json -> urlParams %>

OUTPUT

hello=world&foo=bar

When encoding, the value to encode can be a string, boolean, number, object, array, null, undefined, or a regular expression.

SYNTAX

<%= valueANYTYPE -> miniJson %>

Using this encoding in the forward direction is equivalent to using the Uize.Json.to static method of the Uize.Json module, and specifying the value 'mini' for this method's optional serializationOptionsOBJ parameter.

EXAMPLE

<%= {hello:'world',foo:'bar'} -> miniJson %>

OUTPUT

{hello:'world',foo:'bar'}

When decoding, the value to decode should be a string in JSON format, and the decoded value can be a string, boolean, number, object, array, null, undefined, or a regular expression.

SYNTAX

<%= jsonSTR -> !miniJson %>

Using this encoding in the reverse direction (i.e. decoding by using the "!" prefix) is equivalent to using the Uize.Json.from static method of the Uize.Json module.

EXAMPLE

<%= '{hello:"world",foo:"bar"}' -> !miniJson -> urlParams %>

OUTPUT

hello=world&foo=bar

When encoding, the value to encode will be coerced to a string.

SYNTAX

<%= valueANYTYPE -> indent{encodingOptionsOBJ} %>

Using this encoding in the forward direction is equivalent to using the Uize.Str.Indented.to static method of the Uize.Str.Indented module.

EXAMPLE

top
<%= 'foo\nbar\nbaz\nqux' -> indent{amount:5} %>
bottom

OUTPUT

top
          foo
          bar
          baz
          qux
bottom

When decoding, the value to decode should be a string in JSON format, and the decoded value can be a string, boolean, number, object, array, null, undefined, or a regular expression.

SYNTAX

<%= jsonSTR -> !indent{encodingOptionsOBJ} %>

Using this encoding in the reverse direction (i.e. decoding by using the "!" prefix) is equivalent to using the Uize.Str.Indented.from static method of the Uize.Str.Indented module.

EXAMPLE

top
<%= '\t\tfoo\n\t\t\tbar\n\t\t\t\tbaz\n\t\t\t\t\tqux' -> !indent{amount:2} %>
bottom

OUTPUT

top
foo
  bar
    baz
      qux
bottom

When encoding, the value should be an object, containing properties for the tag attributes.

SYNTAX

<%= tagAttributesOBJ -> tagAttributes %>

Using this encoding in the forward direction is equivalent to using the Uize.Xml.toAttributes static method of the Uize.Xml module.

EXAMPLE

<%= {width:320,height:480,alt:'CONTINUE >>'} -> tagAttributes %>

OUTPUT

width="320" height="480" alt="CONTINUE >>"

When decoding, the value should be a tag attributes string, and the decoded value will be a tag attributes object.

SYNTAX

<%= tagAttributesSTR -> !tagAttributes %>

Using this encoding in the reverse direction (i.e. decoding by using the "!" prefix) is equivalent to using the Uize.Xml.fromAttributes static method of the Uize.Xml module.

EXAMPLE

<%= 'width="320" height="480" alt="CONTINUE &gt;&gt;"' -> !tagAttributes -> miniJson %>

OUTPUT

{width:320,height:480,alt:'CONTINUE >>'}

When encoding, the value can be of any type and will be coerced to a string if necessary.

SYNTAX

<%= valueANYTYPE -> tagAttributeValue %>

Using this encoding in the forward direction is equivalent to using the Uize.Xml.toAttributeValue static method of the Uize.Xml module.

EXAMPLE 1

<%= 'CONTINUE >>' -> tagAttributeValue %>

OUTPUT

CONTINUE >>

EXAMPLE 2

<%= Uize.Class ({value:'CONTINUE >>'}) -> tagAttributeValue %>

OUTPUT

CONTINUE >>

When decoding, the value should be a tag attribute value string (excluding the enclosing quotes), and the decoded value will be a string.

SYNTAX

<%= tagAttributeValueSTR -> !tagAttributeValue %>

Using this encoding in the reverse direction (i.e. decoding by using the "!" prefix) is equivalent to using the Uize.Xml.fromAttributeValue static method of the Uize.Xml module.

EXAMPLE

<%= 'CONTINUE &gt;&gt;' -> !tagAttributeValue %>

OUTPUT

CONTINUE >>

When encoding, the value can be a URL path string, or an array containing a URL path string and any number of optional query parameters objects.

Using this encoding in the forward direction is equivalent to using the Uize.Url.resolve static method of the Uize.Url module.

5.7.1.1. Value To Encode is a URL Path String

<%= urlPathSTR -> url{urlParamsOBJ} %>

<%= 'http://uize.com' -> url{hello:'world',foo:'bar'} %>

http://uize.com?hello=world&foo=bar

5.7.1.2. Value To Encode is a URL Path Plus Params Objects Array

<%= urlPathPlusParamsObjectsARRAY -> url %>
<%= urlPathPlusParamsObjectsARRAY -> url{urlParamsOBJ} %>

<%= ['http://uize.com',{hello:'world',foo:'bar'}] -> url %>

http://uize.com?hello=world&foo=bar

<%= ['http://uize.com',{hello:'world'}] -> url{foo:'bar'} %>

http://uize.com?hello=world&foo=bar

When decoding, the value should be a URL string, and the decoded value will be an object containing properties that represent different logical components of the URL (e.g. protocol, host, folder path, filename, file extension, query string, etc.).

SYNTAX

<%= urlSTR -> !url %>

Using this encoding in the reverse direction (i.e. decoding by using the "!" prefix) is equivalent to using the Uize.Url.from static method of the Uize.Url module.

EXAMPLE

<%= 'http://uize.com:80/reference/Uize.html?param=value#anchor' -> !url -> json %>

OUTPUT

{
  href:'http://uize.com:80/reference/Uize.html?param=value#anchor',
  fullDomain:'http://uize.com:80',
  protocol:'http:',
  host:'uize.com:80',
  hostname:'uize.com',
  port:'80',
  pathname:'/reference/Uize.html',
  folderPath:'/reference/',
  file:'Uize.html',
  fileName:'Uize',
  extension:'.html',
  fileType:'html',
  search:'?param=value',
  query:'param=value',
  hash:'#anchor',
  anchor:'anchor'
}                {

When encoding, the value should be an object, containing properties for the URL query parameters.

SYNTAX

<%= urlParamsOBJ -> urlParams %>

Using this encoding in the forward direction is equivalent to using the Uize.Url.toParams static method of the Uize.Url module.

EXAMPLE

<%= {hello:'world',foo:'bar'} -> urlParams %>

OUTPUT

hello=world&foo=bar

When decoding, the value should be a URL query parameters string, or a full URL string that may contain query parameters, and the decoded value will be a URL query parameters object.

SYNTAX

<%= urlParamsSTR -> !urlParams %>

Using this encoding in the reverse direction (i.e. decoding by using the "!" prefix) is equivalent to using the Uize.Url.fromParams static method of the Uize.Url module.

EXAMPLE

<%= 'http://uize.com/?hello=world&foo=bar' -> !urlParams -> miniJson %>

OUTPUT

{hello:'world',foo:'bar'}

When encoding, the value can be of any type and will be coerced to a string if necessary.

SYNTAX

<%= valueANYTYPE -> urlPiece %>

Using this encoding in the forward direction is equivalent to using the Uize.Url.toPiece static method of the Uize.Url module.

EXAMPLE 1

<%= 'hello, world' -> urlPiece %>

OUTPUT

hello%2C%20world

EXAMPLE 2

<%= Uize.Class ({value:'hello, world'}) -> urlPiece %>

OUTPUT

hello%2C%20world

When decoding, the value should be a URL fragment string, and the decoded value will be a string.

SYNTAX

<%= urlPieceSTR -> !urlPiece %>

Using this encoding in the reverse direction (i.e. decoding by using the "!" prefix) is equivalent to using the Uize.Url.fromPiece static method of the Uize.Url module.

EXAMPLE

<%= 'hello%2C%20world' -> !urlPiece %>

OUTPUT

hello, world