From 0283be6eab9ff615b014e31510e7a63967abf751 Mon Sep 17 00:00:00 2001 From: Yuri Salimovskiy Date: Thu, 22 Dec 2022 11:20:42 +0200 Subject: [PATCH 1/5] variable modifier updates --- docs/development/addon-setup-php-file.md | 9 ++++ docs/development/modifiers.md | 68 ++++++++++++++++++++++++ docs/templates/variable-modifiers.md | 8 +++ 3 files changed, 85 insertions(+) create mode 100644 docs/development/modifiers.md diff --git a/docs/development/addon-setup-php-file.md b/docs/development/addon-setup-php-file.md index 364ef1297..4dd928399 100755 --- a/docs/development/addon-setup-php-file.md +++ b/docs/development/addon-setup-php-file.md @@ -114,6 +114,15 @@ As of 3.1.0 fieldtypes can specify their compatibility. When editing a Channel F | relationship | [Relationships](https://docs.expressionengine.com/latest/fieldtypes/relationships.html) | | text | [Email Address](fieldtypes/email-address.md), [Rich Text Editor](fieldtypes/rte.md), [Text Input](fieldtypes/text.md), [Textarea](fieldtypes/textarea.md),[URL](fieldtypes/url.md) | +### `modifiers` + + 'modifiers' => array( + 'modifier_name', + 'another_modifier_name' + ) + +This property lists the [variable modifiers](development/modifiers.md) that the add-on provides + ### `services` 'services' => array( diff --git a/docs/development/modifiers.md b/docs/development/modifiers.md new file mode 100644 index 000000000..f767cc4c3 --- /dev/null +++ b/docs/development/modifiers.md @@ -0,0 +1,68 @@ + + +# Developing Variable Modifiers + +The add-ons can provide their own [variable modifiers](templates/variable-modifiers.md) + +Each variable modifier needs be created as a separate file in `Modifiers` directory within add-on's own folder and registered in `addon.setup.php`. + +The file name (which will also be PHP class name) should be the modifier's name with first letter capitalized. + +All modifier files are required to implement `ExpressionEngine\Service\Template\Variables\ModifierInterface`. + +Each widget should have `namespace` definition, which should consist of the add-on's namespace as defined in `addon.setup.php` followed by `\Modifiers`. + +Lastly, the modifier's name should be registered in `addon.setup.php` + +TIP: **Tip:** Modifiers provided by add-on can be called by their name as well as by their name prefixed with add-on's name and underscore. For example below we can use `{title:hacker}` and `{title:seo_hacker}` to achieve same result + +### Example + +Let's create `:hacker` modifier which would make text look geeky by converting some letters to numbers that look similarly. The modifier would be part of "Seeo" add-on. + + array( + 'hacker' + ), + +And now, let's call it in template. + + {exp:channel:entries entry_id="1"} +
+ {title} - Hello +
+
+ {title:hacker} - H3110 +
+
+ {title:seeo_hacker} - H3110 +
+ {/exp:channel:entries} \ No newline at end of file diff --git a/docs/templates/variable-modifiers.md b/docs/templates/variable-modifiers.md index 7e053b71d..1f6ece232 100755 --- a/docs/templates/variable-modifiers.md +++ b/docs/templates/variable-modifiers.md @@ -22,6 +22,14 @@ Most template variables can be modified for common formatting and output needs w NOTE: **Note:** Some add-ons and components may have modifiers not listed here. For instance the [File Fieldtype](fieldtypes/file.md) has its own file information-related modifiers. The modifiers listed here are just those universally available. +## Modifiers syntax + +The modifiers are being applied by adding modifier name after variable name, separated by semicolon, e.g. `var_name:trim`. + +It is possible to apply several modifiers at the same time by chaing those, e.g. `var_name:trim:url_encode`. The modifiers would be applied left to right (so in this case, the variable's content will first be trimmed and then URL-encoded). + +When applying several modifiers, there could be conflict in parameter names. To avoid that, the parameters could be prefixed with modifier name followed by semicolon. E.g. `{excerpt:limit characters='20'}` could be written as `{excerpt:limit limit:characters='20'}`. This allows writing constructions such as `{excerpt:limit:trim limit:characters='20' trim::characters='\n\r'}`. Prefixed parameter has higher precedence over non-prefixed one. + ## Modifiers [TOC=3] From 486b2375864d3e1a780f8c48edea2f645a37442c Mon Sep 17 00:00:00 2001 From: Yuri Salimovskiy Date: Mon, 26 Dec 2022 11:51:11 +0200 Subject: [PATCH 2/5] typo --- docs/templates/variable-modifiers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/templates/variable-modifiers.md b/docs/templates/variable-modifiers.md index 1f6ece232..968a1df05 100755 --- a/docs/templates/variable-modifiers.md +++ b/docs/templates/variable-modifiers.md @@ -28,7 +28,7 @@ The modifiers are being applied by adding modifier name after variable name, sep It is possible to apply several modifiers at the same time by chaing those, e.g. `var_name:trim:url_encode`. The modifiers would be applied left to right (so in this case, the variable's content will first be trimmed and then URL-encoded). -When applying several modifiers, there could be conflict in parameter names. To avoid that, the parameters could be prefixed with modifier name followed by semicolon. E.g. `{excerpt:limit characters='20'}` could be written as `{excerpt:limit limit:characters='20'}`. This allows writing constructions such as `{excerpt:limit:trim limit:characters='20' trim::characters='\n\r'}`. Prefixed parameter has higher precedence over non-prefixed one. +When applying several modifiers, there could be conflict in parameter names. To avoid that, the parameters could be prefixed with modifier name followed by semicolon. E.g. `{excerpt:limit characters='20'}` could be written as `{excerpt:limit limit:characters='20'}`. This allows writing constructions such as `{excerpt:limit:trim limit:characters='20' trim:characters='\n\r'}`. Prefixed parameter has higher precedence over non-prefixed one. ## Modifiers From ba1e21e125debcbc17c369297a78b2da8295a775 Mon Sep 17 00:00:00 2001 From: Matt Johnson Date: Thu, 1 Jun 2023 15:46:52 -0500 Subject: [PATCH 3/5] Update variable-modifiers.md --- docs/templates/variable-modifiers.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/templates/variable-modifiers.md b/docs/templates/variable-modifiers.md index 968a1df05..1467e2d57 100755 --- a/docs/templates/variable-modifiers.md +++ b/docs/templates/variable-modifiers.md @@ -24,11 +24,11 @@ NOTE: **Note:** Some add-ons and components may have modifiers not listed here. ## Modifiers syntax -The modifiers are being applied by adding modifier name after variable name, separated by semicolon, e.g. `var_name:trim`. +The modifiers are being applied by adding the modifier name after the variable name, separated by a semicolon, e.g. `var_name:trim`. -It is possible to apply several modifiers at the same time by chaing those, e.g. `var_name:trim:url_encode`. The modifiers would be applied left to right (so in this case, the variable's content will first be trimmed and then URL-encoded). +It is possible to apply several modifiers at the same time by chaining those, e.g. `var_name:trim:url_encode`. The modifiers would be applied left to right, so in this case the variable's content will first be trimmed and then URL-encoded. -When applying several modifiers, there could be conflict in parameter names. To avoid that, the parameters could be prefixed with modifier name followed by semicolon. E.g. `{excerpt:limit characters='20'}` could be written as `{excerpt:limit limit:characters='20'}`. This allows writing constructions such as `{excerpt:limit:trim limit:characters='20' trim:characters='\n\r'}`. Prefixed parameter has higher precedence over non-prefixed one. +To avoid conflicts in parameter names when applying several modifiers, the parameters can be prefixed with the modifier name followed by semicolon. E.g. `{excerpt:limit characters='20'}` could be written as `{excerpt:limit limit:characters='20'}`. This allows writing constructions such as `{excerpt:limit:trim limit:characters='20' trim:characters='\n\r'}`. A prefixed parameter has a higher precedence than a non-prefixed parameter. ## Modifiers From 2bc194f04c31065b6d1df2dfae2de79c61727594 Mon Sep 17 00:00:00 2001 From: Matt Johnson Date: Thu, 1 Jun 2023 15:47:28 -0500 Subject: [PATCH 4/5] Update addon-setup-php-file.md --- docs/development/addon-setup-php-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/addon-setup-php-file.md b/docs/development/addon-setup-php-file.md index 4dd928399..a58000c3b 100755 --- a/docs/development/addon-setup-php-file.md +++ b/docs/development/addon-setup-php-file.md @@ -121,7 +121,7 @@ As of 3.1.0 fieldtypes can specify their compatibility. When editing a Channel F 'another_modifier_name' ) -This property lists the [variable modifiers](development/modifiers.md) that the add-on provides +This property lists the [variable modifiers](development/modifiers.md) that the add-on provides. ### `services` From 1caff0481b4a5962f1e0c195405e96c3e55d034c Mon Sep 17 00:00:00 2001 From: Matt Johnson Date: Thu, 1 Jun 2023 15:52:58 -0500 Subject: [PATCH 5/5] Update modifiers.md --- docs/development/modifiers.md | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/docs/development/modifiers.md b/docs/development/modifiers.md index f767cc4c3..03241da93 100644 --- a/docs/development/modifiers.md +++ b/docs/development/modifiers.md @@ -3,29 +3,29 @@ ExpressionEngine User Guide (https://github.com/ExpressionEngine/ExpressionEngine-User-Guide) @link https://expressionengine.com/ - @copyright Copyright (c) 2003-2021, Packet Tide, LLC (https://packettide.com) + @copyright Copyright (c) 2003-2023, Packet Tide, LLC (https://packettide.com) @license https://expressionengine.com/license Licensed under Apache License, Version 2.0 --> # Developing Variable Modifiers -The add-ons can provide their own [variable modifiers](templates/variable-modifiers.md) +Add-ons can provide their own [variable modifiers](templates/variable-modifiers.md) for use in templates. -Each variable modifier needs be created as a separate file in `Modifiers` directory within add-on's own folder and registered in `addon.setup.php`. +Each variable modifier needs be created as a separate file in the `Modifiers` directory within the add-on's root folder, and registered in `addon.setup.php`. -The file name (which will also be PHP class name) should be the modifier's name with first letter capitalized. +The file name, which is also the PHP class name, should be the modifier's name with the first letter capitalized. All modifier files are required to implement `ExpressionEngine\Service\Template\Variables\ModifierInterface`. -Each widget should have `namespace` definition, which should consist of the add-on's namespace as defined in `addon.setup.php` followed by `\Modifiers`. +Each modifier should have a `namespace` definition, which consists of the add-on's namespace as defined in `addon.setup.php` followed by `\Modifiers`. -Lastly, the modifier's name should be registered in `addon.setup.php` +Lastly, the modifier's name should be registered in `addon.setup.php`. -TIP: **Tip:** Modifiers provided by add-on can be called by their name as well as by their name prefixed with add-on's name and underscore. For example below we can use `{title:hacker}` and `{title:seo_hacker}` to achieve same result +TIP: **Tip:** Modifiers provided by add-ons can be called by their name as well as by their name prefixed with add-on's name and underscore. For example, below we can use `{title:hacker}` and `{title:seeo_hacker}` to achieve the same result. ### Example -Let's create `:hacker` modifier which would make text look geeky by converting some letters to numbers that look similarly. The modifier would be part of "Seeo" add-on. +Let's create the `:hacker` modifier, which would make text look geeky by converting some of the letters to similar looking numbers. This example modifier is part of the "Seeo" add-on. array( - 'hacker' - ), + 'hacker' + ), -And now, let's call it in template. +And now, let's call it in a template. {exp:channel:entries entry_id="1"}
@@ -65,4 +63,4 @@ And now, let's call it in template.
{title:seeo_hacker} - H3110
- {/exp:channel:entries} \ No newline at end of file + {/exp:channel:entries}