gavinc/uf_hcalendar_meta

   1 # Blosxom Plugin: uf_hcalendar_meta
   2 # Author(s): Gavin Carr <gavin@openfusion.com.au>
   3 # Version: 0.001000
   4 # Documentation: 'perldoc uf_hcalendar_meta'
   5
   6 package uf_hcalendar_meta;
   7
   8 use strict;
   9
  10 # Uncomment next line to enable debug output (don't uncomment debug() lines)
  11 #use Blosxom::Debug debug_level => 1;
  12
  13 # --- Configurable variables -----
  14
  15 my %config = (
  16
  17   # Extra CSS classes to add to the microformat container e.g. to turn display off
  18   class => '',
  19   #class => 'nodisplay',
  20
  21   # Whether to automatically add microformat to story bodies. If not set,
  22   # you must explicitly add $uf_adr_meta::adr to a template somewhere.
  23   auto_append_to_body => 1,
  24
  25   # What markup style to use for your adr, if auto-appending.
  26   # 3 styles are currently defined:
  27   # 'div-span' uses a 'div' elt for the container, and 'span' elements for the fields
  28   # 'ul' uses a 'ul' list for the container, and 'li' elements for the fields
  29   # 'dl' uses a 'dl' list for the container, 'dt' elements for field names, and
  30   #    'dd' elements for the fields themselves
  31   #style => 'div-span',
  32   #style => 'ul',
  33   style => 'dl',
  34
  35 );
  36
  37 # --------------------------------
  38 # __END_CONFIG__
  39
  40 use vars qw($hcalendar);
  41
  42 my @required = qw(summary dtstart);
  43 my @optional = qw(dtend duration description location url uid);
  44 my %label = (
  45   dtstart   => 'DtStart',
  46   dtend     => 'DtEnd',
  47   uid       => 'UID',
  48   url       => 'URL',
  49 );
  50
  51 $config{style} = 'div-span' unless $config{style} eq 'ul' or $config{style} eq 'dl';
  52
  53 sub start { 1 }
  54
  55 # Return the first existing metadata item key and value given a list of keys
  56 sub _get_meta {
  57     for my $attr ( @_ ) {
  58         my $meta_attr = $attr;
  59         $meta_attr =~ s/-/_/g;
  60         my $value = $blosxom::meta{$meta_attr};
  61         $value = eval "\$meta::$attr" unless defined $value;
  62         return wantarray ? ( $attr, $value ) : $value if defined $value;
  63     }
  64     return wantarray ? () : undef;
  65 }
  66
  67 sub _format_date {
  68     my ($date) = @_;
  69     my $iso_date = $date;
  70     $iso_date =~ s/^(\d{4}-\d{2}-\d{2})(\s+)/$1T/;
  71     return $iso_date;
  72 }
  73
  74 sub _format_duration {
  75     my ($duration) = @_;
  76     my $iso_duration = uc $duration;
  77
  78     # Trim
  79     $iso_duration =~ s/^\s+//;
  80     $iso_duration =~ s/\s+$//;
  81
  82     # If $iso_duration begins with an H, M, or S element, and no P, insert PT
  83     $iso_duration =~ s/^(\d+)([HMS])/PT$1$2/;
  84
  85     # Otherwise, if $iso_duration begins without a P, insert one
  86     $iso_duration =~ s/^(\d)/P$1/;
  87
  88     # Replace date-time whitespace with 'T'
  89     $iso_duration =~ s/([PYMD])\s+/$1T/;
  90
  91     return $iso_duration;
  92 }
  93
  94 sub story {
  95     my ($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;
  96
  97     my %meta = ();
  98     for (@required, @optional) {
  99       $meta{$_} = _get_meta($_);
 100     }
 101     my @req_count = map { $meta{$_} ? 1 : () } @required;
 102     return 1 unless @req_count == @required;
 103
 104     my $story_style = _get_meta( 'hcal_style' ) || $config{style};
 105     my $ctag = $story_style eq 'div-span' ? 'div' : $story_style;
 106     my $etag = $story_style eq 'div-span' ? 'span' :
 107                $story_style eq 'ul' ? 'li' : 'dd';
 108
 109     $hcalendar = '';
 110     my $container_classes = 'vevent';
 111     if (my $meta_class = _get_meta('hcal_class')) {
 112       $container_classes .= " $meta_class";
 113     }
 114     else {
 115       $container_classes .= " $config{class}" if $config{class};
 116     }
 117     $hcalendar .= qq(<$ctag class="$container_classes">\n);
 118     for (@required, @optional) {
 119         next unless defined $meta{$_};
 120         $hcalendar .= sprintf qq(<dt>%s</dt>), $label{$_} || ucfirst $_
 121             if $story_style eq 'dl';
 122         if ($_ eq 'dtstart' || $_ eq 'dtend') {
 123             my $iso_date = _format_date($meta{$_});
 124             $hcalendar .= qq(<$etag><abbr class="$_" title="$iso_date">$meta{$_}</abbr></$etag>\n);
 125         }
 126         elsif ($_ eq 'duration') {
 127             my $iso_duration = _format_duration($meta{$_});
 128             $hcalendar .= qq(<$etag><abbr class="$_" title="$iso_duration">$meta{$_}</abbr></$etag>\n);
 129         }
 130         elsif ($_ eq 'url') {
 131             $hcalendar .= qq(<$etag><a class="$_" href="$meta{url}">$meta{url}</a></$etag>\n);
 132         }
 133         else {
 134             $hcalendar .= qq(<$etag class="$_">$meta{$_}</$etag>\n);
 135         }
 136     }
 137     $hcalendar .= qq(</$ctag>\n);
 138     # debug(1, "uf_hcalendar_meta: $hcalendar\n");
 139
 140     my $autoappend = _get_meta( 'hcal_autoappend' );
 141     $autoappend = $config{auto_append_to_body} unless defined $autoappend;
 142     return 1 unless $autoappend;
 143
 144     $$body_ref .= "\n\n$hcalendar\n\n";
 145
 146     return 1;
 147 }
 148
 149 1;
 150
 151 __END__
 152
 153 =head1 NAME
 154
 155 uf_hcalendar_meta - plugin to create an 'hcalendar' microformat tag from
 156 post metadata
 157
 158 =head1 DESCRIPTION
 159
 160 uf_hcalendar_meta is a plugin to create an 'hcalendar' microformat tag
 161 from metadata in your post. The microformat tag is created in the
 162 $uf_hcalendar_meta::hcalendar variable for use in templates or by other
 163 plugins, or if the $auto_append_to_body flag is set (it is by default),
 164 uf_hcalendar_meta will append the tag to your story body automatically.
 165
 166 =head2 REQUIRED METADATA ITEMS
 167
 168 (If using the 'metamail/metadir/metafile' plugins, metadata items
 169 are matched case insensitively.)
 170
 171 =over 4
 172
 173 =item summary
 174
 175 The summary or title of the event.
 176
 177 =item dtstart
 178
 179 The start date/time of the event.
 180
 181 Must be given as an ISO 8601 calendar date, in the form
 182 YYYY-MM-DDTHH:MM:SS or YYYYMMDDTHHMMSS, with an optional trailing
 183 timezone of the form /[+-]HH(:?MM)?/. Any number of rightmost time
 184 elements may be omitted. Hours must be given in 24-hour time.
 185
 186 For convenience, this plugin allows the 'T' marker to be replaced by
 187 whitespace.
 188
 189 The following are all valid dtstart values, for example:
 190
 191 =over 4
 192
 193 =item 2007-09-01T19:30:00+10:00
 194
 195 =item 20070901T193000-10
 196
 197 =item 2007-09-01
 198
 199 =item 2007-09-01 17:45
 200
 201 =back
 202
 203 =back
 204
 205 And one of:
 206
 207 =over 4
 208
 209 =item dtend
 210
 211 The end date/time of the event. Must be an ISO 8601 calendar date
 212 as defined for dtstart above.
 213
 214 =item duration
 215
 216 The duration of the event. This may be an ISO 8601 duration, of the
 217 form PnnYnnMnnDTnnHnnMnnS e.g. "P3Y6M4DT12H30M0S". Elements may be
 218 omitted if their duration is zero. The smallest value used may also
 219 have a decimal fraction, as in "P0.5Y" to indicate half a year.
 220
 221 For convenience, this plugin interprets the units case-insensitively,
 222 allows the 'P' and 'T' markers to be omitted, and also accepts
 223 whitespace in the place of the 'T' time marker.
 224
 225 Note that because months and minutes use the same signifier, there is
 226 ambiguity about the meaning of 'P1M' and '1M'. This plugin interprets
 227 'M' values as follows:
 228
 229 =over 4
 230
 231 =item 1M
 232
 233 Interpreted as minutes, since this is the most common use case, and
 234 since ISO 8601 really requires a leading 'P' signifier.
 235
 236 =item P1M
 237
 238 Interpreted as months, following ISO 8601.
 239
 240 =item PT1M
 241
 242 Interpreted as minutes, following ISO 8601.
 243
 244 =back
 245
 246 =back
 247
 248
 249 =head2 OPTIONAL METADATA ITEMS
 250
 251 =over 4
 252
 253 =item description
 254
 255 A description of the event, sometimes longer than the summary.
 256
 257 =item dtend
 258
 259 The end date/time of the event, as discussed above.
 260
 261 =item duration
 262
 263 The duration of the event, as discussed above.
 264
 265 =item location
 266
 267 A string describing the location of the event.
 268
 269 =item url
 270
 271 A canonical URL for the event.
 272
 273 =item uid
 274
 275 A unique identifier for this event. Apparently required by some
 276 versions of Microsoft Outlook.
 277
 278 =back
 279
 280 =head2 Config Elements
 281
 282 uf_hcalendar_meta also supports a couple of config elements that can be used to
 283 override plugin config data on a per-story basis:
 284
 285 =over 4
 286
 287 =item HCal-Class (metamail) / hcal_class (meta)
 288
 289 This class (or list of classes) is appended to the class list applied to the
 290 top-level hcalendar element in the rendered hcalendar i.e. it overrides the
 291 'class' config variable.
 292
 293 =item HCal-Autoappend (metamail) / hcal_autoappend (meta)
 294
 295 This is a flag (0 or 1) indicating whether the rendered hcalendar should be
 296 automatically appended to the story body. It overrides the 'auto_append_to_body'
 297 config variable.
 298
 299 =item HCal-Style (metamail) / hcal_style (meta)
 300
 301 One of the following styles: 'div-span', 'ul', 'dl', used to render the hcalendar.
 302 It overrides the 'style' config variable.
 303
 304 =back
 305
 306 =head1 USAGE
 307
 308 uf_hcalendar_meta should be loaded after the meta plugins (meta
 309 itself, or the metaclear/metamail/metadir/metafile family).
 310
 311 =head1 SEE ALSO
 312
 313 Microformats.org: http://www.microformats.org/,
 314 http://microformats.org/wiki/hcalendar.
 315
 316 Blosxom: http://blosxom.sourceforge.net/
 317
 318 =head1 BUGS
 319
 320 Only the most common hcalendar attributes have been implemented
 321 so far. Please let me know if you'd like something not available
 322 yet.
 323
 324 =head1 AUTHOR
 325
 326 Gavin Carr <gavin@openfusion.com.au>, http://www.openfusion.net/
 327
 328 =head1 LICENSE
 329
 330 Copyright 2007, Gavin Carr.
 331
 332 This plugin is licensed under the same terms as blosxom itself i.e.
 333
 334 Permission is hereby granted, free of charge, to any person obtaining a
 335 copy of this software and associated documentation files (the "Software"),
 336 to deal in the Software without restriction, including without limitation
 337 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 338 and/or sell copies of the Software, and to permit persons to whom the
 339 Software is furnished to do so, subject to the following conditions:
 340
 341 The above copyright notice and this permission notice shall be included
 342 in all copies or substantial portions of the Software.
 343
 344 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 345 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 346 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 347 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 348 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 349 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 350 OTHER DEALINGS IN THE SOFTWARE.
 351
 352 =cut
 353
 354 # vim:ft=perl