gavinc/uf_xfolk_meta

   1 # Blosxom Plugin: uf_xfolk_meta
   2 # Author(s): Gavin Carr <gavin@openfusion.com.au>
   3 # Version: 0.001000
   4 # Documentation: 'perldoc uf_xfolk_meta'
   5
   6 package uf_xfolk_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   # URL to use as base URL for tag links
  18   tagbase => "$blosxom::url/tags",
  19
  20   # Extra CSS classes to add to the microformat container e.g. to turn display off
  21   class => '',
  22   #class => 'nodisplay',
  23
  24   # Whether to automatically add microformat to story bodies. If not set,
  25   # you must explicitly add $uf_adr_meta::adr to a template somewhere.
  26   auto_append_to_body => 1,
  27
  28   # What markup style to use for your adr, if auto-appending.
  29   # 3 styles are currently defined:
  30   # 'div-span' uses a 'div' elt for the container, and 'span' elements for the fields
  31   # 'ul' uses a 'ul' list for the container, and 'li' elements for the fields
  32   # 'dl' uses a 'dl' list for the container, 'dt' elements for field names, and
  33   #    'dd' elements for the fields themselves
  34   #style => 'div-span',
  35   #style => 'ul',
  36   style => 'dl',
  37
  38 );
  39
  40 # --------------------------------
  41
  42 use vars qw($xfolk);
  43
  44 # Attributes which if set will cause us to skip this plugin (looks like an hcard)
  45 my @skip_attr = qw(fn name);
  46
  47 $config{style} = 'div-span' unless $config{style} eq 'ul' or $config{style} eq 'dl';
  48
  49 sub start { 1 }
  50
  51 # Return the first existing metadata item key and value given a list of keys
  52 sub _get_meta {
  53     for my $attr ( @_ ) {
  54         my $meta_attr = $attr;
  55         $meta_attr =~ s/-/_/g;
  56         my $value = $blosxom::meta{$meta_attr};
  57         $value = eval "\$meta::$attr" unless defined $value;
  58         return wantarray ? ( $attr, $value ) : $value if defined $value;
  59     }
  60     return wantarray ? () : undef;
  61 }
  62
  63 sub story {
  64     my ($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;
  65
  66     # Skip if any of the @skip_attr are set
  67     for (@skip_attr) {
  68         return 1 if $blosxom::meta{$_} || eval "\$meta::$_";
  69     }
  70
  71     my $story_style = _get_meta( 'xfolk_style' ) || $config{style};
  72     my $ctag = $story_style eq 'div-span' ? 'div' : $story_style;
  73     my $etag = $story_style eq 'div-span' ? 'span' :
  74                $story_style eq 'ul' ? 'li' : 'dd';
  75
  76     # Required metadata
  77     my $url = _get_meta('url', 'taggedlink');
  78     my $title = _get_meta('title');
  79     my $tags = _get_meta('tags');
  80     my $description = _get_meta('description');
  81     return 1 unless defined $url && defined $title;
  82
  83     $xfolk = '';
  84     my $container_classes = 'xfolkentry';
  85     if (my $meta_class = _get_meta('xfolk_class')) {
  86       $container_classes .= " $meta_class";
  87     }
  88     else {
  89       $container_classes .= " $config{class}" if $config{class};
  90     }
  91     $xfolk .= qq(<$ctag class="$container_classes">\n);
  92     $xfolk .= qq(<dt>URL</dt>) if $story_style eq 'dl';
  93     $xfolk .= qq(<$etag class="xfolk_link"><a class="taggedlink" href="$url" title="$title">$title</a></$etag>\n);
  94     if ($tags) {
  95       $xfolk .= qq(<dt>Tags</dt>) if $story_style eq 'dl';
  96       $xfolk .= qq(<$etag class="xfolk_tags">);
  97       my @tags = ();
  98       for (split /\s*,\s*/, $tags) {
  99         push @tags, qq(<a rel="tag" href="$config{tagbase}/$_">$_</a>);
 100       }
 101       $xfolk .= join ', ', @tags if @tags;
 102       $xfolk .= qq(</$etag>\n);
 103     }
 104     if ($description) {
 105       $xfolk .= qq(<dt>Description</dt>) if $story_style eq 'dl';
 106       $xfolk .= qq(<$etag class="description">$description</$etag>\n)
 107     }
 108     $xfolk .= qq(</$ctag>\n);
 109     # debug(1, "uf_xfolk_meta: $xfolk\n");
 110
 111     my $autoappend = _get_meta( 'xfolk_autoappend' );
 112     $autoappend = $config{auto_append_to_body} unless defined $autoappend;
 113     return 1 unless $autoappend;
 114
 115     $$body_ref .= "\n\n$xfolk\n\n";
 116
 117     return 1;
 118 }
 119
 120 1;
 121
 122 __END__
 123
 124 =head1 NAME
 125
 126 uf_xfolk_meta - plugin to create a 'xfolk' (bookmark) microformat tag
 127 from post metadata
 128
 129 =head1 DESCRIPTION
 130
 131 uf_xfolk_meta is a plugin to create an 'xfolk' (bookmark) microformat tag
 132 from metadata in your post. The microformat tag is created in the
 133 $uf_xfolk_meta::xfolk variable for use in templates or by other plugins,
 134 or if the 'auto_append_to_body' config variable is set (it is by default),
 135 uf_xfolk_meta will append the tag to your story body automatically.
 136
 137 =head2 REQUIRED METADATA ITEMS
 138
 139 =over 4
 140
 141 =item url (or taggedlink)
 142
 143 The URL for the bookmarked page.
 144
 145 =item title
 146
 147 The title to use for the bookmarked page.
 148
 149 =back
 150
 151 If any required metadata is missing the plugin just skips the story.
 152
 153 =head2 OPTIONAL METADATA ITEMS
 154
 155 =over 4
 156
 157 =item tags
 158
 159 Comma-separated list of tags applying to the bookmarked page.
 160
 161 =item description
 162
 163 Description or summary of the bookmarked page.
 164
 165 =back
 166
 167 =head2 Config Elements
 168
 169 uf_xfolk_meta also supports a couple of config elements that can be used to
 170 override plugin config data on a per-story basis:
 171
 172 =over 4
 173
 174 =item XFolk-Class (metamail) / xfolk_class (meta)
 175
 176 This class (or list of classes) is appended to the class list applied to the
 177 top-level xfolk element in the rendered xfolk i.e. it overrides the
 178 'class' config variable.
 179
 180 =item XFolk-Autoappend (metamail) / xfolk_autoappend (meta)
 181
 182 This is a flag (0 or 1) indicating whether the rendered xfolk should be
 183 automatically appended to the story body. It overrides the 'auto_append_to_body'
 184 config variable.
 185
 186 =item XFolk-Style (metamail) / xfolk_style (meta)
 187
 188 One of the following styles: 'div-span', 'ul', 'dl', used to render the xfolk.
 189 It overrides the 'style' config variable.
 190
 191 =back
 192
 193 =head1 USAGE
 194
 195 uf_xfolk_meta should be loaded after the meta plugins (meta
 196 itself, or the metaclear/metamail/metadir/metafile family).
 197
 198 =head1 SEE ALSO
 199
 200 Microformats.org: http://www.microformats.org/, http://microformats.org/wiki/xfolk.
 201
 202 Blosxom: http://blosxom.sourceforge.net/
 203
 204 =head1 AUTHOR
 205
 206 Gavin Carr <gavin@openfusion.com.au>, http://www.openfusion.net/
 207
 208 =head1 LICENSE
 209
 210 Copyright 2007, Gavin Carr.
 211
 212 This plugin is licensed under the same terms as blosxom itself i.e.
 213
 214 Permission is hereby granted, free of charge, to any person obtaining a
 215 copy of this software and associated documentation files (the "Software"),
 216 to deal in the Software without restriction, including without limitation
 217 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 218 and/or sell copies of the Software, and to permit persons to whom the
 219 Software is furnished to do so, subject to the following conditions:
 220
 221 The above copyright notice and this permission notice shall be included
 222 in all copies or substantial portions of the Software.
 223
 224 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 225 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 226 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 227 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 228 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 229 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 230 OTHER DEALINGS IN THE SOFTWARE.
 231
 232 =cut
 233
 234 # vim:ft=perl