zpt
Version:
Zenon Page Templates - JS (ZPT-JS)
158 lines (137 loc) • 6.7 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>ZPT-JS reference - Format expressions</title>
<script type="text/javascript" src="../lib/zpt.min.js" defer></script>
<script type="text/javascript" src="../js/zpt.js" defer></script>
<script type="text/javascript" src="../lib/syntaxHighlighter/lib.js"></script>
<link rel="stylesheet" type="text/css" href="../docs.css">
<link rel="stylesheet" type="text/css" href="../lib/syntaxHighlighter/theme.css">
</head>
<body>
<div data-use-macro="'page@templates.html'">
<div data-fill-slot="'page-header'">
<h1>ZPT-JS reference - Format expressions</h1>
<ul>
<li><a href="#syntax">Syntax</a>.</li>
<li><a href="#description">Description</a>.</li>
<li><a href="#differences">Differences with ZPT</a>.</li>
<li><a href="#examples">Examples</a>.</li>
</ul>
</div>
<article data-fill-slot="'article'">
<h2 data-attributes="id 'syntax'">Syntax</h2>
<pre class="syntax">
format_expressions ::= 'format:' formatter expression format_arguments
formatter ::= Name
format_arguments ::= [expression]*
</pre>
<h2 data-attributes="id 'description'">Description</h2>
<p>
<em>Format</em> expressions makes it easy to format values. They use <em>formatters</em> to do the work: a <em>formatter</em> is a normal function that must be previously registered. ZPT-JS includes some built-in <em>formatters</em>:
</p>
<ul>
<li><em>lowerCase</em>. Converts a string to lowercase letters, according to the host's current locale. It invokes the <em>toLocaleLowerCase</em> method of string objects.</li>
<li><em>upperCase</em>. Converts a string to uppercase letters, according to the host's current locale. It invokes the <em>toLocaleUpperCase</em> method of string objects.</li>
<li><em>localeDate</em>. Converts the date (not the time) of a Date object into a readable string, using locale conventions. It invokes the <em>toLocaleDateString</em> method of date objects.</li>
<li><em>localeTime</em>. Returns the time portion of a Date object as a string, using locale conventions. It invokes the <em>toLocaleTimeString</em> method of date objects.</li>
<li><em>localeString</em>. Converts a Date object to a string, using locale settings (or the host's current locale if not set). It invokes the <em>toLocaleString</em> method of date objects.</li>
<li><em>fix</em>. Converts a number into a string, keeping a specified number of decimals. It invokes the <em>toFixed</em> method of number objects.</li>
</ul>
<p>
How are <em>formatters</em> found by ZPT-JS? When ZPT-JS finds a format expression it tries to locate the formatter following this order:
</p>
<ol>
<li>
First it tries to get it from the context. It uses the <code>context.getFormatter()</code> method to try to find it.
</li>
<li>
If the <em>formatter</em> is not found, it tries to get it from the scope using the <em>formatter</em> as a function name.
</li>
<li>
If the <em>formatter</em> is not found, it evaluates the <em>formatter</em> as an expression and then it tries to get it from the scope using the resulting value as a function name.
</li>
<li>
If the <em>formatter</em> is not found, an exception is thrown.
</li>
</ol>
<p>
You can add your custom <em>formatters</em> simply adding a function with the same name to the dictionary.
</p>
<h2 data-attributes="id 'differences'">Differences with ZPT</h2>
<p>
<em>Formatters</em> does not exist in ZPT.
</p>
<h2 data-attributes="id 'examples'">Examples</h2>
<p>
Simple format:
</p>
<pre class="brush: html">
<div data-content="format: lowerCase 'Test'">must be test</div>
<div data-content="format: upperCase 'Test'">must be TEST</div>
</pre>
<p>
Format with arguments:
</p>
<pre class="brush: html">
<div data-content="format: fix 1.377 2">must be 1.37</div>
<div data-content="format: fix (/: 1 3) 2">must be 1.33</div>
</pre>
<p>
Custom formatters using dictionary
</p>
<p>
The javascript code:
</p>
<pre class="brush: js">
"use strict";
var zpt = require( 'zpt' );
// To register customFormatter add it to the dictionary
var dictionary = {
myCustomFormatter: function( value ){
return "$" + value;
}
};
// Parse template
zpt.run({
root: document.body,
dictionary: dictionary
});
</pre>
<p>
...and the invokation of <em>myCustomFormatter</em>:
</p>
<pre class="brush: html">
<div data-content="format: myCustomFormatter 1.55">must be $1.55</div>
</pre>
<p>
Custom formatters using context
</p>
<p>
The javascript code:
</p>
<pre class="brush: js">
"use strict";
var zpt = require( 'zpt' );
var dictionary = {};
// To register customFormatter add it to the context
zpt.context.registerFormatter(
'customFormatter',
function( value ){
return "$" + value;
}
);
// Parse template
zpt.run({
root: document.body,
dictionary: dictionary
});
</pre>
<p>
...and the invokation is exactly equal.
</p>
</article>
</div>
</body>
</html>