X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/79e6dd9d9b2b51aad33e2af3ccb89f0e69343a36..8cab4366d1eafa8c8e8ccb0d0d8166343bd9df49:/doc/plugins/write/tutorial.mdwn diff --git a/doc/plugins/write/tutorial.mdwn b/doc/plugins/write/tutorial.mdwn index 2fc1c3e3f..5b810a18f 100644 --- a/doc/plugins/write/tutorial.mdwn +++ b/doc/plugins/write/tutorial.mdwn @@ -1,22 +1,22 @@ 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/PreProcessorDirective]] 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. @@ -31,7 +31,7 @@ important one is the IkiWiki module. 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 { @@ -39,12 +39,12 @@ register hooks that ikiwiki will call later. } 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 [[PreprocessorDirectives|ikiwiki/preprocessordirective]]. 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: - \[[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 @@ -56,19 +56,19 @@ the PreprocessorDirective. So, time to write that function: } 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 [[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! ... ---- @@ -76,7 +76,7 @@ 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 { @@ -98,7 +98,7 @@ And let's change the `preprocess` sub to use it: 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: @@ -119,7 +119,7 @@ the sequence in some cases. Obviously, using a global `$last` veriable 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; @@ -139,7 +139,7 @@ Ok, one more enhancement. Just incrementing the numbers is pretty boring. 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: @@ -169,7 +169,7 @@ be a guard on how high it will go. } 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); } @@ -182,8 +182,8 @@ does for numbers less than 1. Or for any number that's not an integer. In 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.