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 =head1 SEE ALSO
 183
 184 Blosxom Home/Docs/Licensing:
 185   http://blosxom.sourceforge.net/
 186
 187 Blosxom Plugin User Documentation:
 188   http://blosxom.sourceforge.net/documentation/users/plugins.html
 189
 190 Blosxom Plugin Developer Documentation:
 191   http://blosxom.sourceforge.net/documentation/developers/plugins.html
 192
 193 =head1 BUGS
 194
 195 Address bug reports and comments to the Blosxom mailing list
 196 [http://www.yahoogroups.com/group/blosxom].
 197
 198 =head1 LICENSE
 199
 200 Blosxom and this Blosxom Plug-in
 201 Copyright 2003, Rael Dornfest
 202
 203 Permission is hereby granted, free of charge, to any person obtaining a
 204 copy of this software and associated documentation files (the "Software"),
 205 to deal in the Software without restriction, including without limitation
 206 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 207 and/or sell copies of the Software, and to permit persons to whom the
 208 Software is furnished to do so, subject to the following conditions:
 209
 210 The above copyright notice and this permission notice shall be included
 211 in all copies or substantial portions of the Software.
 212
 213 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 214 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 215 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 216 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 217 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 218 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 219 OTHER DEALINGS IN THE SOFTWARE.