NAME

Konstrukt::Doc::Tutorial::Plugin::Randomline - Create a really simple plugin putting out a random line

DESCRIPTION

This tutorial will teach you how to create a very simple plugin, that you can use in your web pages.

SETUP

Note: For the general setup of a new website see "SETUP" in Konstrukt::Doc::Tutorial::Usage::Blog.

For your plugin to be loaded, Perl must find it in its @INC paths. To create a plugin for a local website only, you can easily create a new directory for it and add this directory to Perl's @INC:

1. Create a new directory for your custom plugins

For example /path/to/your/site/lib. Inside that directory create the directories Konstrukt/Plugin, where you will put your plugin module. So the whole path to the directory for your custom plugin modules will be

/path/to/your/site/lib/Konstrukt/Plugin

2. Let Perl know to look for additional modules in this directory.

Add this line to your konstrukt.settings:

lib /path/to/your/site/lib

See also "Installation of custom plugins" in Konstrukt::Doc::Installation.

CREATE THE PLUGIN

We will create a very simple plugin, that will print a random line out of the embedded content.

Create a file (e.g. random.html) with this content:

        <& randomline &>
                some of
                these lines
                will be
                put out
                randomly
        <& / &>

Create a file randomline.pm in your custom plugin directory with this skeleton:

        package Konstrukt::Plugin::randomline;
        
        use strict;
        use warnings;
        
        use base 'Konstrukt::SimplePlugin';
        
        #the default action for your plugin
        sub default : Action {
                my ($self, $tag, $content, $params) = @_;
                print 'hi!';
        }
        
        1;

You can now point your web browser to the web page (e.g. random.html) and you will see the text:

        hi!

ADD THE LOGIC

We want to pick a random line of the embedded text and print it out. Replace the print statement in the default action with this code:

        #split the content into lines
        my @lines = split /[ \t]*\r?\n[ \t]*/, $content;
        #remove empty lines
        @lines = grep { !/^\s*$/ } @lines;
        #print a random line
        print $lines[int rand @lines];

That's it!

You need to restart/reload your Apache, if you're using mod_perl, so that it loads your plugin module again.

APPENDIX: THE COMPLETE PLUGIN

        package Konstrukt::Plugin::randomline;
        
        use strict;
        use warnings;
        
        use base 'Konstrukt::SimplePlugin';
        
        #the default action for your plugin
        sub default : Action {
                my ($self, $tag, $content, $params) = @_;
                #split the content into lines
                my @lines = split /[ \t]*\r?\n[ \t]*/, $content;
                #remove empty lines
                @lines = grep { !/^\s*$/ } @lines;
                #print a random line
                print $lines[int rand @lines];
        }
        
        1;

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::Tutorial::Plugin::Note::Actions

Previous: Konstrukt::Doc::Tutorial::Usage::Blog

Parent: Konstrukt::Doc

See also: Konstrukt::SimplePlugin, Konstrukt::Doc::CreatingPlugins

cpanm Konstrukt

perl -MCPAN -e shell
install Konstrukt