Add entries_cache_meta to general.
[matthijs/upstream/blosxom-plugins.git] / general / theme
1 # Blosxom Plugin: theme
2 # Author(s): Rael Dornfest <rael@oreilly.com> 
3 # Version: 2003-08-26
4 # Documentation: See the bottom of this file or type: perldoc theme
5
6 package theme;
7
8 # --- Configurable variables -----
9
10 # Where do your themes live?
11 my $theme_dir = "$blosxom::datadir/themes";
12
13 # What's the URL of your themes directory?
14 # This is vital for those themes that employ images, stylesheets, or other
15 # external content pulled in from outside the page itself.
16 $theme_dir_url = "$blosxom::url/themes";
17
18 # Should I fall back to the blosxom template system, looking in $datadir
19 # and paths beyond for template components?
20 # 0 = no; 1 = yes (default)
21 my $fallback_to_templates = 1;
22
23 # --------------------------------
24
25 use FileHandle;
26 my $fh = new FileHandle;
27
28 my $cache = {};
29
30 sub start {
31   return -r $theme_dir ? 1 : 0;
32 }
33
34 sub template {
35   return sub {
36     my ($path, $chunk, $flavour) = @_;
37
38     $path =~ s!^/*!!; $path = "/$path";
39
40     # Return cached chunk, if available
41     $cache->{$flavour}->{$chunk} and return $cache->{$flavour}->{$chunk};
42
43     # Glean, spindle, and cache the theme
44     if (!keys %{$cache->{$flavour}} and $fh->open("$theme_dir/$flavour/page")) {
45       my $in_chunk = '';
46       while (my $line = <$fh>) {
47         $line =~ /<!--\s*blosxom\s+(\w+)(?:\s+(.*)\b)?\s*-->/;
48         $1 and $2 and $cache->{$flavour}->{$1} = $2 and next;
49         $1 and $in_chunk = $1 and next;
50         $cache->{$flavour}->{$in_chunk} .= $line;
51       }
52
53       # Return the requested chunk
54       $cache->{$flavour}->{$chunk} and return $cache->{$flavour}->{$chunk};
55     }
56
57     # Fall back to standard blosxom templating (if $fallback_to_templates)
58     $fallback_to_templates and do {
59       $blosxom::others{"$blosxom::datadir$path/$chunk.$flavour"} and 
60         $fh->open("< $blosxom::datadir$path/$chunk.$flavour") and 
61           return join '', <$fh>;
62     } while ($path =~ s/(\/*[^\/]*)$// and $1);
63
64     # Finally, fall back to baked-in basic flavours
65     return join '', ($blosxom::template{$flavour}{$chunk} || $blosxom::template{error}{$chunk} || '');
66
67   };
68 }
69   
70 1;
71
72 __END__
73
74 =head1 NAME
75
76 Blosxom Plug-in: theme
77
78 =head1 SYNOPSIS
79
80 Build themes or use those built by others for your Blosxom-powered weblog.
81 Themes consist of a directory named for your theme (e.g. "yellowish") 
82 containing a single template file ("page") and any supporting images,
83 stylesheets, javascript source, etc.  A typical theme directory structure
84 looks something like:
85
86 $theme_dir
87           /page
88           /images
89                  /background.gif
90                  /logo.gif
91           /javascript
92                  /util.js
93
94 The only bit that's required is that "page" file.
95
96 The "page" file should define a content type, head, date, story, 
97 and foot --just as with Blosxom's default flavour template system
98 [http://blosxom.sourceforge.net/documentation/users/flavour.html], except all
99 in a single file rather than individual flavour files.  Components are
100 deliniated using <!-- blosxom componentname --> comments.  
101
102 Here's a sample (over-simplified) page definition:
103
104   <!-- blosxom content_type text/html -->
105
106   <!-- blosxom head -->
107    <html>
108     <head>
109      <title>my blosxom blog</title>
110     </head>
111     <body>
112     <h1>my blosxom blog</h1>
113
114   <!-- blosxom date -->
115    <p><b>$dw, $da $mo $yr</b></p>
116
117   <!-- blosxom story -->
118    <p>
119    <a name="$fn"><b>$title</b></a>
120    <br />
121    $body
122    <br />
123    <a href="$url$path/$fn.$default_flavour">permanent link</a>
124    </p>
125
126   <!-- blosxom foot -->
127     </body>
128    </html>
129
130 Everything after a <!-- blosxom componentname --> comment (until the
131 next one) is part of the component.  Notice the only exception is the
132 content_type component, the content type for the document being defined
133 in the comment itself; this is to assure only a single line is used for
134 content type.
135
136 The theme plugin overrides Blosxom's default template() subroutine, 
137 falling back to Blosxom's default flavour template system if the
138 requested theme is not available.  It falls further back to Blosxom's
139 baked in default HTML and RSS flavours if no theme or flavour
140 templates are available for the requested theme/flavour.
141
142 =head1 INSTALLATION 
143
144 Drop the theme plugin into your Blosxom plugins folder.
145
146 =head1 CONFIGURATION
147
148 The plugin is preconfigured to assume a themes directory beneath your 
149 Blosxom data directory ($datadir, as configured in the blosxom.cgi script).  
150 Alter the $theme_dir configurable variable to have your themes live elsewhere.
151
152 e.g. 
153   # Where do your themes live?
154   my $theme_dir = "/somewhere/else/themes";
155
156 Wherever it lives, your themes directory should be Web-accessible since
157 themes may (and probably do) employ images, stylesheets, and other 
158 content pulled in from outside the page itself.
159
160 e.g. 
161   # What's the URL of your themes directory?
162   my $theme_dir_url = "http://example.com/somewhere/else/themes";
163
164 By default, the theme plugin falls back to Blosxom's built-in flavour 
165 template system [http://blosxom.sourceforge.net/documentation/users/flavour.html].
166 You can turn this off by setting the $fallback_to_templates variable to 0.
167
168 e.g. 
169   # Should I fall back to the blosxom template system, looking in $datadir
170   # and paths beyond for template components?
171   # 0 = no; 1 = yes (default)
172   my $fallback_to_templates = 0;
173
174 =head1 VERSION
175
176 2003-08-26
177
178 =head1 AUTHOR
179
180 Rael Dornfest <rael@oreilly.com>, http://www.raelity.org/
181
182 This plugin is now maintained by the Blosxom Sourceforge Team,
183 <blosxom-devel@lists.sourceforge.net>.
184
185 =head1 SEE ALSO
186
187 Blosxom Home/Docs/Licensing: 
188   http://blosxom.sourceforge.net/
189
190 Blosxom Plugin User Documentation:
191   http://blosxom.sourceforge.net/documentation/users/plugins.html
192
193 Blosxom Plugin Developer Documentation: 
194   http://blosxom.sourceforge.net/documentation/developers/plugins.html
195
196 =head1 BUGS
197
198 None known; please send bug reports and feedback to the Blosxom
199 development mailing list <blosxom-devel@lists.sourceforge.net>.
200
201 =head1 LICENSE
202
203 Blosxom and this Blosxom Plug-in
204 Copyright 2003, Rael Dornfest 
205
206 Permission is hereby granted, free of charge, to any person obtaining a
207 copy of this software and associated documentation files (the "Software"),
208 to deal in the Software without restriction, including without limitation
209 the rights to use, copy, modify, merge, publish, distribute, sublicense,
210 and/or sell copies of the Software, and to permit persons to whom the
211 Software is furnished to do so, subject to the following conditions:
212
213 The above copyright notice and this permission notice shall be included
214 in all copies or substantial portions of the Software.
215
216 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
217 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
218 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
219 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
220 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
221 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
222 OTHER DEALINGS IN THE SOFTWARE.