variable modifier updates

Author: intoeetive

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(

docs/development/modifiers.md

@@ -0,0 +1,68 @@
+<!--
+    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-2021, 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)
+
+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.
+
+    <?php
+
+    /**
+    * namespace is required and must be add-on's namespace + 'Modifiers'
+    * 
+    */
+    <?php
+
+    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 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 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]