{
    "content": [
        {
            "type": "text",
            "text": "# Template::Plugin::Filter (perldoc)\n\n## NAME\n\nTemplate::Plugin::Filter - Base class for plugin filters\n\n## SYNOPSIS\n\npackage MyOrg::Template::Plugin::MyFilter;\nuse Template::Plugin::Filter;\nuse base qw( Template::Plugin::Filter );\nsub filter {\nmy ($self, $text) = @;\n# ...mungify $text...\nreturn $text;\n}\n# now load it...\n[% USE MyFilter %]\n# ...and use the returned object as a filter\n[% FILTER $MyFilter %]\n...\n[% END %]\n\n## DESCRIPTION\n\nThis module implements a base class for plugin filters. It hides the underlying complexity\ninvolved in creating and using filters that get defined and made available by loading a plugin.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **EXAMPLE**\n- **AUTHOR**\n- **COPYRIGHT**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Template::Plugin::Filter",
        "section": "",
        "mode": "perldoc",
        "summary": "Template::Plugin::Filter - Base class for plugin filters",
        "synopsis": "package MyOrg::Template::Plugin::MyFilter;\nuse Template::Plugin::Filter;\nuse base qw( Template::Plugin::Filter );\nsub filter {\nmy ($self, $text) = @;\n# ...mungify $text...\nreturn $text;\n}\n# now load it...\n[% USE MyFilter %]\n# ...and use the returned object as a filter\n[% FILTER $MyFilter %]\n...\n[% END %]",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [
            "Here's a complete example of a plugin filter module.",
            "package My::Template::Plugin::Change;",
            "use Template::Plugin::Filter;",
            "use base qw( Template::Plugin::Filter );",
            "sub init {",
            "my $self = shift;",
            "$self->{ DYNAMIC } = 1;",
            "# first arg can specify filter name",
            "$self->installfilter($self->{ ARGS }->[0] || 'change');",
            "return $self;",
            "sub filter {",
            "my ($self, $text, $args, $config) = @;",
            "$config = $self->mergeconfig($config);",
            "my $regex = join('|', keys %$config);",
            "$text =~ s/($regex)/$config->{ $1 }/ge;",
            "return $text;",
            "1;"
        ],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 21,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 188,
                "subsections": []
            },
            {
                "name": "EXAMPLE",
                "lines": 30,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "COPYRIGHT",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "Template::Plugin::Filter - Base class for plugin filters\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "package MyOrg::Template::Plugin::MyFilter;\n\nuse Template::Plugin::Filter;\nuse base qw( Template::Plugin::Filter );\n\nsub filter {\nmy ($self, $text) = @;\n\n# ...mungify $text...\n\nreturn $text;\n}\n\n# now load it...\n[% USE MyFilter %]\n\n# ...and use the returned object as a filter\n[% FILTER $MyFilter %]\n...\n[% END %]\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "This module implements a base class for plugin filters. It hides the underlying complexity\ninvolved in creating and using filters that get defined and made available by loading a plugin.\n\nTo use the module, simply create your own plugin module that is inherited from the\n\"Template::Plugin::Filter\" class.\n\npackage MyOrg::Template::Plugin::MyFilter;\n\nuse Template::Plugin::Filter;\nuse base qw( Template::Plugin::Filter );\n\nThen simply define your \"filter()\" method. When called, you get passed a reference to your\nplugin object ($self) and the text to be filtered.\n\nsub filter {\nmy ($self, $text) = @;\n\n# ...mungify $text...\n\nreturn $text;\n}\n\nTo use your custom plugin, you have to make sure that the Template Toolkit knows about your\nplugin namespace.\n\nmy $tt2 = Template->new({\nPLUGINBASE => 'MyOrg::Template::Plugin',\n});\n\nOr for individual plugins you can do it like this:\n\nmy $tt2 = Template->new({\nPLUGINS => {\nMyFilter => 'MyOrg::Template::Plugin::MyFilter',\n},\n});\n\nThen you \"USE\" your plugin in the normal way.\n\n[% USE MyFilter %]\n\nThe object returned is stored in the variable of the same name, '\"MyFilter\"'. When you come to\nuse it as a \"FILTER\", you should add a dollar prefix. This indicates that you want to use the\nfilter stored in the variable '\"MyFilter\"' rather than the filter named '\"MyFilter\"', which is\nan entirely different thing (see later for information on defining filters by name).\n\n[% FILTER $MyFilter %]\n...text to be filtered...\n[% END %]\n\nYou can, of course, assign it to a different variable.\n\n[% USE blat = MyFilter %]\n\n[% FILTER $blat %]\n...text to be filtered...\n[% END %]\n\nAny configuration parameters passed to the plugin constructor from the \"USE\" directive are\nstored internally in the object for inspection by the \"filter()\" method (or indeed any other\nmethod). Positional arguments are stored as a reference to a list in the \"ARGS\" item while\nnamed configuration parameters are stored as a reference to a hash array in the \"CONFIG\" item.\n\nFor example, loading a plugin as shown here:\n\n[% USE blat = MyFilter 'foo' 'bar' baz = 'blam' %]\n\nwould allow the \"filter()\" method to do something like this:\n\nsub filter {\nmy ($self, $text) = @;\n\nmy $args = $self->{ ARGS   };  # [ 'foo', 'bar' ]\nmy $conf = $self->{ CONFIG };  # { baz => 'blam' }\n\n# ...munge $text...\n\nreturn $text;\n}\n\nBy default, plugins derived from this module will create static filters. A static filter is\ncreated once when the plugin gets loaded via the \"USE\" directive and re-used for all subsequent\n\"FILTER\" operations. That means that any argument specified with the \"FILTER\" directive are\nignored.\n\nDynamic filters, on the other hand, are re-created each time they are used by a \"FILTER\"\ndirective. This allows them to act on any parameters passed from the \"FILTER\" directive and\nmodify their behaviour accordingly.\n\nThere are two ways to create a dynamic filter. The first is to define a $DYNAMIC class variable\nset to a true value.\n\npackage MyOrg::Template::Plugin::MyFilter;\nuse base 'Template::Plugin::Filter';\nour $DYNAMIC = 1;\n\nThe other way is to set the internal \"DYNAMIC\" value within the \"init()\" method which gets\ncalled by the \"new()\" constructor.\n\nsub init {\nmy $self = shift;\n$self->{ DYNAMIC } = 1;\nreturn $self;\n}\n\nWhen this is set to a true value, the plugin will automatically create a dynamic filter. The\noutcome is that the \"filter()\" method will now also get passed a reference to an array of\npositional arguments and a reference to a hash array of named parameters.\n\nSo, using a plugin filter like this:\n\n[% FILTER $blat 'foo' 'bar' baz = 'blam' %]\n\nwould allow the \"filter()\" method to work like this:\n\nsub filter {\nmy ($self, $text, $args, $conf) = @;\n\n# $args = [ 'foo', 'bar' ]\n# $conf = { baz => 'blam' }\n}\n\nIn this case can pass parameters to both the USE and FILTER directives, so your filter() method\nshould probably take that into account.\n\n[% USE MyFilter 'foo' wiz => 'waz' %]\n\n[% FILTER $MyFilter 'bar' biz => 'baz' %]\n...\n[% END %]\n\nYou can use the \"mergeargs()\" and \"mergeconfig()\" methods to do a quick and easy job of\nmerging the local (e.g. \"FILTER\") parameters with the internal (e.g. \"USE\") values and returning\nnew sets of conglomerated data.\n\nsub filter {\nmy ($self, $text, $args, $conf) = @;\n\n$args = $self->mergeargs($args);\n$conf = $self->mergeconfig($conf);\n\n# $args = [ 'foo', 'bar' ]\n# $conf = { wiz => 'waz', biz => 'baz' }\n...\n}\n\nYou can also have your plugin install itself as a named filter by calling the \"installfilter()\"\nmethod from the \"init()\" method. You should provide a name for the filter, something that you\nmight like to make a configuration option.\n\nsub init {\nmy $self = shift;\nmy $name = $self->{ CONFIG }->{ name } || 'myfilter';\n$self->installfilter($name);\nreturn $self;\n}\n\nThis allows the plugin filter to be used as follows:\n\n[% USE MyFilter %]\n\n[% FILTER myfilter %]\n...\n[% END %]\n\nor\n\n[% USE MyFilter name = 'swipe' %]\n\n[% FILTER swipe %]\n...\n[% END %]\n\nAlternately, you can allow a filter name to be specified as the first positional argument.\n\nsub init {\nmy $self = shift;\nmy $name = $self->{ ARGS }->[0] || 'myfilter';\n$self->installfilter($name);\nreturn $self;\n}\n\n[% USE MyFilter 'swipe' %]\n\n[% FILTER swipe %]\n...\n[% END %]\n",
                "subsections": []
            },
            "EXAMPLE": {
                "content": "Here's a complete example of a plugin filter module.\n\npackage My::Template::Plugin::Change;\nuse Template::Plugin::Filter;\nuse base qw( Template::Plugin::Filter );\n\nsub init {\nmy $self = shift;\n\n$self->{ DYNAMIC } = 1;\n\n# first arg can specify filter name\n$self->installfilter($self->{ ARGS }->[0] || 'change');\n\nreturn $self;\n}\n\nsub filter {\nmy ($self, $text, $args, $config) = @;\n\n$config = $self->mergeconfig($config);\nmy $regex = join('|', keys %$config);\n\n$text =~ s/($regex)/$config->{ $1 }/ge;\n\nreturn $text;\n}\n\n1;\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "Andy Wardley <abw@wardley.org> <http://wardley.org/>\n",
                "subsections": []
            },
            "COPYRIGHT": {
                "content": "Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.\n\nThis module is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "Template::Plugin, Template::Filters, Template::Manual::Filters\n",
                "subsections": []
            }
        }
    }
}