NAME

MKDoc::Core::Plugin - Class for atomic MKDoc application functionality

SUMMARY

The MKDoc::Core plugin system is a fundamental foundation for any application which uses the MKDoc::Core framework. Plugins are classes which are executed one after the other in a predefined order.

The plugin processor (MKDoc::process) executes a list of plugins until one (usually the one which handles the request) returns 'TERMINATE'.

Petal modifiers

plugin:

Instanciates a plugin of class plugin_type and returns it. This is handy if you need to access the attributes methods of another plugin from the plugin you're on, e.g:

    petal:define="details flo::plugin::Account::Details"

global:

Gives you access to any scalar variable stored in $::. For example:

    petal:define="site_dir global: MKD__SITE_DIR"

Methods

$self->equals ($otherplugin);

Returns TRUE if the class of $self is the same as the class of $otherplugin.

Since by default plugin objects do not have any data a class equivalence makes sense, however this behavior can be subclassed as necessary.

$self->would_activate();

Returns TRUE if this plugin would activate if it was requested. Returns FALSE otherwise.

For example:

    <span
        petal:define="details flo::plugin::Account::Details"
        petal:condition="details/would_activate"
    > ./.account.details can be accessed from here!</span>

For convenience, would_activate always returns FALSE if invoked on the same class of plugin that is currently being activated. This is because usually, hyperlinking to yourself is rather useless.

i.e. if you were using the piece of code above in the account details plugin itself, details/would_activate would always return false.

$thing->current_plugin();

Returns the current plugin which is being executed.

$self->is_current_plugin();

Returns TRUE if $self is the plugin being currently executed, FALSE otherwise.

$self->main();

This class method is called by the MKDoc module. Unless overriden it instantiates the current plugin and checks to see if it should be activated. If so it processes the request by calling run(), otherwise it does nothing.

Returns 'TERMINATE' if the request was handled by this plugin, false if not, or undef on error.

$class->new();

Very basic constructor which instantiates a new object. Calls the _initialize method.

$self->_initialize();

Initializes this object, called by new(). This is empty, and here to be overrided if necessary. Returns $self, or undef on failure.

$self->run();

Runs the current plugin. If the request is a POST, runs $self->http_post(). If it's a GET, runs $self->http_get().

$self->http_get();

Processes an HTTP GET request.

$self->http_post();

Processes an HTTP POST request. Defaults http_get() by default.

$self->activate();

Returns TRUE if this plugin wants to be activated, FALSE otherwise.

By default it returns true if $self->location() equals the current PATH_INFO.

$self->uri();

By default, returns the URI of the current plugin without any parameters. However, this behavior can be overriden as follows:

  # http://example.com/.plugin
  $plugin->uri();
  
  # http://example.com/.plugin?foo=bar
  $plugin->uri (foo => 'bar');
  
  # http://example.com/.plugin?keep-original=parameters
  $plugin->uri ('parameters');
  
  # http://example.com/.plugin?keep-original=parameters;foo=bar
  $plugin->uri ( 'parameters', foo => 'bar');

$self->uri_relative ($other);

Same this object's URI relative to $other. $other can be a URI object, a SCALAR representing a URI, or an object which MUST have a uri() method.

$self->language();

Returns a MKDoc::Language object which represents the preferred language to be used for this plugin. By order of preference:

looks into $ENV{HTTP_ACCEPT_LANGUAGE}

looks at $ENV{MKD__DEFAULT_LANGUAGE}

new MKDoc::Language ('en')

$self->HTTP_Content_Type();

Returns the content-type associated with this plugin. By default, returns "text/html; charset=UTF-8"

$self->has_errors();

Returns TRUE if the current plugin object holds error that needs to be displayed, false otherwise.

$self->errors();

Returns a list of errors, or an array ref in scalar context.

$self->add_error (@_);

Adds all the errors in @_ to the current plugin object.

$self->render_http

Renders the current object with render(). Sets the response object.

Explores all the inherited HTTP_ methods and sets HTTP headers accordingly.

$this->_render_http_headers()

Recursively introspects $this and its base classes and find all methods which starts with HTTP_. Returns a list of methods found.

This little hack is written so that you can simply add HTTP headers by defining methods, e.g.

  sub HTTP_X_Bender { "Bite my shiny, metal ass!" }

Will set the following header:

  X-Bender: Bite my shiny, metal ass!

$self->render (%args);

Renders the current object, passing %args to the template being used. Intercepts '__input__' and '__output__' to set Petal processing vars.

Returns the rendered document on success, or undef on error. See template_path().

$self->env()

Returns the environment variables as a hash reference.

$self->env_keys();

Returns the environment variables keys as an array or an array ref depending on the context.

$self->env_value ($key);

Returns the environment variable value for $key, i.e.

    my $path_info = $self->env_value ('PATH_INFO');

$self->template_path();

Returns the template path relative to Petal @BASE_DIR directories.

By default if your plugin is called something like:

  Foo::Bar::Plugin::Hello::World

It will return:

  /hello/world/

This method is subclassable.

$self->location();

Returns the location of the current plugin. By default, returns the current PATH_INFO.

$self->request();

Returns the MKDoc::Core::Request object singleton.

$self->response();

Returns the MKDoc::Core::Response object singleton.

$self->return_uri();

Some plugins have a need to redirect to a return uri once they have finished processing. This is usually the case with POST request. This method tries to provide a sensible default:

it looks for a return_uri parameter

otherwise it looks in $ENV{HTTP_REFERER}

otherwise it returns the root of the website by setting path_info to '/'.

AUTHOR

Copyright 2003 - MKDoc Holdings Ltd.

Author: Jean-Michel Hiver

This module is free software and is distributed under the same license as Perl itself. Use it at your own risk.

SEE ALSO

  L<Petal> TAL for perl
  MKDoc: http://www.mkdoc.com/

Help us open-source MKDoc. Join the mkdoc-modules mailing list:

  mkdoc-modules@lists.webarch.co.uk

cpanm MKDoc::Core

perl -MCPAN -e shell
install MKDoc::Core