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

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

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

CPAN RT