diff --git a/docs/development/addon-setup-php-file.md b/docs/development/addon-setup-php-file.md index 364ef1297..a58000c3b 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..03241da93 --- /dev/null +++ b/docs/development/modifiers.md @@ -0,0 +1,66 @@ + + +# 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. + + array( + 'hacker' + ), + +And now, let's call it in a template. + + {exp:channel:entries entry_id="1"} +
+ {title} - Hello +
+
+ {title:hacker} - H3110 +
+
+ {title:seeo_hacker} - H3110 +
+ {/exp:channel:entries} diff --git a/docs/templates/variable-modifiers.md b/docs/templates/variable-modifiers.md index 7e053b71d..1467e2d57 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 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]