/ 
Konstrukt-0.5-beta7
River stage zero No dependents
/ Konstrukt::Doc::CreatingPlugins

NAME

Konstrukt::Doc::CreatingPlugins - Create your own plugins

BASICS

Basically you subclass the SimplePlugin or Plugin module and add your own logic by overwriting the stub methods. So you might want to take a look at the documentation of those plugins, which explains the plugin creation interfaces.

CONVENTIONS

TODO

PARSE-TREE AND CACHING

TODO: Motivation, tree, nodes, caching.

CORE MODULES

The goals of this framework include rapid development and code reuse. This includes that most nasty work like session management and so on will already be done for you.

You are encouraged to use the existing core modules and plugins to do the basic work and focus on your application.

Mostly interesting for plugin development

Here's a list of the core modules, which are immediately interesting for plugin development.

  • Konstrukt::Cache - Caching functionalities. Useful to read if you're developing high performance plugins and want to cache data yourself or want to use the automatic cache validation when using files from disk.

  • Konstrukt::DBI - Database handle pool. Eases the access to databases. Features DB connection settings management, DB handle pooling and automatic error handling.

  • Konstrukt::Debug - Debug and error message handling. Here you can configure (in the source) how noisy the debug output will be.

  • Konstrukt::Event - Event management. Plugins can register for events and other plugins can trigger them. Allows for a very loose coupled plugin interaction.

  • Konstrukt::File - Comfortable handling of files, file names and paths.

  • Konstrukt::Lib - Common function library. Some smaller, useful functions like HTML-escaping, sending mails etc. are collected here.

  • Konstrukt::Plugin - Base class for the Konstrukt plugins. You have to subclass this one if you want to create a "fully featured" (say low level/fast) Konstrukt plugin.

  • Konstrukt::Request - Class for everything related to the page request. Provides access to the request method, URI and headers.

  • Konstrukt::Response - Class for everything related to the generated response. You can specify the response's HTTP status and headers here.

  • Konstrukt::Session - Session management (Cookies/Session). Automatically creates a session for each visitor and tracks it using a cookie. You can easily store and access persistent data with this module.

  • Konstrukt::Settings - Settings management. All settings are stored in the konstrukt.settings file, which is read by this module. You can easily access these settings, modify them or use it to define default settings for your plugin.

  • Konstrukt::SimplePlugin - Base class for simple Konstrukt plugins. Provides a rather simple interface to create your own plugins and applications. You don't have to know much about the Framework to create plugins using this base class. The downside of the simplicity is a loss in performance over the creation using the lower level plugin base class.

Mostly interesting for core development

This are the remaining core modules, which you probably won't need to develop your own plugins. These are rather used internally.

  • Konstrukt::Attributes - Sub attribute handling.

  • Konstrukt::Handler - Base class for handlers that control the processing of the requests. There already exist some handlers and you can create your own ones.

  • Konstrukt::Parser - Parser for the tag syntax. Usually only used internally unless you want to develop plugins that offer an own tag syntax. Features parsing of text against special tags and execution of those tags.

  • Konstrukt::PrintRedirector - Catches the print statements and fires an event on each print. Used in the perl plugin.

  • Konstrukt::TagHandler - Base class for the tag handlers. Using this baseclass you can create own tag types that will be recognized in the parsing process.

EXISTING PLUGINS

Also most of the plugins have a perl interface that offers some methods to utilize these plugins.

This will usually be done like this:

my $someplugin = use_plugin 'someplugin';
$someplugin->method($arg);

The perl interface of each plugin is documented in the SYNOPSIS and the DESCRIPTION of the plugins. Additionally each method of each plugin is also documented with it's purpose, parameters and return value.

So the best idea would be just to take a look at the documentation of the plugins.

A complete list of the plugins that are shipped with this package is available here.

TROUBLESHOOTING

The prepare method won't be executed

If you feel like the prepare-method of your plugin doesn't get executed, the reason will probably be that you're using a cached page.

One main feature of the cache architecture is to run prepare only once and cache the results.

To fix this, delete the cached file or disable the cache if you're working on your plugin.

TODO

Complete this document.

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

Next: Konstrukt::Doc::CoreDevelopment

Previous: Konstrukt::Doc::ApplicationPlugins

Parent: Konstrukt::Doc

See also: Konstrukt::Doc::PluginList