2 # Author(s): Gavin Carr <gavin@openfusion.com.au>
4 # Documentation: See the bottom of this file or type: perldoc tags
11 # Uncomment next line to enable debug output (don't uncomment debug() lines)
12 #use Blosxom::Debug debug_level => 2;
14 use vars qw($tagroot $tag_cache $tag_entries $tag_counts);
16 # --- Configuration variables -----
18 # What path prefix is used for tag-based queries?
21 # What story header to you use for your tags?
22 my $tag_header = 'Tags';
24 # Where is our $tag_cache file?
25 my $tag_cache_file = "$blosxom::plugin_state_dir/tag_cache";
27 # ---------------------------------
32 my $tag_cache_dirty = 0;
39 if (-f $tag_cache_file) {
40 my $fh = FileHandle->new( $tag_cache_file, 'r' )
41 or warn "[tags] cannot open cache: $!";
54 my $path_info = "/$blosxom::path_info";
55 # debug(3, "entries, path_info $path_info");
57 if ($path_info =~ m!^$tagroot/(.*)!) {
58 $blosxom::flavour = '';
60 # debug(3, "entries, path_info matches tagroot (taglist $taglist)");
62 # Allow flavours appended to tags after a slash
63 # Dot-flavour versions are problematic, because tags can include dot e.g. web2.0
64 if ($taglist =~ m! /(\w+)$ !x) {
65 $blosxom::flavour = $1;
66 $taglist =~ s! /$blosxom::flavour$ !!x;
69 # Split individual tags out of taglist
70 if ($taglist =~ m/;/) {
71 @path_tags = split /\s*;\s*/, $taglist;
75 @path_tags = split /\s*,\s*/, $taglist;
78 # If $path_info matches $tagroot it's a virtual path, so reset
79 $blosxom::path_info = '';
80 $blosxom::flavour ||= $blosxom::default_flavour;
87 my ($pkg, $files_ref) = @_;
88 return 1 unless @path_tags;
91 for my $tag (@path_tags) {
92 if ($tag_entries->{$tag} && @{ $tag_entries->{$tag} }) {
93 for my $entry ( @{ $tag_entries->{$tag} } ) {
94 $tagged{"$blosxom::datadir$entry.$blosxom::file_extension"}++;
98 # debug(2, "entries tagged with " . join($path_tags_op,@path_tags) . ":\n " . join("\n ", sort keys %tagged));
100 # Now delete all entries from $files_ref except those tagged
101 my $tag_count = scalar @path_tags;
102 for (keys %$files_ref) {
103 if ($path_tags_op eq ';') {
104 # OR semantics - delete unless at least one tag
105 delete $files_ref->{$_} unless exists $tagged{$_};
108 # AND semantics - delete unless ALL tags
109 delete $files_ref->{$_} unless $tagged{$_} == $tag_count;
116 # Update tag cache on new or updated stories
118 my ($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;
120 my $file = "$blosxom::datadir$path/$filename.$blosxom::file_extension";
122 warn "[tags] cannot find story file '$file'";
127 my $st = stat($file) or die "bad stat: $!";
128 my $mtime = $st->mtime;
129 if ($tag_cache->{"$path/$filename"}->{mtime} == $mtime) {
130 # debug(3, "$path/$filename found up to date in tag_cache - skipping");
134 # mtime has changed (or story is new) - compare old and new tagsets
135 my $tags_new = $blosxom::meta{$tag_header};
136 my $tags_old = $tag_cache->{"$path/$filename"}->{tags};
137 # debug(2, "tags_new: $tags_new, tags_old: $tags_old");
139 return 1 if defined $tags_new && defined $tags_old && $tags_old eq $tags_new;
142 # debug(2, "updating tag_cache, mtime $mtime, tags '$tags_new'");
143 $tag_cache->{"$path/$filename"} = { mtime => $mtime, tags => $tags_new };
147 # Write tag_cache to disk if updated
149 if ($tag_cache_dirty) {
150 # Refresh tag entries and tag counts
153 for my $entry (keys %{$tag_cache}) {
154 next unless $tag_cache->{$entry}->{tags};
155 for (split /\s*,\s*/, $tag_cache->{$entry}->{tags}) {
156 $tag_entries->{$_} ||= [];
157 push @{ $tag_entries->{$_} }, $entry;
162 # Save tag caches back to $tag_cache_file
163 my $fh = FileHandle->new( $tag_cache_file, 'w' )
164 or warn "[tags] cannot open cache '$tag_cache_file': $!"
166 print $fh Data::Dumper->Dump([ $tag_cache, $tag_entries, $tag_counts ],
167 [ qw(tag_cache tag_entries tag_counts) ]);
178 tags - blosxom plugin to read tags from story files, maintain a tag cache,
179 and allow tag-based filtering
183 L<tags> is a blosxom plugin to read tags from story files, maintain a tag
184 cache, and allow tag-based filtering.
186 Tags are defined in a comma-separated list in a $tag_header header at the
187 beginning of a blosxom post, with $tag_header defaulting to 'Tags'. So for
188 example, your post might look like:
191 Tags: dogs, cats, pets
193 Post text goes here ...
195 L<tags> uses the L<metamail> plugin to parse story headers, and stores
196 the tags in a cache (in $tag_cache_file, which defaults to
197 $blosxom::plugin_state_dir/tag_cache). The tag cache is only updated
198 when the mtime of the story file changes, so L<tags> should perform
201 L<tags> also supports tag-based filtering. If the blosxom $path_info
202 begins with $tagroot ('/tags', by default, e.g. '/tags/dogs'), then
203 L<tags> filters the entries list to include only posts with the
204 specified tag. The following syntaxes are supported (assuming the
205 default '/tags' for $tagroot):
209 =item /tags/<tag> e.g. /tags/dog
211 Show only posts with the specified tag.
213 =item /tags/<tag1>,<tag2>[,<tag3>...] e.g. /tags/dogs,cats
215 (Comma-separated) Show only posts with ALL of the specified tags i.e.
218 =item /tags/<tag1>;<tag2>[;<tag3>...] e.g. /tags/dogs;cats
220 (Comma-separated) Show only posts with ANY of the specified tags i.e.
225 Tag filtering also supports a trailing flavour after the taglist,
226 separated by a slash e.g.
230 /tags/dogs;cats;pets/atom
232 Note that this is different to L<tagging>, which treats trailing
233 components as additional tags.
235 At this point L<tags> don't support dot-flavour paths e.g.
239 The problem with this is that tags can include dots, so it's
240 ambiguous how to parse C</tags/web2.0>, for instance. If you'd
241 like this supported and have suggestions about how to handle
242 the ambiguities, please get in touch.
246 L<tags> should be loaded early as it modifies blosxom $path_info when
247 doing tag-based filtering. Specifically, it needs to be loaded BEFORE
248 any C<entries> plugins (e.g. L<entries_index>, L<entries_cache>,
249 L<entries_timestamp>, etc.)
251 L<tags> depends on the L<metamail> plugin to parse the tags header,
252 though, so it must be loaded AFTER L<metamail>.
254 Also, because L<tags> does tag-based filtering, any filter plugins
255 that you want to have a global view of your entries (like
256 L<recententries>, for example) should be loaded BEFORE L<tags>.
258 =head1 ACKNOWLEDGEMENTS
260 This plugin was inspired by xtaran's excellent L<tagging> plugin.
261 Initially I was just looking to add caching to L<tagging>, but found
262 I wanted to use a more modular approach, and wanted to do slightly
263 different filtering than L<tagging> offered as well. L<tagging> is
264 still more full-featured.
268 L<tags> only handles maintaining the tags cache and doing tag-based
269 filtering. For displaying tag lists in stories, see L<storytags>.
270 For displaying a tagcloud, see L<tagcloud>.
272 L<metamail> is used for the tags header parsing.
274 See also xtaran's L<tagging> plugin, which inspired L<tags>.
276 Blosxom: http://blosxom.sourceforge.net/
280 Gavin Carr <gavin@openfusion.com.au>, http://www.openfusion.net/
284 Copyright 2007, Gavin Carr.
286 This plugin is licensed under the same terms as blosxom itself i.e.
288 Permission is hereby granted, free of charge, to any person obtaining a
289 copy of this software and associated documentation files (the "Software"),
290 to deal in the Software without restriction, including without limitation
291 the rights to use, copy, modify, merge, publish, distribute, sublicense,
292 and/or sell copies of the Software, and to permit persons to whom the
293 Software is furnished to do so, subject to the following conditions:
295 The above copyright notice and this permission notice shall be included
296 in all copies or substantial portions of the Software.
298 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
299 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
300 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
301 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
302 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
303 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
304 OTHER DEALINGS IN THE SOFTWARE.