This tutorial will walk you through [[writing|write]] your first ikiwiki
plugin.
-What should the plugin do? Let's make it calculate and output the Fibonachi
-sequense. To output the next number in the sequence, all a user has to do
+What should the plugin do? Let's make it calculate and output the Fibonacci
+sequence. To output the next number in the sequence, all a user has to do
is write this on a wiki page:
- \[[fib ]]
+ \[[!fib]]
-When the page is built, that'll be replaced by the next number in the
-sequence.
+When the page is built, the [[ikiwiki/directive]] will be
+replaced by the next number in the sequence.
-Most of ikiwiki's plugins are written in perl, and it's currently easiest
-to write them in perl. So, open your favorite text editor, and start
+Most of ikiwiki's plugins are written in Perl, and it's currently easiest
+to write them in Perl. So, open your favorite text editor and start
editing a file named "fib.pm".
#!/usr/bin/perl
-This isn't really necessary, since fib.pm will be a perl module, but it's
+This isn't really necessary, since fib.pm will be a Perl module, but it's
nice to have. Since it's a module, the next bit is this. Notice the "fib"
at the end, matching the "fib" in the filename.
use warnings;
use strict;
- use IkiWiki 2.00;
+ use IkiWiki 3.00;
Ok, boilerplate is out of the way. Now to add the one function that ikiwiki
expects to find in any module: `import`. The import function is called when
-the module is first loaded, and what modules typically do with it is
+the module is first loaded; what modules typically do with it is
register hooks that ikiwiki will call later.
sub import {
}
This has hooked our plugin into the preprocess hook, which ikiwiki uses to
-expand [[PreprocessorDirectives|preprocessordirectives]]. Notice that "fib"
-has shown up again. It doesn't actually have to match the module name this
-time, but it generally will. This "fib" is telling ikiwiki what kind of
-PreprocessorDirective to handle, namely one that looks like this:
+expand preprocessor [[directives|ikiwiki/directive]]. Notice
+that "fib" has shown up again. It doesn't actually have to match the module
+name this time, but it generally will. This "fib" is telling ikiwiki what
+kind of preprocessor directive to handle, namely one that looks like this:
- \[[fib ]]
+ [[!fib ]]
Notice the `\&preprocess`? This is how you pass a reference to a function,
and the `preprocess` function is the one that ikiwiki will call to expand
-the PreprocessorDirective. So, time to write that function:
+the preprocessor directive. So, time to write that function:
sub preprocess {
my %params=@_;
}
Whatever this function returns is what will show up on the wiki page.
-Since this is the Fibonachi sequence, returning 1 will be right for the
+Since this is the Fibonacci sequence, returning 1 will be right for the
first two calls anways, so our plugin isn't _too_ buggy. ;-) Before we fix
the bug, let's finish up the plugin.
1
-Always put this as the last line in your perl modules. Perl likes it.
+Always put this as the last line in your Perl modules. Perl likes it.
Ok, done! If you save the plugin, you can copy it to a place your ikiwiki
looks for plugins (`/usr/share/perl5/IkiWiki/Plugins/` is a good bet; see
-[[plugin/install]] for the details of how to figure out where to
+[[install]] for the details of how to figure out where to
install it). Then configure ikiwiki to use the plugin, and you're ready to
-insert at least the first two numbers of the Fibonachi sequence on web
+insert at least the first two numbers of the Fibonacci sequence on web
pages. Behold, the power of ikiwiki! ...
----
You could stop here, if you like, and go write your own plugin that does
something more useful. Rather than leave you with a broken fib plugin
though, this tutorial will go ahead and complete it. Let's add a simple
-Fibonachi generating function to the plugin. This is right out of a
+Fibonacci generating function to the plugin. This is right out of a
textbook.
sub fib {
Feel free to try it out with a simple page like this:
- \[[fib ]], \[[fib ]], \[[fib ]], \[[fib ]], \[[fib ]]
+ [[!fib ]], [[!fib ]], [[!fib ]], [[!fib ]], [[!fib ]]
Looks like it works ok, doesn't it? That creates a page that lists:
and the standalone page another. The numbers might even skip over part of
the sequence in some cases.
-Obviously, using a global `$last` veriable was a bad idea. It would
+Obviously, using a global `$last` variable was a bad idea. It would
work ok in a more regular cgi-based wiki, which only outputs one page per
run. But since ikiwiki is a wiki *compiler*, things are a bit more
-complicated. It't not very hard to fix, though, if we do want the seqense
+complicated. It's not very hard to fix, though, if we do want the sequence
to start from 1 in every page that uses it.
my %last;
It would be nice to be able to jump directly to a given point in the
sequence:
- \[[fib seed=20]], [[fib ]], [[fib ]]
+ \[[!fib seed=20]], [[!fib ]], [[!fib ]]
Just insert these lines of code inside `preprocess`, in the appropriate
spot:
}
my $num=$last{$page}++;
if ($num > 25) {
- return "[[fib will only calculate the first 25 numbers in the sequence]]";
+ error "can only calculate the first 25 numbers in the sequence";
}
return fib($num);
}
either case, it will run forever. Here's one way to fix that:
if (int($num) != $num || $num < 1) {
- return "[[fib positive integers only, please]]";
+ error "positive integers only, please";
}
As these security problems have demonstrated, even a simple input from the
-user needs to be checked thuroughly before being used by an ikiwiki plugin.
+user needs to be checked thoroughly before being used by an ikiwiki plugin.