{ "content": [ { "type": "text", "text": "# Template::Plugin (perldoc)\n\n## NAME\n\nTemplate::Plugin - Base class for Template Toolkit plugins\n\n## SYNOPSIS\n\npackage MyOrg::Template::Plugin::MyPlugin;\nuse base qw( Template::Plugin );\nuse Template::Plugin;\nuse MyModule;\nsub new {\nmy $class = shift;\nmy $context = shift;\nbless {\n...\n}, $class;\n}\n\n## DESCRIPTION\n\nA \"plugin\" for the Template Toolkit is simply a Perl module which exists in a known package\nlocation (e.g. \"Template::Plugin::*\") and conforms to a regular standard, allowing it to be\nloaded and used automatically.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS**\n- **DEEPER MAGIC** (1 subsections)\n- **AUTHOR**\n- **COPYRIGHT**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Template::Plugin", "section": "", "mode": "perldoc", "summary": "Template::Plugin - Base class for Template Toolkit plugins", "synopsis": "package MyOrg::Template::Plugin::MyPlugin;\nuse base qw( Template::Plugin );\nuse Template::Plugin;\nuse MyModule;\nsub new {\nmy $class = shift;\nmy $context = shift;\nbless {\n...\n}, $class;\n}", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 13, "subsections": [] }, { "name": "DESCRIPTION", "lines": 20, "subsections": [] }, { "name": "METHODS", "lines": 58, "subsections": [] }, { "name": "DEEPER MAGIC", "lines": 1, "subsections": [ { "name": "error", "lines": 74 } ] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 5, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] } ], "sections": { "NAME": { "content": "Template::Plugin - Base class for Template Toolkit plugins\n", "subsections": [] }, "SYNOPSIS": { "content": "package MyOrg::Template::Plugin::MyPlugin;\nuse base qw( Template::Plugin );\nuse Template::Plugin;\nuse MyModule;\n\nsub new {\nmy $class = shift;\nmy $context = shift;\nbless {\n...\n}, $class;\n}\n", "subsections": [] }, "DESCRIPTION": { "content": "A \"plugin\" for the Template Toolkit is simply a Perl module which exists in a known package\nlocation (e.g. \"Template::Plugin::*\") and conforms to a regular standard, allowing it to be\nloaded and used automatically.\n\nThe \"Template::Plugin\" module defines a base class from which other plugin modules can be\nderived. A plugin does not have to be derived from Template::Plugin but should at least conform\nto its object-oriented interface.\n\nIt is recommended that you create plugins in your own package namespace to avoid conflict with\ntoolkit plugins. e.g.\n\npackage MyOrg::Template::Plugin::FooBar;\n\nUse the PLUGINBASE option to specify the namespace that you use. e.g.\n\nuse Template;\nmy $template = Template->new({\nPLUGINBASE => 'MyOrg::Template::Plugin',\n});\n", "subsections": [] }, "METHODS": { "content": "The following methods form the basic interface between the Template Toolkit and plugin modules.\n\nload($context)\nThis method is called by the Template Toolkit when the plugin module is first loaded. It is\ncalled as a package method and thus implicitly receives the package name as the first parameter.\nA reference to the Template::Context object loading the plugin is also passed. The default\nbehaviour for the \"load()\" method is to simply return the class name. The calling context then\nuses this class name to call the \"new()\" package method.\n\npackage MyPlugin;\n\nsub load { # called as MyPlugin->load($context)\nmy ($class, $context) = @;\nreturn $class; # returns 'MyPlugin'\n}\n\nnew($context, @params)\nThis method is called to instantiate a new plugin object for the \"USE\" directive. It is called\nas a package method against the class name returned by load(). A reference to the\nTemplate::Context object creating the plugin is passed, along with any additional parameters\nspecified in the \"USE\" directive.\n\nsub new { # called as MyPlugin->new($context)\nmy ($class, $context, @params) = @;\nbless {\nCONTEXT => $context,\n}, $class; # returns blessed MyPlugin object\n}\n\nerror($error)\nThis method, inherited from the Template::Base module, is used for reporting and returning\nerrors. It can be called as a package method to set/return the $ERROR package variable, or as an\nobject method to set/return the object \"ERROR\" member. When called with an argument, it sets\nthe relevant variable and returns \"undef.\" When called without an argument, it returns the value\nof the variable.\n\npackage MyPlugin;\nuse base 'Template::Plugin';\n\nsub new {\nmy ($class, $context, $dsn) = @;\n\nreturn $class->error('No data source specified')\nunless $dsn;\n\nbless {\nDSN => $dsn,\n}, $class;\n}\n\npackage main;\n\nmy $something = MyPlugin->new()\n|| die MyPlugin->error(), \"\\n\";\n\n$something->dosomething()\n|| die $something->error(), \"\\n\";\n", "subsections": [] }, "DEEPER MAGIC": { "content": "The Template::Context object that handles the loading and use of plugins calls the new() and", "subsections": [ { "name": "error", "content": "looks something like this:\n\n$class = MyPlugin->load($context); # returns 'MyPlugin'\n\n$object = $class->new($context, @params) # MyPlugin->new(...)\n|| die $class->error(); # MyPlugin->error()\n\nThe load() method may alternately return a blessed reference to an object instance. In this\ncase, new() and error() are then called as *object* methods against that prototype instance.\n\npackage YourPlugin;\n\nsub load {\nmy ($class, $context) = @;\nbless {\nCONTEXT => $context,\n}, $class;\n}\n\nsub new {\nmy ($self, $context, @params) = @;\nreturn $self;\n}\n\nIn this example, we have implemented a 'Singleton' plugin. One object gets created when load()\nis called and this simply returns itself for each call to new().\n\nAnother implementation might require individual objects to be created for every call to new(),\nbut with each object sharing a reference to some other object to maintain cached data, database\nhandles, etc. This pseudo-code example demonstrates the principle.\n\npackage MyServer;\n\nsub load {\nmy ($class, $context) = @;\nbless {\nCONTEXT => $context,\nCACHE => { },\n}, $class;\n}\n\nsub new {\nmy ($self, $context, @params) = @;\nMyClient->new($self, @params);\n}\n\nsub addtocache { ... }\n\nsub getfromcache { ... }\n\npackage MyClient;\n\nsub new {\nmy ($class, $server, $blah) = @;\nbless {\nSERVER => $server,\nBLAH => $blah,\n}, $class;\n}\n\nsub get {\nmy $self = shift;\n$self->{ SERVER }->getfromcache(@);\n}\n\nsub put {\nmy $self = shift;\n$self->{ SERVER }->addtocache(@);\n}\n\nWhen the plugin is loaded, a \"MyServer\" instance is created. The new() method is called against\nthis object which instantiates and returns a \"MyClient\" object, primed to communicate with the\ncreating \"MyServer\".\n" } ] }, "AUTHOR": { "content": "Andy Wardley \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, Template::Plugins, Template::Context\n", "subsections": [] } } } }