NAME

Konstrukt::SimplePlugin - Base class for simple Konstrukt plugins.

SYNOPSIS

Writing own plugins

        package Konstrukt::Plugin::my_plugin;
        
        use base 'Konstrukt::SimplePlugin';
        
        #(over)write (some of) the methods: init, default-action, other action handlers.
        
        #per request initialization
        sub init {
                my ($self) = @_;
                #...
        }
        
        #initialization that is needed before the first time your plugin can be used
         
        
        #write methods for your actions (will be called with page.html?${yourpluginname}_action=some_action)
        sub some_action : Action {
                my ($self, $tag, $content, $params) = @_;
                #...
        }
        
        #will be called when no sub matches the action name
        sub default : Action {
                my ($self, $tag, $content, $params) = @_;
                #...
        }
        
        #...
        
        1;

Using existing plugins (within your plugin)

Basically:

        use Konstrukt::Plugin; #import use_plugin
        
        my $plugin = use_plugin 'some_plugin';
        $plugin->method();

See "Using existing plugins" in Konstrukt::Plugin for more details.

DESCRIPTION

Base class for simple Konstrukt plugins.

Only the methods relevant for creating a simple plugin are documented.

Every method that should be accessible from the client must have a :Action attribute. Otherwise it cannot be called from the client.

If you want some more control over what your plugin does (e.g. to gain performance) you may want to inherit Konstrukt::Plugin. As SimplePlugin inherits from Plugin you may also take more control of your plugin behaviour as you could when developing a Plugin. The methods aren't documented here to keep it simple, but you may of course read the Plugin docs and apply (most of) them to your SimplePlugin.

METHODS

init

Method that will be called right before the first usage within a request. Here you should do per request initialization work like definition of default settings.

Should be overridden by the inheriting class.

install

Should be overloaded by your plugin and its backends, if they need installation before the first run.

The installation should be performed according to the current settings like the selected backend and database settings as well as the template path.

Usually in the backend module this method will create database tables for your plugin. The "main" plugin should load the backend plugin on init, that is defined in the settings, and then the install method will be called automatically on the backend module when it gets loaded.

The "main" plugin may create templates that are needed for the output.

Will be called automatically after the plugin has been loaded and init()ialized, if the setting autoinstall is true.

You may want to use "plugin_dbi_install_helper" in Konstrukt::Lib for the installation of your DBI backend plugins and "plugin_file_install_helper" in Konstrukt::Lib for the installation of default templates for your plugin, which can be embedded at the end of your plugin module.

Don't confuse this method with "init", which will be called once on every request.

Parameters:

none

some_action : Action

You have to write a method for each "action" of your plugin. Your method will then be called with the parameters listed below.

The action will be called with page.html?${yourpluginname}action=some_action.

You may print some output here:

        print 'something';

Or put out other plugin tags (e.g. templates) by adding nodes to the result:

        #put out a template containing another template in a field:
        my $template = use_plugin 'template';
        $self->add_node($template->node('some.template', { some_field => $template->node('some_other.template') }));

Parameters:

• $tag - Reference to the tag node (and its children) that shall be handled. Contains the plugin tag in the parse tree and all related information - especially the tag attributes:

          my $source = $tag->{tag}->{attributes}->{src};

  and the content inside the tag (via the parse tree nodes), which should be only text and comment nodes:

          my $node = $tag->{first_child};
          while (defined $node) {
                  #do stuff on $node->{content}...
                  $node = $node->{next};
          }

• $content - The content below/inside the tag as a flat string. (Might be easier to deal with in some cases)

• $params - Reference to a hash of the passed CGI parameters.

default : Action

The default action handler of this plugin. This method will be called, when no action has been specified. For some more info take a look at "some_action".

This sub should be overridden by the inheriting class.

Parameters:

• $tag - Reference to the tag (and its children) that shall be handled.

• $content - The content below/inside the tag as a flat string.

• $params - Reference to a hash of the passed CGI parameters.

METHODS NOT DOCUMENTED HERE

To keep it simple some methods that evey plugin has are not documented here, as they are of minor relevance for "simple" plugin.

They are defined with good defaults for a simple plugin and you shouldn't need to care about them. If you're interested in this methods nonetheless, read on!

prepare_again

Returns 0 by default.

See "prepare_again" in Konstrukt::Plugin for more details.

execute_again

Returns 1 by default.

See "execute_again" in Konstrukt::Plugin for more details.

prepare

Won't be used by default.

See "prepare" in Konstrukt::Plugin for more details.

execute

Will handle the request internally and dispatch it to your action methods.

See "execute" in Konstrukt::Plugin for more details.

print_event

Will be used internally to catch the prints of your plugin.

Works the same way as in "print_event" in Konstrukt::Plugin::perl.

AUTHOR

Copyright 2006 Thomas Wittek (mail at gedankenkonstrukt dot de). All rights reserved.

This document is free software. It is distributed under the same terms as Perl itself.

SEE ALSO

Konstrukt::Plugin, Konstrukt::Parser::Node, Konstrukt

cpanm Konstrukt

perl -MCPAN -e shell
install Konstrukt