[sling-site] branch master updated: SLIN-10654: document sightly format string with icu (#100)

[di...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

diru pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-site.git


The following commit(s) were added to refs/heads/master by this push:
     new d43f5c046 SLIN-10654: document sightly format string with icu  (#100)
d43f5c046 is described below

commit d43f5c0468af01b4f478bdb682455f17a2e6f084
Author: Dirk Rudolph <di...@apache.org>
AuthorDate: Wed Oct 26 23:06:04 2022 +0200

    SLIN-10654: document sightly format string with icu  (#100)
---
 .../content/documentation/bundles/scripting/scripting-htl.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/src/main/jbake/content/documentation/bundles/scripting/scripting-htl.md b/src/main/jbake/content/documentation/bundles/scripting/scripting-htl.md
index 9d760fd3a..f1f74604b 100644
--- a/src/main/jbake/content/documentation/bundles/scripting/scripting-htl.md
+++ b/src/main/jbake/content/documentation/bundles/scripting/scripting-htl.md
@@ -124,6 +124,18 @@ Those pattern values are case-insensitive.
 
 The implementation uses [`DateTimeFormatter.ofLocalizedDate(FormatStyle)`](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ofLocalizedDate-java.time.format.FormatStyle-) for formatting those dates.
 
+### Format String (supported since HTL Engine 1.4.22-1.4.0)
+
+In addition to the variable-element placeholder replacement as given by the examples in the [HTL Spec 1.4](https://github.com/adobe/htl-spec/blob/1.4/SPECIFICATION.md#examples), [SLING-10654](https://issues.apache.org/jira/browse/SLING-10654) adds optional support for complex argument types using [ICU Message Formatting](https://unicode-org.github.io/icu/userguide/format_parse/messages/).
+
+When the [icu4j bundle](https://github.com/unicode-org/icu/releases) is available at runtime, pattterns that contain complex argument types will automatically be formatted using the icu4j [`MessageFormat`](https://unicode-org.github.io/icu-docs/apidoc/dev/icu4j/com/ibm/icu/text/MessageFormat.html). This adds for example support for select and plural formats:
+
+    ${ '{0, plural, one{# result} other{# results}}' @format=properties.result }
+    ${ '{0, plural, one{# výsledek} few{# výsledky} other{# výsledků}}' @format=properties.result }
+
+Other than for the regular variable-element placeholder replacement, parameters passed to the format option are not converted to any other type. If they do not match the pattern an `IllegalArgumentException` may be throw. 
+
+If the icu4j bundle is not available at runtime, only simple variable-element placeholders will be replaced and expessions that use complex argument types will be removed. 
 
 ## Use-API Extensions