Merge pull request #546 from ExpressionEngine/feature/7.x/modifier-updates

variable modifier updates

Author: intoeetive

docs/development/addon-setup-php-file.md

@@ -119,6 +119,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(

docs/development/modifiers.md

@@ -0,0 +1,66 @@
+<!--
+    This source file is part of the open source project
+    ExpressionEngine User Guide (https://github.com/ExpressionEngine/ExpressionEngine-User-Guide)
+
+    @link      https://expressionengine.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
+
+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 the `Modifiers` directory within the add-on's root folder, and registered in `addon.setup.php`.
+
+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 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`.
+
+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 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.
+
+    <?php
+
+    /**
+    * namespace is required and must be add-on's namespace + 'Modifiers'
+    * 
+    */
+    namespace EEHarbor\Seeo\Modifiers;
+
+    use ExpressionEngine\Service\Template\Variables\ModifierInterface;
+
+    class Hacker implements ModifierInterface
+    {
+        public function modify($data, $params = array(), $tagdata = false)
+        {
+            return str_replace(['e', 'o', 'l'], ['3', '0', '1'], (string) $data);
+        }
+    }
+
+Next, we'll add the following to `addon.setup.php`
+
+    'modifiers' => array(
+        'hacker'
+    ),
+
+And now, let's call it in a template.
+
+    {exp:channel:entries entry_id="1"}
+        <div class="title">
+            <span>{title}</span> - Hello
+        </div>
+        <div class="hacker">
+            <span>{title:hacker}</span> - H3110
+        </div>
+        <div class="seeo_hacker">
+            <span>{title:seeo_hacker}</span> - H3110
+        </div>
+    {/exp:channel:entries}

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 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 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.
+
+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
 
 [TOC=3]