Add initial tags, storytags, and tagcloud plugins.

[matthijs/upstream/blosxom-plugins.git] / gavinc / storytags

diff --git a/gavinc/storytags b/gavinc/storytags
new file mode 100644 (file)
index 0000000..148a48f
--- /dev/null
+++ b/gavinc/storytags
@@ -0,0 +1,124 @@
+# Blosxom Plugin: storytags
+# Author(s): Gavin Carr <gavin@openfusion.com.au>
+# Version: 0.001000
+# Documentation: See the bottom of this file or type: perldoc storytags
+# Requires: tags
+# Follows: tags
+
+package storytags;
+
+use strict;
+
+# Uncomment next line to enable debug output (don't uncomment debug() lines)
+#use Blosxom::Debug debug_level => 1;
+
+use vars qw($taglist);
+
+# --- Configuration variables -----
+
+# Formatting strings
+my $prefix = 'Tags: ';
+my $suffix = '. ';
+
+# ---------------------------------
+
+$taglist = '';
+
+sub start { 1 }
+
+# Set $taglist
+sub story {
+    my ($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;
+
+    return 1 unless $tags::tag_cache 
+                 && ref $tags::tag_cache 
+                 && keys %{ $tags::tag_cache };
+    return 1 unless defined $tags::tag_cache->{"$path/$filename"};
+
+    $taglist = _format_taglist($tags::tag_cache->{"$path/$filename"}->{tags});
+
+    return 1;
+}
+
+sub _format_taglist {
+    my ($tags) = @_;
+    $tags = '' unless defined $tags;
+    my @tags = sort { lc $a cmp lc $b } split /\s*,\s*/, $tags;
+    return '' unless @tags;
+    return $prefix
+           . join(', ', 
+               map { qq(<a href="$blosxom::url/tags/$_" rel="tag">$_</a>) }
+               @tags
+           )
+           . $suffix;
+}
+
+1;
+
+__END__
+
+=head1 NAME
+
+storytags - blosxom plugin to format a per-story $storytags::taglist string
+
+=head1 DESCRIPTION
+
+L<storytags> is a blosxom plugin to format a per-story $storytags::taglist 
+string. The string is a comma-separated list of the tags defined for the
+story, prefixed by $storytags::prefix, and suffixed by $storytags::suffix.
+If no tags are defined, then $taglist will be the empty string '' (i.e. no
+prefix and suffix are added).
+
+The default values for $prefix and $suffix are 'Tags: ' and '. ' 
+respectively, so a typical $taglist might look like:
+
+    Tags: dogs, cats, pets.
+
+=head1 USAGE
+
+L<storytags> requires the L<tags> plugin, and should be loaded AFTER
+L<tags>. It has no other ordering dependencies.
+
+=head1 ACKNOWLEDGEMENTS
+
+This plugin was inspired by xtaran's excellent L<tagging> plugin,
+which includes similar functionality.
+
+=head1 SEE ALSO
+
+L<tags>, L<tagcloud>, xtaran's L<tagging>.
+
+Blosxom: http://blosxom.sourceforge.net/
+
+=head1 AUTHOR
+
+Gavin Carr <gavin@openfusion.com.au>, http://www.openfusion.net/
+
+=head1 LICENSE
+
+Copyright 2007, Gavin Carr.
+
+This plugin is licensed under the same terms as blosxom itself i.e.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+=cut
+
+# vim:ft=perl:sw=4
+