From 721befc194054e587950a61ef6d06015f957858b Mon Sep 17 00:00:00 2001 From: Simon Wisselink Date: Mon, 26 Feb 2024 12:06:29 +0100 Subject: [PATCH] Documented all available modifiers --- .../language-modifier-json-encode.md | 27 ++++++++++++++ .../language-modifier-number-format.md | 32 +++++++++++++++++ .../language-modifier-round.md | 35 +++++++++++++++++++ .../language-modifier-str-repeat.md | 14 ++++++++ .../language-modifier-strlen.md | 9 +++++ .../language-modifier-substr.md | 25 +++++++++++++ mkdocs.yml | 2 +- 7 files changed, 143 insertions(+), 1 deletion(-) create mode 100644 docs/designers/language-modifiers/language-modifier-json-encode.md create mode 100644 docs/designers/language-modifiers/language-modifier-number-format.md create mode 100644 docs/designers/language-modifiers/language-modifier-round.md create mode 100644 docs/designers/language-modifiers/language-modifier-str-repeat.md create mode 100644 docs/designers/language-modifiers/language-modifier-strlen.md create mode 100644 docs/designers/language-modifiers/language-modifier-substr.md diff --git a/docs/designers/language-modifiers/language-modifier-json-encode.md b/docs/designers/language-modifiers/language-modifier-json-encode.md new file mode 100644 index 000000000..4e70f0c26 --- /dev/null +++ b/docs/designers/language-modifiers/language-modifier-json-encode.md @@ -0,0 +1,27 @@ +# json_encode + +Transforms a value into a valid JSON string. + +## Basic usage +```smarty +{$user|json_encode} +``` +Depending on the value of `$user` this would return a string in JSON-format, e.g. `{"username":"my_username","email":"my_username@smarty.net"}`. + + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------------------------------------------------------------------------------------| +| 1 | int | No | bitmask of flags, directly passed to [PHP's json_encode](https://www.php.net/json_encode) | + + +## Examples + +By passing `16` as the second parameter, you can force json_encode to always format the JSON-string as an object. +Without it, an array `$myArray = ["a","b"]` would be formatted as a javascript array: + +```smarty +{$myArray|json_encode} # renders: ["a","b"] +{$myArray|json_encode:16} # renders: {"0":"a","1":"b"} +``` \ No newline at end of file diff --git a/docs/designers/language-modifiers/language-modifier-number-format.md b/docs/designers/language-modifiers/language-modifier-number-format.md new file mode 100644 index 000000000..44c3acf44 --- /dev/null +++ b/docs/designers/language-modifiers/language-modifier-number-format.md @@ -0,0 +1,32 @@ +# number_format + +Allows you to format a number using decimals and a thousands-separator. By default, the number of decimals is 0 +and the number is rounded. + +## Basic usage +```smarty +{$num = 2000.151} +{$num|number_format} # renders: 2,000 +``` + + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|--------|----------|---------------------------------------| +| 1 | int | No | number of decimals (defaults to 0) | +| 2 | string | No | decimal separator (defaults to ".") | +| 3 | string | No | thousands-separator (defaults to ",") | + + +## Examples + +```smarty +{$num = 2000.151} +{$num|number_format:2} # renders: 2,000.15 +``` + +```smarty +{$num = 2000.151} +{$num|number_format:2:".":""} # renders: 2000.15 +``` \ No newline at end of file diff --git a/docs/designers/language-modifiers/language-modifier-round.md b/docs/designers/language-modifiers/language-modifier-round.md new file mode 100644 index 000000000..c05b899a9 --- /dev/null +++ b/docs/designers/language-modifiers/language-modifier-round.md @@ -0,0 +1,35 @@ +# round + +Rounds a number to the specified precision. + +## Basic usage +```smarty +{3.14|round} # renders: 3 +``` + +```smarty +{3.141592|round:2} # renders: 3.14 +``` + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|---------------------------| +| 1 | int | No | precision (defaults to 0) | +| 2 | int | No | mode (defaults to 1) | + +If 'precision' is negative, the number is rounded to the nearest power of 10. See examples below. + +The parameter 'mode' defines how the rounding is done. By default, 2.5 is rounded to 3, whereas 2.45 is rounded to 2. +You usually don't need to change this. For more details on rounding modes, +see [PHP's documentation on round](https://www.php.net/manual/en/function.round). + +## Examples + +By passing `16` as the second parameter, you can force json_encode to always format the JSON-string as an object. +Without it, an array `$myArray = ["a","b"]` would be formatted as a javascript array: + +```smarty +{$myArray|json_encode} # renders: ["a","b"] +{$myArray|json_encode:16} # renders: {"0":"a","1":"b"} +``` \ No newline at end of file diff --git a/docs/designers/language-modifiers/language-modifier-str-repeat.md b/docs/designers/language-modifiers/language-modifier-str-repeat.md new file mode 100644 index 000000000..1ae1824d6 --- /dev/null +++ b/docs/designers/language-modifiers/language-modifier-str-repeat.md @@ -0,0 +1,14 @@ +# str_repeat + +Repeats the given value n times. + +## Basic usage +```smarty +{"hi"|str_repeat:2} # renders: hihi +``` + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-----------------------| +| 1 | int | yes | number of repetitions | diff --git a/docs/designers/language-modifiers/language-modifier-strlen.md b/docs/designers/language-modifiers/language-modifier-strlen.md new file mode 100644 index 000000000..4c1f37ab7 --- /dev/null +++ b/docs/designers/language-modifiers/language-modifier-strlen.md @@ -0,0 +1,9 @@ +# strlen + +Returns the length (number of characters) in the given string, including spaces. + +## Basic usage +```smarty +{"Smarty"|strlen} # renders: 6 +{156|strlen} # renders: 3 +``` diff --git a/docs/designers/language-modifiers/language-modifier-substr.md b/docs/designers/language-modifiers/language-modifier-substr.md new file mode 100644 index 000000000..a79d8a4d1 --- /dev/null +++ b/docs/designers/language-modifiers/language-modifier-substr.md @@ -0,0 +1,25 @@ +# substr + +Returns a part (substring) of the given string starting at a given offset. + +## Basic usage +```smarty +{"Smarty"|substr:2} # renders: arty +{"Smarty"|substr:2:3} # renders: art +``` + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-----------------------------------------------------| +| 1 | int | yes | offset (zero based, can be negative) | +| 2 | int | no | length of substring returned (unlimited of omitted) | + + +## Examples + +When used with a negative offset, the substring starts n characters from the end of the string counting backwards. +```smarty +{"Smarty"|substr:-2} # renders: ty +{"Smarty"|substr:-2:1} # renders: t +``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 62ff92101..223cab28b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -72,7 +72,7 @@ nav: - 'round': 'designers/language-modifiers/language-modifier-round.md' - 'spacify': 'designers/language-modifiers/language-modifier-spacify.md' - 'split': 'designers/language-modifiers/language-modifier-split.md' - - 'str_repeat': 'designers/language-modifiers/language-modifier-string-repeat.md' + - 'str_repeat': 'designers/language-modifiers/language-modifier-str-repeat.md' - 'string_format': 'designers/language-modifiers/language-modifier-string-format.md' - 'strip': 'designers/language-modifiers/language-modifier-strip.md' - 'strip_tags': 'designers/language-modifiers/language-modifier-strip-tags.md'