]> sipb.mit.edu Git - ikiwiki.git/blob - doc/patchqueue/varioki_--_add_template_variables___40__with_closures_for_values__41___in_ikiwiki.setup.mdwn
add warnings about using map, inline, etc with the sidebar causing
[ikiwiki.git] / doc / patchqueue / 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 > Here's a dump of the file Manoj sent me, for reference.
23
24 > My take on this is that simple plugins can do the same sort of things, this is
25 > kind of wanting to avoid the plugin mechanism and just use templates and
26 > stuff in the config file. Not too thrilled about that. --[[Joey]]
27
28 ----
29
30 <pre>
31 * looking for srivasta@debian.org--2006-misc/ikiwiki--upstream--1.0--patch-488 to compare with
32 * comparing to srivasta@debian.org--2006-misc/ikiwiki--upstream--1.0--patch-488: ................................................................ done.
33
34 * added files
35
36 --- /dev/null
37 +++ mod/IkiWiki/Plugin/.arch-ids/varioki.pm.id
38 @@ -0,0 +1 @@
39 +Manoj Srivastava <srivasta@debian.org> Thu Dec  7 12:59:07 2006 12659.0
40 --- /dev/null
41 +++ mod/IkiWiki/Plugin/varioki.pm
42 @@ -0,0 +1,190 @@
43 +#!/usr/bin/perl
44 +#                              -*- Mode: Cperl -*- 
45 +# varioki.pm --- 
46 +# Author           : Manoj Srivastava ( srivasta@glaurung.internal.golden-gryphon.com ) 
47 +# Created On       : Wed Dec  6 22:25:44 2006
48 +# Created On Node  : glaurung.internal.golden-gryphon.com
49 +# Last Modified By : Manoj Srivastava
50 +# Last Modified On : Thu Dec  7 13:07:36 2006
51 +# Last Machine Used: glaurung.internal.golden-gryphon.com
52 +# Update Count     : 127
53 +# Status           : Unknown, Use with caution!
54 +# HISTORY          : 
55 +# Description      : 
56 +# 
57 +# arch-tag: 6961717b-156f-4ab2-980f-0d6a973aea21
58 +#
59 +# Copyright (c) 2006 Manoj Srivastava <srivasta@debian.org>
60 +#
61 +# This program is free software; you can redistribute it and/or modify
62 +# it under the terms of the GNU General Public License as published by
63 +# the Free Software Foundation; either version 2 of the License, or
64 +# (at your option) any later version.
65 +#
66 +# This program is distributed in the hope that it will be useful,
67 +# but WITHOUT ANY WARRANTY; without even the implied warranty of
68 +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
69 +# GNU General Public License for more details.
70 +#
71 +# You should have received a copy of the GNU General Public License
72 +# along with this program; if not, write to the Free Software
73 +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
74 +#
75 +
76 +require 5.002;
77 +
78 +package IkiWiki::Plugin::varioki;
79 +
80 +use warnings;
81 +use strict;
82 +use IkiWiki '1.00';
83 +
84 +our $VERSION = "0.1";
85 +my $file = __FILE__;
86 +
87 +
88 +=head1 NAME
89 +
90 +varioki - Add variables for use in ikiwiki templates
91 +
92 +=cut
93 +
94 +=head1 DESCRIPTION
95 +
96 +This plugin attempts to provide a means to add templates for use in
97 +ikiwiki templates, based on a hash variable set in the ikiwiki
98 +configuration file. The motivation for this plugin was to provide an
99 +easy way for end users to add information to be used in templates --
100 +for example, my C<Blosxom> blog entry template does fancy things with
101 +the date components of the entry, and there was no easy way to get
102 +that information into the template. Or if one wants to have a
103 +different page template for the top level index page than for the rest
104 +of the pages in the wiki (for example, to only put special content,
105 +like, say, C<last.fm> play lists, only on the front page).
106 +
107 +This plugin hooks itsef into the C<pagetemplate> hook, and adds
108 +parameters to the appropriate templates based on the type. For
109 +example, the following inseted into C<ikiwiki.setup> creates
110 +C<TMPL_VAR MOTTO>, C<ARRAYVAR>, C<HASHVAR> and C<TOPLVL> which can
111 +then be used in your templates. The array and hash variables are only
112 +for completeness; I suspect that the first two forms are all that are
113 +really required.
114 +
115 + varioki => {
116 +   'motto'    => '"Manoj\'s musings"',
117 +   'toplvl'   => 'sub {return $page eq "index"}',
118 +   'arrayvar' => '[0, 1, 2, 3]',
119 +   'hashvar'  => '{1, 1, 2, 2}'
120 + },
121 +
122 +Please note that the values in the hash must be simple strings which
123 +are then eval'd, so a string value has to be double quoted, as above
124 +(the eval strips off the outer quotes).  
125 +
126 +=cut
127 +
128 +
129 +sub import { #{{{
130 +       hook(type => "pagetemplate", id => "varioki", call => \&pagetemplate);
131 +} # }}}
132 +
133 +
134 +=pod
135 +
136 +For every key in the configured hash, the corresponding value is
137 +evaluated.  Based on whether the value was a stringified scalar, code,
138 +array, or hash, the value of the template parameter is generated on
139 +the fly.  The available variables are whatever is available to
140 +C<pagetemplate> hook scripts, namely, C<$page>, C<$destpage>, and
141 +C<$template>.  Additionally, the global variables and functions as
142 +defined in the Ikiwiki documentation
143 +(L<http://ikiwiki.kitenet.net/plugins/write.html>) may be used.
144 +
145 +=cut
146 +
147 +sub pagetemplate (@) { #{{{
148 +       my %params=@_;
149 +       my $page=$params{page};
150 +       my $template=$params{template};
151 +        
152 +        return unless defined $config{varioki};
153 +         for my $var (keys %{$config{varioki}}) {
154 +           my $value;
155 +           my $foo;
156 +           eval "\$foo=$config{varioki}{$var}";
157 +           if (ref($foo) eq "CODE") {
158 +             $value = $foo->();
159 +           }
160 +           elsif (ref($foo) eq "SCALAR") {
161 +             $value = $foo;
162 +           }
163 +           elsif (ref($foo) eq "ARRAY") {
164 +             $value = join ' ', @$foo;
165 +           }
166 +           elsif (ref($foo) eq "HASH") {
167 +             for my $i (values %$foo ) {
168 +               $value .= ' ' . "$i";
169 +             }
170 +           }
171 +           else {
172 +             $value = $foo;
173 +           }
174 +           warn "$page $var $value\n";
175 +           if ($template->query(name => "$var")) {
176 +             $template->param("$var" =>"$value");
177 +           }
178 +        }
179 +} # }}}
180 +
181 +1;
182 +
183 +=head1 CAVEATS
184 +
185 +This is very inchoate, at the moment, and needs testing. Also, there
186 +is no good way to determine how to handle hashes as values --
187 +currently, the code just joins all hash values with spaces, but it
188 +would be easier for the user to just use an anonymous sub instead of
189 +passing in a hash or an array.
190 +
191 +=cut
192 +
193 +=head1 BUGS
194 +
195 +Since C<ikiwiki> evals the configuration file, the values have to all
196 +on a single physical line. This is the reason we need to use strings
197 +and eval, instead of just passing in real anonymous sub references,
198 +since the eval pass converts the coderef into a string of the form
199 +"(CODE 12de345657)" which can't be dereferenced.
200 +
201 +=cut
202 +
203 +=head1 AUTHOR
204 +
205 +Manoj Srivastava <srivasta@debian.org>
206 +
207 +=head1 COPYRIGHT AND LICENSE
208 +
209 +This script is a part of the Devotee package, and is 
210 +
211 +Copyright (c) 2002 Manoj Srivastava <srivasta@debian.org>
212 +
213 +This program is free software; you can redistribute it and/or modify
214 +it under the terms of the GNU General Public License as published by
215 +the Free Software Foundation; either version 2 of the License, or
216 +(at your option) any later version.
217 +
218 +This program is distributed in the hope that it will be useful,
219 +but WITHOUT ANY WARRANTY; without even the implied warranty of
220 +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
221 +GNU General Public License for more details.
222 +
223 +You should have received a copy of the GNU General Public License
224 +along with this program; if not, write to the Free Software
225 +Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
226 +
227 +=cut
228 +
229 +1;
230 +
231 +__END__
232 +
233 </pre>