ZPT-JS reference - Format expressions

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:

1. First it tries to get it from the context. It uses the context.getFormatter() method to try to find it.
2. If the formatter is not found, it tries to get it from the scope using the formatter as a function name.
3. 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.
4. 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:

import { zpt } from './zpt-esm.js';

// 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:

import { zpt } from './zpt-esm.js';

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.