1 # Blosxom Plugin: uf_hcalendar_meta
2 # Author(s): Gavin Carr <gavin@openfusion.com.au>
4 # Documentation: 'perldoc uf_hcalendar_meta'
6 package uf_hcalendar_meta;
10 # Uncomment next line to enable debug output (don't uncomment debug() lines)
11 #use Blosxom::Debug debug_level => 1;
13 # --- Configurable variables -----
17 # Extra CSS classes to add to the microformat container e.g. to turn display off
19 #class => 'nodisplay',
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,
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
37 # --------------------------------
39 use vars qw($hcalendar);
41 my @required = qw(summary dtstart);
42 my @optional = qw(dtend duration description location url uid);
50 $config{style} = 'div-span' unless $config{style} eq 'ul' or $config{style} eq 'dl';
54 # Return the first existing metadata item key and value given a list of keys
57 my $meta_attr = $attr;
58 $meta_attr =~ s/-/_/g;
59 my $value = $blosxom::meta{$meta_attr};
60 $value = eval "\$meta::$attr" unless defined $value;
61 return wantarray ? ( $attr, $value ) : $value if defined $value;
63 return wantarray ? () : undef;
69 $iso_date =~ s/^(\d{4}-\d{2}-\d{2})(\s+)/$1T/;
73 sub _format_duration {
75 my $iso_duration = uc $duration;
78 $iso_duration =~ s/^\s+//;
79 $iso_duration =~ s/\s+$//;
81 # If $iso_duration begins with an H, M, or S element, and no P, insert PT
82 $iso_duration =~ s/^(\d+)([HMS])/PT$1$2/;
84 # Otherwise, if $iso_duration begins without a P, insert one
85 $iso_duration =~ s/^(\d)/P$1/;
87 # Replace date-time whitespace with 'T'
88 $iso_duration =~ s/([PYMD])\s+/$1T/;
94 my ($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;
97 for (@required, @optional) {
98 $meta{$_} = _get_meta($_);
100 my @req_count = map { $meta{$_} ? 1 : () } @required;
101 return 1 unless @req_count == @required;
103 my $story_style = _get_meta( 'hcal_style' ) || $config{style};
104 my $ctag = $story_style eq 'div-span' ? 'div' : $story_style;
105 my $etag = $story_style eq 'div-span' ? 'span' :
106 $story_style eq 'ul' ? 'li' : 'dd';
109 my $container_classes = 'vevent';
110 if (my $meta_class = _get_meta('hcal_class')) {
111 $container_classes .= " $meta_class";
114 $container_classes .= " $config{class}" if $config{class};
116 $hcalendar .= qq(<$ctag class="$container_classes">\n);
117 for (@required, @optional) {
118 next unless defined $meta{$_};
119 $hcalendar .= sprintf qq(<dt>%s</dt>), $label{$_} || ucfirst $_
120 if $story_style eq 'dl';
121 if ($_ eq 'dtstart' || $_ eq 'dtend') {
122 my $iso_date = _format_date($meta{$_});
123 $hcalendar .= qq(<$etag><abbr class="$_" title="$iso_date">$meta{$_}</abbr></$etag>\n);
125 elsif ($_ eq 'duration') {
126 my $iso_duration = _format_duration($meta{$_});
127 $hcalendar .= qq(<$etag><abbr class="$_" title="$iso_duration">$meta{$_}</abbr></$etag>\n);
129 elsif ($_ eq 'url') {
130 $hcalendar .= qq(<$etag><a class="$_" href="$meta{url}">$meta{url}</a></$etag>\n);
133 $hcalendar .= qq(<$etag class="$_">$meta{$_}</$etag>\n);
136 $hcalendar .= qq(</$ctag>\n);
137 # debug(1, "uf_hcalendar_meta: $hcalendar\n");
139 my $autoappend = _get_meta( 'hcal_autoappend' );
140 $autoappend = $config{auto_append_to_body} unless defined $autoappend;
141 return 1 unless $autoappend;
143 $$body_ref .= "\n\n$hcalendar\n\n";
154 uf_hcalendar_meta - plugin to create an 'hcalendar' microformat tag from
159 uf_hcalendar_meta is a plugin to create an 'hcalendar' microformat tag
160 from metadata in your post. The microformat tag is created in the
161 $uf_hcalendar_meta::hcalendar variable for use in templates or by other
162 plugins, or if the $auto_append_to_body flag is set (it is by default),
163 uf_hcalendar_meta will append the tag to your story body automatically.
165 =head2 REQUIRED METADATA ITEMS
167 (If using the 'metamail/metadir/metafile' plugins, metadata items
168 are matched case insensitively.)
174 The summary or title of the event.
178 The start date/time of the event.
180 Must be given as an ISO 8601 calendar date, in the form
181 YYYY-MM-DDTHH:MM:SS or YYYYMMDDTHHMMSS, with an optional trailing
182 timezone of the form /[+-]HH(:?MM)?/. Any number of rightmost time
183 elements may be omitted. Hours must be given in 24-hour time.
185 For convenience, this plugin allows the 'T' marker to be replaced by
188 The following are all valid dtstart values, for example:
192 =item 2007-09-01T19:30:00+10:00
194 =item 20070901T193000-10
198 =item 2007-09-01 17:45
210 The end date/time of the event. Must be an ISO 8601 calendar date
211 as defined for dtstart above.
215 The duration of the event. This may be an ISO 8601 duration, of the
216 form PnnYnnMnnDTnnHnnMnnS e.g. "P3Y6M4DT12H30M0S". Elements may be
217 omitted if their duration is zero. The smallest value used may also
218 have a decimal fraction, as in "P0.5Y" to indicate half a year.
220 For convenience, this plugin interprets the units case-insensitively,
221 allows the 'P' and 'T' markers to be omitted, and also accepts
222 whitespace in the place of the 'T' time marker.
224 Note that because months and minutes use the same signifier, there is
225 ambiguity about the meaning of 'P1M' and '1M'. This plugin interprets
226 'M' values as follows:
232 Interpreted as minutes, since this is the most common use case, and
233 since ISO 8601 really requires a leading 'P' signifier.
237 Interpreted as months, following ISO 8601.
241 Interpreted as minutes, following ISO 8601.
248 =head2 OPTIONAL METADATA ITEMS
254 A description of the event, sometimes longer than the summary.
258 The end date/time of the event, as discussed above.
262 The duration of the event, as discussed above.
266 A string describing the location of the event.
270 A canonical URL for the event.
274 A unique identifier for this event. Apparently required by some
275 versions of Microsoft Outlook.
279 =head2 Config Elements
281 uf_hcalendar_meta also supports a couple of config elements that can be used to
282 override plugin config data on a per-story basis:
286 =item HCal-Class (metamail) / hcal_class (meta)
288 This class (or list of classes) is appended to the class list applied to the
289 top-level hcalendar element in the rendered hcalendar i.e. it overrides the
290 'class' config variable.
292 =item HCal-Autoappend (metamail) / hcal_autoappend (meta)
294 This is a flag (0 or 1) indicating whether the rendered hcalendar should be
295 automatically appended to the story body. It overrides the 'auto_append_to_body'
298 =item HCal-Style (metamail) / hcal_style (meta)
300 One of the following styles: 'div-span', 'ul', 'dl', used to render the hcalendar.
301 It overrides the 'style' config variable.
307 uf_hcalendar_meta should be loaded after the meta plugins (meta
308 itself, or the metaclear/metamail/metadir/metafile family).
312 Microformats.org: http://www.microformats.org/,
313 http://microformats.org/wiki/hcalendar.
315 Blosxom: http://blosxom.sourceforge.net/
319 Only the most common hcalendar attributes have been implemented
320 so far. Please let me know if you'd like something not available
325 Gavin Carr <gavin@openfusion.com.au>, http://www.openfusion.net/
329 Copyright 2007, Gavin Carr.
331 This plugin is licensed under the same terms as blosxom itself i.e.
333 Permission is hereby granted, free of charge, to any person obtaining a
334 copy of this software and associated documentation files (the "Software"),
335 to deal in the Software without restriction, including without limitation
336 the rights to use, copy, modify, merge, publish, distribute, sublicense,
337 and/or sell copies of the Software, and to permit persons to whom the
338 Software is furnished to do so, subject to the following conditions:
340 The above copyright notice and this permission notice shall be included
341 in all copies or substantial portions of the Software.
343 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
344 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
345 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
346 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
347 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
348 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
349 OTHER DEALINGS IN THE SOFTWARE.