1 # Blosxom Plugin: mason_blocks
2 # Author(s): Gavin Carr <gavin@openfusion.com.au>
9 #use Blosxom::Debug debug_level => 1;
11 # --- Configurable variables -----
15 # --------------------------------
20 my($pkg, $currentdir, $head_ref) = @_;
21 munge_blocks($head_ref);
26 my ($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;
27 munge_blocks($story_ref);
32 my($pkg, $currentdir, $foot_ref) = @_;
33 munge_blocks($foot_ref);
38 my ($flavour_ref) = @_;
41 my ($doc, @if, @else, @if_blocks, @else_blocks);
42 @if = @else = @if_blocks = @else_blocks = ();
43 for (split /\n/, $$flavour_ref) {
44 # Ignore lines beginning with '%#'
47 # Ignore if in doc block <%doc> .... </%doc> (at beginning of lines)
48 if (m!^</%doc>! && $doc) {
53 } elsif (m!^<%doc>!) {
58 # Minimalist version - if, } else {, } only, nesting supported
61 $if =~ s/^%\s*if\s*//;
63 # New block, record condition, and add new entries to other arrays
67 push @else_blocks, [];
70 elsif (m/^%\s*\}\s*else\s*\{/) {
71 # Else at same level - set current else flag to true
76 # End of block - pull latest entries from all arrays
79 my $if_block = pop @if_blocks;
80 my $else_block = pop @else_blocks;
81 # debug(1, "end_block: if '$if', if block " . scalar(@$if_block) . " lines, else block " . scalar(@$else_block) . " lines\n");
82 # Check condition, and replace current line with appropriate flattened block
84 $_ = join "\n", @$if_block;
86 $_ = join "\n", @$else_block;
90 # Regular line - add to @else_blocks, @if_blocks, or @flavour
91 if (@else && $else[$#else]) {
92 push @{$else_blocks[$#else_blocks]}, $_;
95 push @{$if_blocks[$#if_blocks]}, $_;
102 # Join flavour lines and update $$flavour_ref
103 $$flavour_ref = join "\n", @flavour;
105 # Support mason-style end-of-line newline escapes
106 $$flavour_ref =~ s/\\\r?\n//g;
115 mason_blocks - blosxom plugin to support simple mason-style if-blocks
116 in blosxom flavours/templates
120 # In a flavour or template file ...
122 # Mason-style conditionals
123 % if ($pagetype::pagetype ne 'story') {
124 <a href="$permalink::story#comments">Comments ($feedback::count) »</a>
126 <a href="$permalink::story#leave_comment">Leave a comment »</a>
129 # Mason-style comments
130 %# Only show a comments section if there are comments
131 % if ($feedback::count > 0) {
135 # Mason-style block comments
138 multi-line, extremely important
145 mason_blocks is a blosxom plugin implementing simple conditional and
146 commment blocks using mason-style syntax (as in the HTML::Mason perl
147 templating system), for use in blosxom flavour and template files.
151 mason_blocks supports simple if and if-else blocks using lines beginning
152 with the '%' character (which must be the first character on the line)
155 % if ($pagetype::pagetype eq 'story') {
156 <a href="$permalink::story#leave_comment">Leave a comment »</a>
161 % if ($pagetype::pagetype ne 'story') {
162 <a href="$permalink::story#comments">Comments ($feedback::count) »</a>
164 <a href="$permalink::story#leave_comment">Leave a comment »</a>
167 Whitespace is not significant, but braces are required and should match,
168 just as in perl. The if-conditions can comprise any valid perl condition.
172 Two comment styles are also supported. Single line comments must begin with
173 a '%' character, followed by optional whitespace, follwed by a '#' character,
174 and continue only to the end of the line e.g.
176 %# This is a completely profound and illuminating comment
179 Block comments must begin with a <%doc> token (at the beginning of a line)
180 and end with a </%doc> token (also at the beginning of a line). All text
181 between these two tokens is treated as a comment and not included in output.
185 More enlightening profundities from your template author
186 Explaining why this stuff is as ugly as it is ...
189 Block comments cannot be nested.
191 =head2 VS. INTERPOLATE_FANCY
193 mason_blocks was initially born out of my frustration with older versions
194 of interpolate_fancy not supporting nested constructs properly (though I'd
195 also been frustrated with the syntax and the limits on the conditionals
198 I thought for an experiment I'd see how hard simple non-nested
199 conditionals using a mason-style syntax would be, and it turned out to be
200 not very difficult at all. I no longer use interpolate_fancy at all - my
201 limited use cases seem better met using mason_blocks.
203 As I see it, mason_blocks has the following advantages over
208 =item Nesting support
210 Earlier versions of interpolate_fancy had problems with nested
211 constructs. I believe that this has been fixed in the later versions
212 updated by Matthijs Kooijman (>= version 20060111).
214 mason_blocks fully supports nested conditionals.
216 =item If-Else Constructs
218 mason_blocks supports simple if-else blocks, instead of making you
219 use 'if x eq 1; if x ne 1' pairs. It does not currently support
222 =item Full perl conditions
224 mason_blocks allows you to use full perl conditions (including composite
225 conditions) instead of being limited to simple conditions using only the
226 most common operators. For instance, all of the following require hoop
227 jumping with interpolate_fancy:
233 =item if (substr($foo, 3, 1) eq 'X')
235 =item if ($pagetype::pagetype eq 'story' && $feedback::comments > 0)
241 mason_blocks does not provide any of interpolate_fancy's interpolation
242 or action functionality, however.
247 mason_blocks should probably be loaded relatively late, since you'll
248 often want to use various plugin package variables in your conditionals.
250 It uses the 'head', 'story', and 'footer' hooks, rather than 'interpolate',
251 so it should be able to be used alongside any of the interpolate plugins
257 HTML::Mason, for the block syntax (the module is not used or required by
258 this plugin, however).
260 Blosxom: http://blosxom.sourceforge.net/
265 Please report bugs either directly to the author or to the blosxom
266 development mailing list: <blosxom-devel@lists.sourceforge.net>.
276 Gavin Carr <gavin@openfusion.com.au>, http://www.openfusion.net/
280 Copyright 2007, Gavin Carr.
282 This plugin is licensed under the same terms as blosxom itself i.e.
284 Permission is hereby granted, free of charge, to any person obtaining a
285 copy of this software and associated documentation files (the "Software"),
286 to deal in the Software without restriction, including without limitation
287 the rights to use, copy, modify, merge, publish, distribute, sublicense,
288 and/or sell copies of the Software, and to permit persons to whom the
289 Software is furnished to do so, subject to the following conditions:
291 The above copyright notice and this permission notice shall be included
292 in all copies or substantial portions of the Software.
294 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
295 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
296 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
297 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
298 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
299 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
300 OTHER DEALINGS IN THE SOFTWARE.