1 # Blosxom Plugin: mason_blocks
2 # Author(s): Gavin Carr <gavin@openfusion.com.au>
9 # --- Configurable variables -----
14 # --------------------------------
19 my($pkg, $currentdir, $head_ref) = @_;
20 munge_blocks($head_ref);
25 my ($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;
26 munge_blocks($story_ref);
31 my($pkg, $currentdir, $foot_ref) = @_;
32 munge_blocks($foot_ref);
37 my ($flavour_ref) = @_;
40 my ($doc, @if, @else, @if_blocks, @else_blocks);
41 @if = @else = @if_blocks = @else_blocks = ();
42 for (split /\n/, $$flavour_ref) {
43 # Ignore lines beginning with '%#'
46 # Ignore if in doc block <%doc> .... </%doc> (at beginning of lines)
47 if (m!^</%doc>! && $doc) {
52 } elsif (m!^<%doc>!) {
57 # Minimalist version - if, } else {, } only, nesting supported
60 $if =~ s/^%\s*if\s*//;
62 # New block, record condition, and add new entries to other arrays
66 push @else_blocks, [];
69 elsif (m/^%\s*\}\s*else\s*\{/) {
70 # Else at same level - set current else flag to true
75 # End of block - pull latest entries from all arrays
78 my $if_block = pop @if_blocks;
79 my $else_block = pop @else_blocks;
80 warn "end_block: if '$if', if block " .
81 scalar(@$if_block) . " lines, else block " .
82 scalar(@$else_block) . " lines\n"
84 # Check condition, and replace current line with appropriate flattened block
86 $_ = join "\n", @$if_block;
88 $_ = join "\n", @$else_block;
92 # Regular line - add to @else_blocks, @if_blocks, or @flavour
93 if (@else && $else[$#else]) {
94 push @{$else_blocks[$#else_blocks]}, $_;
97 push @{$if_blocks[$#if_blocks]}, $_;
104 # Join flavour lines and update $$flavour_ref
105 $$flavour_ref = join "\n", @flavour;
107 # Support mason-style end-of-line newline escapes
108 $$flavour_ref =~ s/\\\r?\n//g;
117 mason_blocks - blosxom plugin to support simple mason-style if-blocks
118 in blosxom flavours/templates
122 # In a flavour or template file ...
124 # Mason-style conditionals
125 % if ($pagetype::pagetype ne 'story') {
126 <a href="$permalink::story#comments">Comments ($feedback::count) »</a>
128 <a href="$permalink::story#leave_comment">Leave a comment »</a>
131 # Mason-style comments
132 %# Only show a comments section if there are comments
133 % if ($feedback::count > 0) {
137 # Mason-style block comments
140 multi-line, extremely important
144 # Mason-style newline escaping, if last character on line is a backslash e.g.
148 # is rendered as: <p>Foo bar</p>
153 mason_blocks is a blosxom plugin implementing simple conditional and
154 commment blocks using mason-style syntax (as in the HTML::Mason perl
155 templating system), for use in blosxom flavour and template files.
159 mason_blocks supports simple if and if-else blocks using lines beginning
160 with the '%' character (which must be the first character on the line)
163 % if ($pagetype::pagetype eq 'story') {
164 <a href="$permalink::story#leave_comment">Leave a comment »</a>
169 % if ($pagetype::pagetype ne 'story') {
170 <a href="$permalink::story#comments">Comments ($feedback::count) »</a>
172 <a href="$permalink::story#leave_comment">Leave a comment »</a>
175 Whitespace is not significant, but braces are required and should match,
176 just as in perl. The if-conditions can comprise any valid perl condition.
180 Two comment styles are also supported. Single line comments must begin with
181 a '%' character, followed by optional whitespace, follwed by a '#' character,
182 and continue only to the end of the line e.g.
184 %# This is a completely profound and illuminating comment
187 Block comments must begin with a <%doc> token (at the beginning of a line)
188 and end with a </%doc> token (also at the beginning of a line). All text
189 between these two tokens is treated as a comment and not included in output.
193 More enlightening profundities from your template author
194 Explaining why this stuff is as ugly as it is ...
197 Block comments cannot be nested.
199 =head2 NEWLINE ESCAPING
201 mason_blocks also supports mason-style newline escaping i.e. if the last
202 character on a line is a backslash, mason_blocks escapes the line break,
203 deleting both the backslash and the following newline character(s). This
204 is useful in conjunction with conditionals where you'd prefer the
205 conditional content to appear inline within the enclosing content e.g.
207 <a href="$permalink::story#comments">\
208 % if ($feedback::count == 0) {
213 would be rendered as:
215 <a href="$permalink::story#comments">No Comments »</a>
217 This is not just a prettiness issue - some browsers treat embedded
218 whitespace (including newlines) as significant, even when they
221 =head2 VS. INTERPOLATE_FANCY
223 mason_blocks was initially born out of my frustration with older versions
224 of interpolate_fancy not supporting nested constructs properly (though I'd
225 also been frustrated with the syntax and the limits on the conditionals
228 I thought for an experiment I'd see how hard simple non-nested
229 conditionals using a mason-style syntax would be, and it turned out to be
230 not very difficult at all. I no longer use interpolate_fancy at all - my
231 limited use cases seem better met using mason_blocks.
233 As I see it, mason_blocks has the following advantages over
238 =item Nesting support
240 Earlier versions of interpolate_fancy had problems with nested
241 constructs. I believe that this has been fixed in the later versions
242 updated by Matthijs Kooijman (>= version 20060111).
244 mason_blocks fully supports nested conditionals.
246 =item If-Else Constructs
248 mason_blocks supports simple if-else blocks, instead of making you
249 use 'if x eq 1; if x ne 1' pairs. It does not currently support
252 =item Full perl conditions
254 mason_blocks allows you to use full perl conditions (including composite
255 conditions) instead of being limited to simple conditions using only the
256 most common operators. For instance, all of the following require hoop
257 jumping with interpolate_fancy:
263 =item if (substr($foo, 3, 1) eq 'X')
265 =item if ($pagetype::pagetype eq 'story' && $feedback::comments > 0)
271 mason_blocks does not provide any of interpolate_fancy's interpolation
272 or action functionality, however.
277 mason_blocks should probably be loaded relatively late, since you'll
278 often want to use various plugin package variables in your conditionals.
280 It uses the 'head', 'story', and 'footer' hooks, rather than 'interpolate',
281 so it should be able to be used alongside any of the interpolate plugins
287 HTML::Mason, for the block syntax (the module is not used or required by
288 this plugin, however).
290 Blosxom: http://blosxom.sourceforge.net/
295 Please report bugs either directly to the author or to the blosxom
296 development mailing list: <blosxom-devel@lists.sourceforge.net>.
306 Gavin Carr <gavin@openfusion.com.au>, http://www.openfusion.net/
310 Copyright 2007, Gavin Carr.
312 This plugin is licensed under the same terms as blosxom itself i.e.
314 Permission is hereby granted, free of charge, to any person obtaining a
315 copy of this software and associated documentation files (the "Software"),
316 to deal in the Software without restriction, including without limitation
317 the rights to use, copy, modify, merge, publish, distribute, sublicense,
318 and/or sell copies of the Software, and to permit persons to whom the
319 Software is furnished to do so, subject to the following conditions:
321 The above copyright notice and this permission notice shall be included
322 in all copies or substantial portions of the Software.
324 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
325 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
326 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
327 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
328 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
329 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
330 OTHER DEALINGS IN THE SOFTWARE.