doc/todo/varioki_--_add_template_variables___40__with_closures_for_values__41___in_ikiwiki.setup.mdwn

   1 varioki - Add variables for use in ikiwiki templates
   2
   3 This plugin attempts to provide a means to add templates for use in ikiwiki templates, based on a hash variable set in the ikiwiki configuration file. The motivation for this plugin was to provide an easy way for end users to add information to be used in templates -- for example, my "Blosxom" blog entry template does fancy things with the date components of the entry, and there was no easy way to get that information into the template. Or if one wants to have a different page template for the top level index page than for the rest of the pages inthe wiki (for example, to only put special content, like, say, 'last.fm" play lists, only on the front page).
   4
   5 This plugin hooks itsef into the "pagetemplate" hook, and adds parameters to the appropriate templates based on the type. For example, the following inserted into "ikiwiki.setup" creates "TMPL_VAR MOTTO" and "TOPLVL" which can then be used in your templates.
   6
   7     varioki => {
   8       ’motto’    => ’"Manoj\’s musings"’,
   9       ’toplvl’   => ’sub {return $page eq "index"}’
  10     },
  11
  12 For every key in the configured hash, the corresponding value is evaluated.  Based on whether the value was a stringified scalar, code, array, or hash, the value of the template parameter is generated on the fly.  The available variables are whatever is available to "pagetemplate" hook scripts, namely, $page, $destpage, and $template.  Additionally, the global variables and functions as defined in the Ikiwiki documentation (<http://ikiwiki.info/plugins/write/>) may be used.
  13
  14 ManojSrivastava
  15
  16 > I think you could now implement "toplvl" using [[conditionals|/plugins/conditional]]:
  17 >
  18 >     \[[!if test="destpage(/index)" then="""...""" else="""..."""]]
  19 >
  20 > --[[JoshTriplett]]
  21
  22 > > Right. But how about some more complex stuff, for example, from my varioki settings below? --ManojSrivastava
  23
  24 > Here's a dump of the file Manoj sent me, for reference.
  25 >
  26 > My take on this is that simple plugins can do the same sort of things, this is
  27 > kind of wanting to avoid the plugin mechanism and just use templates and
  28 > stuff in the config file. Not too thrilled about that. --[[Joey]]
  29
  30 > > OK. How do you implement something like category I have in my varioki
  31 > >  settings? As a user, I can just add new stuff to my config and my template;
  32 > >  with a plugin I'll have to write a plugin, and install it in the ikiwiki plugin
  33 > > directory,  which is not very easy for a plain ol' user.  Not everyone is the
  34 > >  sysadmin of their own machines with access to system dirs. --ManojSrivastava
  35
  36 >>> It seems worth mentioning here that the `libdir` configuration parameter
  37 >>> lets you install additional plugins in a user-controlled directory
  38 >>> (*libdir*`/IkiWiki/Plugin`), avoiding needing root; indeed, a full local
  39 >>> ikiwiki installation without any involvement from the sysadmin is
  40 >>> [[possible|tips/DreamHost]]. --[[smcv]]
  41
  42 <pre>
  43                 varioki => {'motto'    => '"Manoj\'s musings"',
  44                         'arrayvar' => '[0, 1, 2, 3]',
  45                         'hashvar'  => '{1, 1, 2, 2}',
  46                         'toplvl'   => 'sub {return $page eq "index"}',
  47                         'isblog'   => 'sub {return $page =~ m,blog/.*,}',
  48                         'category' => 'sub { return " " unless $page=~ m,^blog/,; my  $p=""; my $i="&lt;a href=\"$config{url}/blog\"&gt;Top::&lt;/a&gt;"; my @a=split ("/",$page); shift @a; pop @a; foreach my $dir (@a) { $p.=$dir; $i.="&lt;a href=\"$config{url}/tag/$p\"&gt;$dir&lt;/a&lt;::"; $p.="/"; }; return $i }',
  49                         'date'     => 'sub { return POSIX::strftime("%d", gmtime((stat(srcfile($pagesources{$page})))[9])); }',
  50                         'year'     => 'sub { return POSIX::strftime("%Y", gmtime((stat(srcfile($pagesources{$page})))[9])); }',
  51                         'month'    => 'sub { return POSIX::strftime("%B", gmtime((stat(srcfile($pagesources{$page})))[9])); }',
  52                        'day'      => 'sub { return POSIX::strftime("%A", gmtime((stat(srcfile($pagesources{$page})))[9])); }',
  53                       },
  54 </pre>
  55
  56 > > I'd argue in favour of this plugin; it's true that a simple plugin can be
  57 > > used to set a template variable, but that makes it necessary to write a new
  58 > > plugin for every variable (or set of variables) that are needed. In that
  59 > > kind of situation, I don't think bypassing the plugin mechanism is a bad
  60 > > thing, unless an ever-growing collection of plugins to set one or two
  61 > > variables is a good thing.
  62 > >
  63 > > --[[bma]]
  64
  65 ----
  66
  67 <pre>
  68 * looking for srivasta@debian.org--2006-misc/ikiwiki--upstream--1.0--patch-488 to compare with
  69 * comparing to srivasta@debian.org--2006-misc/ikiwiki--upstream--1.0--patch-488: ................................................................ done.
  70
  71 * added files
  72
  73 --- /dev/null
  74 +++ mod/IkiWiki/Plugin/.arch-ids/varioki.pm.id
  75 @@ -0,0 +1 @@
  76 +Manoj Srivastava <srivasta@debian.org> Thu Dec  7 12:59:07 2006 12659.0
  77 --- /dev/null
  78 +++ mod/IkiWiki/Plugin/varioki.pm
  79 @@ -0,0 +1,190 @@
  80 +#!/usr/bin/perl
  81 +#                              -*- Mode: Cperl -*-
  82 +# varioki.pm ---
  83 +# Author           : Manoj Srivastava ( srivasta@glaurung.internal.golden-gryphon.com )
  84 +# Created On       : Wed Dec  6 22:25:44 2006
  85 +# Created On Node  : glaurung.internal.golden-gryphon.com
  86 +# Last Modified By : Manoj Srivastava
  87 +# Last Modified On : Thu Dec  7 13:07:36 2006
  88 +# Last Machine Used: glaurung.internal.golden-gryphon.com
  89 +# Update Count     : 127
  90 +# Status           : Unknown, Use with caution!
  91 +# HISTORY          :
  92 +# Description      :
  93 +#
  94 +# arch-tag: 6961717b-156f-4ab2-980f-0d6a973aea21
  95 +#
  96 +# Copyright (c) 2006 Manoj Srivastava <srivasta@debian.org>
  97 +#
  98 +# This program is free software; you can redistribute it and/or modify
  99 +# it under the terms of the GNU General Public License as published by
 100 +# the Free Software Foundation; either version 2 of the License, or
 101 +# (at your option) any later version.
 102 +#
 103 +# This program is distributed in the hope that it will be useful,
 104 +# but WITHOUT ANY WARRANTY; without even the implied warranty of
 105 +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 106 +# GNU General Public License for more details.
 107 +#
 108 +# You should have received a copy of the GNU General Public License
 109 +# along with this program; if not, write to the Free Software
 110 +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 111 +#
 112 +
 113 +require 5.002;
 114 +
 115 +package IkiWiki::Plugin::varioki;
 116 +
 117 +use warnings;
 118 +use strict;
 119 +use IkiWiki '1.00';
 120 +
 121 +our $VERSION = "0.1";
 122 +my $file = __FILE__;
 123 +
 124 +
 125 +=head1 NAME
 126 +
 127 +varioki - Add variables for use in ikiwiki templates
 128 +
 129 +=cut
 130 +
 131 +=head1 DESCRIPTION
 132 +
 133 +This plugin attempts to provide a means to add templates for use in
 134 +ikiwiki templates, based on a hash variable set in the ikiwiki
 135 +configuration file. The motivation for this plugin was to provide an
 136 +easy way for end users to add information to be used in templates --
 137 +for example, my C<Blosxom> blog entry template does fancy things with
 138 +the date components of the entry, and there was no easy way to get
 139 +that information into the template. Or if one wants to have a
 140 +different page template for the top level index page than for the rest
 141 +of the pages in the wiki (for example, to only put special content,
 142 +like, say, C<last.fm> play lists, only on the front page).
 143 +
 144 +This plugin hooks itsef into the C<pagetemplate> hook, and adds
 145 +parameters to the appropriate templates based on the type. For
 146 +example, the following inseted into C<ikiwiki.setup> creates
 147 +C<TMPL_VAR MOTTO>, C<ARRAYVAR>, C<HASHVAR> and C<TOPLVL> which can
 148 +then be used in your templates. The array and hash variables are only
 149 +for completeness; I suspect that the first two forms are all that are
 150 +really required.
 151 +
 152 + varioki => {
 153 +   'motto'    => '"Manoj\'s musings"',
 154 +   'toplvl'   => 'sub {return $page eq "index"}',
 155 +   'arrayvar' => '[0, 1, 2, 3]',
 156 +   'hashvar'  => '{1, 1, 2, 2}'
 157 + },
 158 +
 159 +Please note that the values in the hash must be simple strings which
 160 +are then eval'd, so a string value has to be double quoted, as above
 161 +(the eval strips off the outer quotes).
 162 +
 163 +=cut
 164 +
 165 +
 166 +sub import {
 167 +       hook(type => "pagetemplate", id => "varioki", call => \&pagetemplate);
 168 +}
 169 +
 170 +
 171 +=pod
 172 +
 173 +For every key in the configured hash, the corresponding value is
 174 +evaluated.  Based on whether the value was a stringified scalar, code,
 175 +array, or hash, the value of the template parameter is generated on
 176 +the fly.  The available variables are whatever is available to
 177 +C<pagetemplate> hook scripts, namely, C<$page>, C<$destpage>, and
 178 +C<$template>.  Additionally, the global variables and functions as
 179 +defined in the Ikiwiki documentation
 180 +(L<http://ikiwiki.kitenet.net/plugins/write.html>) may be used.
 181 +
 182 +=cut
 183 +
 184 +sub pagetemplate (@) {
 185 +       my %params=@_;
 186 +       my $page=$params{page};
 187 +       my $template=$params{template};
 188 +
 189 +        return unless defined $config{varioki};
 190 +         for my $var (keys %{$config{varioki}}) {
 191 +           my $value;
 192 +           my $foo;
 193 +           eval "\$foo=$config{varioki}{$var}";
 194 +           if (ref($foo) eq "CODE") {
 195 +             $value = $foo->();
 196 +           }
 197 +           elsif (ref($foo) eq "SCALAR") {
 198 +             $value = $foo;
 199 +           }
 200 +           elsif (ref($foo) eq "ARRAY") {
 201 +             $value = join ' ', @$foo;
 202 +           }
 203 +           elsif (ref($foo) eq "HASH") {
 204 +             for my $i (values %$foo ) {
 205 +               $value .= ' ' . "$i";
 206 +             }
 207 +           }
 208 +           else {
 209 +             $value = $foo;
 210 +           }
 211 +           warn "$page $var $value\n";
 212 +           if ($template->query(name => "$var")) {
 213 +             $template->param("$var" =>"$value");
 214 +           }
 215 +        }
 216 +}
 217 +
 218 +1;
 219 +
 220 +=head1 CAVEATS
 221 +
 222 +This is very inchoate, at the moment, and needs testing. Also, there
 223 +is no good way to determine how to handle hashes as values --
 224 +currently, the code just joins all hash values with spaces, but it
 225 +would be easier for the user to just use an anonymous sub instead of
 226 +passing in a hash or an array.
 227 +
 228 +=cut
 229 +
 230 +=head1 BUGS
 231 +
 232 +Since C<ikiwiki> evals the configuration file, the values have to all
 233 +on a single physical line. This is the reason we need to use strings
 234 +and eval, instead of just passing in real anonymous sub references,
 235 +since the eval pass converts the coderef into a string of the form
 236 +"(CODE 12de345657)" which can't be dereferenced.
 237 +
 238 +=cut
 239 +
 240 +=head1 AUTHOR
 241 +
 242 +Manoj Srivastava <srivasta@debian.org>
 243 +
 244 +=head1 COPYRIGHT AND LICENSE
 245 +
 246 +This script is a part of the Devotee package, and is
 247 +
 248 +Copyright (c) 2002 Manoj Srivastava <srivasta@debian.org>
 249 +
 250 +This program is free software; you can redistribute it and/or modify
 251 +it under the terms of the GNU General Public License as published by
 252 +the Free Software Foundation; either version 2 of the License, or
 253 +(at your option) any later version.
 254 +
 255 +This program is distributed in the hope that it will be useful,
 256 +but WITHOUT ANY WARRANTY; without even the implied warranty of
 257 +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 258 +GNU General Public License for more details.
 259 +
 260 +You should have received a copy of the GNU General Public License
 261 +along with this program; if not, write to the Free Software
 262 +Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 263 +
 264 +=cut
 265 +
 266 +1;
 267 +
 268 +__END__
 269 +
 270 </pre>
 271
 272 [[!tag patch]]