Layouts, expui and expai operators #

Three Exponential extension families add their own operators. Each exists only where its extension is active: explayouts, explayouts_ui and expui on the sites and the administration, expai only on the administration siteaccesses of a development installation (its operators are not registered on site).

Contents #

1. explayouts block markers: expl_parse, expl_strip, expl_has, expl_first
2. explayouts_ui: explayouts_ui_has_template
3. expui: exp_config
4. expai: expai_money, expai_tokens, expai_number, expai_retention, expai_json

explayouts block markers #

The {explblock} template function of explayouts wraps parts of rendered output in comment markers <!--expl:s:<name>--> and <!--expl:e:<name>--> (names: a lowercase letter, then lowercase letters, digits or _). The four operators read such output through ExplBlockParser (extension/explayouts/classes/explblockparser.php), a parser without kernel dependencies, so they also work on cached HTML. All four take up to two positional parameters (both mixed, optional); the first is used only when there is no input.

expl_parse #

Returns a hash: blocks (name => list of the contents of every block of that name, in order) and stripped (the input without any markers). Crossed nesting drops the inner frame; an end marker without a start is ignored; a block still open at the end runs to the end of the text.

expl_strip #

Returns only the text without markers (stripped of expl_parse).

expl_has #

Input: the HTML, the result of expl_parse, or its blocks. Parameter: the block name. true when that block exists and is not empty.

expl_first #

Input: a list (such as $parsed.blocks.title): its first element; a string is returned as it is; anything else gives an empty string.

explayouts_ui #

explayouts_ui_has_template #

true when a template with that path exists in one of the design bases of the siteaccess (eZTemplateDesignResource::fileMatch() on templates/). A path containing .. is always false. The layouts UI uses it to include optional parts only when a design provides them.

{def $html = '<div><!--expl:s:title--><h1>Recipes</h1><!--expl:e:title--><!--expl:s:lead-->Fresh food<!--expl:e:lead--></div>'
     $parsed = $html|expl_parse}
1 expl_parse blocks: {foreach $parsed.blocks as $name => $parts}{$name} ({$parts|count}){delimiter}, {/delimiter}{/foreach}

2 expl_parse stripped: {$parsed.stripped}
3 expl_strip: {$html|expl_strip}
4 expl_first: {$parsed.blocks.title|expl_first}
5 expl_has title: {expl_has( $html, 'title' )|choose( 'no', 'yes' )}, footer: {$parsed|expl_has( 'footer' )|choose( 'no', 'yes' )}
6 explayouts_ui_has_template: {explayouts_ui_has_template( 'pagelayout.tpl' )|choose( 'no', 'yes' )} / {explayouts_ui_has_template( 'no/such/template.tpl' )|choose( 'no', 'yes' )} / {explayouts_ui_has_template( '../settings/site.ini' )|choose( 'no', 'yes' )}

Output:

1 expl_parse blocks: title (1), lead (1)
2 expl_parse stripped: <div><h1>Recipes</h1>Fresh food</div>
3 expl_strip: <div><h1>Recipes</h1>Fresh food</div>
4 expl_first: <h1>Recipes</h1>
5 expl_has title: yes, footer: no
6 explayouts_ui_has_template: yes / no / no

expui #

exp_config #

Returns the configuration block that the expui JavaScript core reads: <script type="application/json" data-exp-config> with config (version, root and www paths, siteaccess, ezjscore call address, preferences address, form token element id, separator, locale code, HTTP locale and first weekday), strings and prefs. options.strings adds texts to translate (in the context extension/expui) to those of expui.ini [ExpUI] Strings[]; options.prefs names user preferences to include (names matching [A-Za-z0-9_.-]{1,64}). The JSON is encoded with <, >, & and quotes escaped, so no value can end the script element. A type="application/json" block is data, so it needs no CSP nonce. Print it unwashed; the example washes it only to show the tag:

{def $script = exp_config( hash( 'strings', array( 'Close' ) ) )}
starts: {$script|extract_left( 48 )|wash}
ends:   {$script|extract_right( 9 )|wash}

Output:

starts: <script type="application/json" data-exp-config>
ends:   </script>

expai #

The expai operators format the figures of the AI usage pages. Rendered on the admin siteaccess:

expai_money #

Parameter approx (boolean, default false). Formats an amount in dollars (expAiCost::money()): small amounts as < $0.01, with ≈ in front when approx is true.

expai_tokens #

No parameters. Token counts shortened: 950, 22k, 1.2M (expAiCost::tokens()).

expai_number #

Parameter decimals (integer, default 0). A number with the locale's separators (expAiCost::number()).

expai_retention #

No parameters. A data retention value from the provider settings (none, zdr, 30d, unknown): unknown is translated, every other value is shown as written.

expai_json #

No parameters. JSON of the input for a <script type="application/json"> block: <, >, &, ' and " are escaped as \u sequences, and invalid UTF-8 becomes U+FFFD instead of making the whole result empty. A value that cannot be encoded gives null and a warning in the debug log.

1 expai_money: {0.0625|expai_money} / {0.004|expai_money} / {0.0625|expai_money( true() )}
2 expai_tokens: {950|expai_tokens} / {21600|expai_tokens} / {1200000|expai_tokens}
3 expai_number: {1234567.891|expai_number( 2 )}
4 expai_retention: {'unknown'|expai_retention} / {'30d'|expai_retention}
5 expai_json: {hash( 'text', '</script><b>"x"</b>', 'n', 3 )|expai_json}

Output:

1 expai_money: $0.06 / < $0.01 / ≈$0.06
2 expai_tokens: 950 / 22k / 1.2M
3 expai_number: 1,234,567.89
4 expai_retention: unknown / 30d
5 expai_json: {"text":"\u003C\/script\u003E\u003Cb\u003E\u0022x\u0022\u003C\/b\u003E","n":3}

Related pages #

• ezjscore operators in depth (json_encode for the same purpose without the extra escaping)
• The layouts editor
• Content security policy for applications
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.