]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blob - doc/todo/allow_TMPL__95__LOOP_in_template_directives.mdwn
7a9191387b52bddf5f59e7a7ca3fdb75005a18ed
[git.ikiwiki.info.git] / doc / todo / allow_TMPL__95__LOOP_in_template_directives.mdwn
1 [[!tag patch todo]]
3 [[!template id="note" text="""
4 Simply copied this from my website
5 [[http://www.camco.ie/code/ikiwiki,3.20120202,20120313a/]]
6 feel free to reformat / delete"""]]
8 The following re-write allows for multiple definitions of the
9 same tag value in a [[plugins/template]] definition.  This, in turn, allows
10 us to use TMPL_LOOPS in our [[ikiwiki/directives/template]] directives; all-be-it in a
11 rather limited way.
13 I would, personally, only use this feature for very basic loops
14 and, although nested loops *might* be possible (with a little
15 more tinkering) it think any attempt would be better served by
16 [[Kathyrn Anderson's|http://www.katspace.org/]] [[field et
17 al.|http://ikiwiki.info/plugins/contrib/field/]] plugin.
19 It *is* (primarily) intended to allow insertion of organised CSS
20 blocks (i.e. `<div>`) through template directives (since i can't
21 seem to get HTML and Markup to mix the way I want).
23 [[!template id="note" text="""
24 Apologies for the re-write.  I struggle reading perl code that
25 I didn't write and (probably too often) re-format to reduce my
26 head-aches.  Anyway it didn't make sense to post the patch since
27 everything's changed now.
28 """]]
30 NB: this *should* be 100% backwards compatible.
32 # `lib/perl5/IkiWiki/Plugin/template.pm`
34 [[!format perl """
36         #!/usr/bin/perl
37         # Structured template plugin.
38         package IkiWiki::Plugin::template ;
40         use warnings ;
41         use strict ;
42         use IkiWiki 3.00 ;
43         use Encode ;
45         sub mktmpl_hash( $ ; $ ; @ ) ;
46                                 # declare to supress warning in recursive call
47         sub mktmpl_hash( $ ; $ ; @ )
48                                 # make hash for the template, filling
49                                 # values from the supplied params
50         {
51                 my $template = shift( @_ )
52                                 || error( "mktmpl_hash: no template provided" ) ;
53                 my $param_src = shift( @_ )
54                                 || error( "mktmpl_hash: no parameters" ) ;
56                 my $path ;
57                 if( $#_ > 0 )
58                 {
59                         $path = [ @_ ] ;
60                 } else {
61                         $path = shift(@_) || [] ;
62                 } ;
64                 my %params ;
66                 my @path_vars ;
67                 if( $#{$path} < 0 )
68                 {
69                         @path_vars = $template->query() ;
70                 } else {
71                         @path_vars = $template->query( loop => $path ) ;
72                 } ;
74                 foreach my $var ( @path_vars )
75                 {
76                         push( @{$path}, $var ) ;
77                         my $param_type = $template->query( name => $path ) ;
78                         if( $param_type eq 'VAR' )
79                         {
80                                 my @var_path = split( /_/, $var ) ;
81                                 if( $var_path[0] ne '' )
82                                 {
83                                         $path->[-1] = join( '_', @var_path[1..$#var_path] )
84                                                 if( $var_path[0] eq 'raw' ) ;
85                                         $params{$var} = shift( @{$param_src->{$path->[-1]}} )
86                                                         || return(undef) ;
87                                 } ;
88                         } elsif( $param_type eq 'LOOP' )
89                         {
90                                 $params{$var} = [] ;
91                                 push( @{$params{$var}}, $_ )
92                                         while( $_ = mktmpl_hash($template,$param_src,$path) ) ;
93                         } ;
94                         pop( @{$path} ) ;
95                 } ; 
96                 return( \%params ) ;
97         } ;
99         sub proc_tmpl_hash( $ ; $ ; $ ; $ ) ;
100                                 # declare to supress warning in recursive call
101         sub proc_tmpl_hash( $ ; $ ; $ ; $ )
102                                 # walk the hash, preprocess and
103                                 # convert to html
104         {
105                 my $tmpl_hash = shift( @_ ) ;
106                 my $page = shift( @_ ) ;
107                 my $destpage = shift( @_ ) ;
108                 my $scan = shift( @_ ) ;
109                 foreach my $key ( keys(%{$tmpl_hash}) )
110                 {
111                         unless( ref($tmpl_hash->{$key}) )
112                                                 # here we assume that
113                                                 # any reference is an
114                                                 # array and allow it to
115                                                 # fail if that's false
116                         {
117                                 $tmpl_hash->{$key} =
118                                                 IkiWiki::preprocess(
119                                                                 $page,
120                                                                 $destpage,
121                                                                 $tmpl_hash->{$key},
122                                                                 $scan ) ;
123                                 my @key_path = split( /_/, $key ) ;
124                                 $tmpl_hash->{$key} =
125                                                 IkiWiki::htmlize(
126                                                                 $page,
127                                                                 $destpage,
128                                                                 pagetype($pagesources{$page}),
129                                                                 $tmpl_hash->{$key}, )
130                                         unless( $key_path[0] eq 'raw' ) ;
131                         } else {
132                                 proc_tmpl_hash( $_, $page, $destpage, $scan )
133                                         foreach( @{$tmpl_hash->{$key}} ) ;
134                         } ;
135                 } ;
136         } ;
138         # "standard" ikiwiki definitions / hooks
140         sub import
141         {
142                 hook( type => "getsetup",
143                                 id => "template",
144                                 call => \&getsetup ) ;
145                 hook( type => "preprocess",
146                                 id => "template",
147                                 call => \&preprocess,
148                                 scan => 1 ) ;
149         } ;
151         sub getsetup()
152         {
153                 return(
154                                 plugin => {
155                                         safe => 1,
156                                         rebuild => undef,
157                                         section => "widget",
158                                 }, ) ;
159         } ;
161         sub preprocess( @ )
162         {
163         # first process arguments into arrays of values
164                 my %params ;
166                 my( $key, $value ) ;
167                 while( ($key,$value)=splice(@_,0,2) )
168                 {
169                         if( exists($params{$key}) )
170                         {
171                                 push( @{$params{$key}}, $value ) ;
172                         } else {
173                                 $params{$key} = [ $value ] ;
174                         } ;
175                 } ;
177         # set context
178                 my $scan = ! defined( wantarray() ) ;
179                                         # This needs to run even in scan
180                                         # mode, in order to process links
181                                         # and other metadata included via
182                                         # the template.
184         # check for critical values
185                 if( ! exists($params{id}) )
186                 {
187                         error( gettext("missing id parameter") ) ;
188                 } ;
190         # set some convenience variables
191                 my $id = $params{id}->[$#{$params{id}}] ;
192                 my $page = $params{page}->[$#{$params{page}}] ;
193                 my $destpage = $params{destpage}->[$#{$params{destpage}}] ;
194         # ... and an essential one for the production pass
195                 $params{basename} = [ IkiWiki::basename($page) ] ;
197         # load the template
198                 my $template ;
199                 eval {
200                         $template =
201                                         template_depends( $id, $page,
202                                                         blind_cache=>1 ) ;
203                                                 # The bare id is used, so
204                                                 # a page templates/$id can
205                                                 # be used as the template.
206                 } ;
207                 if( $@ )
208                 {
209                         error(
210                                         sprintf(
211                                                         gettext("failed to process template %s"),
212                                                         htmllink(
213                                                                         $page,
214                                                                         $destpage,
215                                                                         "/templates/$id")
216                                                         )." $@"
217                                         ) ;
218                 } ;
220         # create and process the parameters
221                 my $tmpl_hash = mktmpl_hash( $template, \%params ) ;
222                 proc_tmpl_hash( $tmpl_hash, $page, $destpage, $scan ) ;
223         # ... and load the template with the values
224                 $template->param( $tmpl_hash ) ;
226         # return the processed page chunk
227                 return( IkiWiki::preprocess($page,
228                                                 $destpage,
229                                                 $template->output(),$scan)
230                                 ) ;
231         } ;
233         1 ;
235 """]]
237 ## sample template
239         # <TMPL_VAR HEADER0>
241         <table>
242         <TMPL_LOOP TEST0>
243         <tr>
244                 <td><TMPL_VAR DATA0></td>
245                 <td><TMPL_VAR DATA1></td>
246         </tr>
247         </TMPL_LOOP>
248         </table>
250 ## sample iki page
252         \[[!meta title="this is my loops page"]]
254         \[[!template id="loops"
255         header0="this is a table"
256         data0="cell0:0"
257         data1="cell0:1"
258         data0="cell1:0"
259         data1="cell1:1"
260         ]]