Syntax
format_expressions ::= 'format:' formatter expression format_arguments formatter ::= Name format_arguments ::= [expression]*
Description
Format expressions makes it easy to format values. They use formatters to do the work: a formatter is a normal function that must be previously registered. ZPT-JS includes some built-in formatters:
- lowerCase. Converts a string to lowercase letters, according to the host's current locale. It invokes the toLocaleLowerCase method of string objects.
- upperCase. Converts a string to uppercase letters, according to the host's current locale. It invokes the toLocaleUpperCase method of string objects.
- localeDate. Converts the date (not the time) of a Date object into a readable string, using locale conventions. It invokes the toLocaleDateString method of date objects.
- localeTime. Returns the time portion of a Date object as a string, using locale conventions. It invokes the toLocaleTimeString method of date objects.
- localeString. Converts a Date object to a string, using locale settings (or the host's current locale if not set). It invokes the toLocaleString method of date objects.
- fix. Converts a number into a string, keeping a specified number of decimals. It invokes the toFixed method of number objects.
How are formatters found by ZPT-JS? When ZPT-JS finds a format expression it tries to locate the formatter following this order:
-
First it tries to get it from the context. It uses the
context.getFormatter()
method to try to find it. - If the formatter is not found, it tries to get it from the scope using the formatter as a function name.
- If the formatter is not found, it evaluates the formatter as an expression and then it tries to get it from the scope using the resulting value as a function name.
- If the formatter is not found, an exception is thrown.
You can add your custom formatters simply adding a function with the same name to the dictionary.
Differences with ZPT
Formatters does not exist in ZPT.
Examples
Simple format:
<div data-content="format: lowerCase 'Test'">must be test</div> <div data-content="format: upperCase 'Test'">must be TEST</div>
Format with arguments:
<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>
Custom formatters using dictionary
The javascript code:
"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 });
...and the invokation of myCustomFormatter:
<div data-content="format: myCustomFormatter 1.55">must be $1.55</div>
Custom formatters using context
The javascript code:
"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 });
...and the invokation is exactly equal.