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 #$config{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 $config{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
31 #$config{style} = 'div-span';
32 #$config{style} = 'ul';
33 $config{style} = 'dl';
35 # --------------------------------
38 use vars qw($hcalendar);
40 my @required = qw(summary dtstart);
41 my @optional = qw(dtend duration description location url uid);
49 $config{style} = 'div-span' unless $config{style} eq 'ul' or $config{style} eq 'dl';
53 # Return the first existing metadata item key and value given a list of keys
56 my $meta_attr = $attr;
57 $meta_attr =~ s/-/_/g;
58 my $value = $blosxom::meta{$meta_attr};
59 $value = eval "\$meta::$attr" unless defined $value;
60 return wantarray ? ( $attr, $value ) : $value if defined $value;
62 return wantarray ? () : undef;
68 $iso_date =~ s/^(\d{4}-\d{2}-\d{2})(\s+)/$1T/;
72 sub _format_duration {
74 my $iso_duration = uc $duration;
77 $iso_duration =~ s/^\s+//;
78 $iso_duration =~ s/\s+$//;
80 # If $iso_duration begins with an H, M, or S element, and no P, insert PT
81 $iso_duration =~ s/^(\d+)([HMS])/PT$1$2/;
83 # Otherwise, if $iso_duration begins without a P, insert one
84 $iso_duration =~ s/^(\d)/P$1/;
86 # Replace date-time whitespace with 'T'
87 $iso_duration =~ s/([PYMD])\s+/$1T/;
93 my ($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;
96 for (@required, @optional) {
97 $meta{$_} = _get_meta($_);
99 my @req_count = map { $meta{$_} ? 1 : () } @required;
100 return 1 unless @req_count == @required;
102 my $story_style = _get_meta( 'hcal_style' ) || $config{style};
103 my $ctag = $story_style eq 'div-span' ? 'div' : $story_style;
104 my $etag = $story_style eq 'div-span' ? 'span' :
105 $story_style eq 'ul' ? 'li' : 'dd';
108 my $container_classes = 'vevent';
109 if (my $meta_class = _get_meta('hcal_class')) {
110 $container_classes .= " $meta_class";
113 $container_classes .= " $config{class}" if $config{class};
115 $hcalendar .= qq(<$ctag class="$container_classes">\n);
116 for (@required, @optional) {
117 next unless defined $meta{$_};
118 $hcalendar .= sprintf qq(<dt>%s</dt>), $label{$_} || ucfirst $_
119 if $story_style eq 'dl';
120 if ($_ eq 'dtstart' || $_ eq 'dtend') {
121 my $iso_date = _format_date($meta{$_});
122 $hcalendar .= qq(<$etag><abbr class="$_" title="$iso_date">$meta{$_}</abbr></$etag>\n);
124 elsif ($_ eq 'duration') {
125 my $iso_duration = _format_duration($meta{$_});
126 $hcalendar .= qq(<$etag><abbr class="$_" title="$iso_duration">$meta{$_}</abbr></$etag>\n);
128 elsif ($_ eq 'url') {
129 $hcalendar .= qq(<$etag><a class="$_" href="$meta{url}">$meta{url}</a></$etag>\n);
132 $hcalendar .= qq(<$etag class="$_">$meta{$_}</$etag>\n);
135 $hcalendar .= qq(</$ctag>\n);
136 # debug(1, "uf_hcalendar_meta: $hcalendar\n");
138 my $autoappend = _get_meta( 'hcal_autoappend' );
139 $autoappend = $config{auto_append_to_body} unless defined $autoappend;
140 return 1 unless $autoappend;
142 $$body_ref .= "\n\n$hcalendar\n\n";
153 uf_hcalendar_meta - plugin to create an 'hcalendar' microformat tag from
158 uf_hcalendar_meta is a plugin to create an 'hcalendar' microformat tag
159 from metadata in your post. The microformat tag is created in the
160 $uf_hcalendar_meta::hcalendar variable for use in templates or by other
161 plugins, or if the $auto_append_to_body flag is set (it is by default),
162 uf_hcalendar_meta will append the tag to your story body automatically.
164 =head2 REQUIRED METADATA ITEMS
166 (If using the 'metamail/metadir/metafile' plugins, metadata items
167 are matched case insensitively.)
173 The summary or title of the event.
177 The start date/time of the event.
179 Must be given as an ISO 8601 calendar date, in the form
180 YYYY-MM-DDTHH:MM:SS or YYYYMMDDTHHMMSS, with an optional trailing
181 timezone of the form /[+-]HH(:?MM)?/. Any number of rightmost time
182 elements may be omitted. Hours must be given in 24-hour time.
184 For convenience, this plugin allows the 'T' marker to be replaced by
187 The following are all valid dtstart values, for example:
191 =item 2007-09-01T19:30:00+10:00
193 =item 20070901T193000-10
197 =item 2007-09-01 17:45
209 The end date/time of the event. Must be an ISO 8601 calendar date
210 as defined for dtstart above.
214 The duration of the event. This may be an ISO 8601 duration, of the
215 form PnnYnnMnnDTnnHnnMnnS e.g. "P3Y6M4DT12H30M0S". Elements may be
216 omitted if their duration is zero. The smallest value used may also
217 have a decimal fraction, as in "P0.5Y" to indicate half a year.
219 For convenience, this plugin interprets the units case-insensitively,
220 allows the 'P' and 'T' markers to be omitted, and also accepts
221 whitespace in the place of the 'T' time marker.
223 Note that because months and minutes use the same signifier, there is
224 ambiguity about the meaning of 'P1M' and '1M'. This plugin interprets
225 'M' values as follows:
231 Interpreted as minutes, since this is the most common use case, and
232 since ISO 8601 really requires a leading 'P' signifier.
236 Interpreted as months, following ISO 8601.
240 Interpreted as minutes, following ISO 8601.
247 =head2 OPTIONAL METADATA ITEMS
253 A description of the event, sometimes longer than the summary.
257 The end date/time of the event, as discussed above.
261 The duration of the event, as discussed above.
265 A string describing the location of the event.
269 A canonical URL for the event.
273 A unique identifier for this event. Apparently required by some
274 versions of Microsoft Outlook.
278 =head2 Config Elements
280 uf_hcalendar_meta also supports a couple of config elements that can be used to
281 override plugin config data on a per-story basis:
285 =item HCal-Class (metamail) / hcal_class (meta)
287 This class (or list of classes) is appended to the class list applied to the
288 top-level hcalendar element in the rendered hcalendar i.e. it overrides the
289 'class' config variable.
291 =item HCal-Autoappend (metamail) / hcal_autoappend (meta)
293 This is a flag (0 or 1) indicating whether the rendered hcalendar should be
294 automatically appended to the story body. It overrides the 'auto_append_to_body'
297 =item HCal-Style (metamail) / hcal_style (meta)
299 One of the following styles: 'div-span', 'ul', 'dl', used to render the hcalendar.
300 It overrides the 'style' config variable.
306 uf_hcalendar_meta should be loaded after the meta plugins (meta
307 itself, or the metaclear/metamail/metadir/metafile family).
311 Microformats.org: http://www.microformats.org/,
312 http://microformats.org/wiki/hcalendar.
314 Blosxom: http://blosxom.sourceforge.net/
318 Only the most common hcalendar attributes have been implemented
319 so far. Please let me know if you'd like something not available
324 Gavin Carr <gavin@openfusion.com.au>, http://www.openfusion.net/
328 Copyright 2007, Gavin Carr.
330 This plugin is licensed under the same terms as blosxom itself i.e.
332 Permission is hereby granted, free of charge, to any person obtaining a
333 copy of this software and associated documentation files (the "Software"),
334 to deal in the Software without restriction, including without limitation
335 the rights to use, copy, modify, merge, publish, distribute, sublicense,
336 and/or sell copies of the Software, and to permit persons to whom the
337 Software is furnished to do so, subject to the following conditions:
339 The above copyright notice and this permission notice shall be included
340 in all copies or substantial portions of the Software.
342 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
343 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
344 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
345 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
346 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
347 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
348 OTHER DEALINGS IN THE SOFTWARE.