The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Konstrukt-0.5-beta13
River stage zero No dependents
++
/ Konstrukt::Plugin::tags

NAME

Konstrukt::Plugin::tags - Tagging plugin

SYNOPSIS

Tag interface

Usage:

        <!-- display all tags as a cloud -->
        <& tags template="/tags/cloud.template" limit="30" order="alpha|count" / &>
        
        <!-- display all tags for a specified plugin.
             limit, order and template are also applicable here -->
        <& tags plugin="blog|image|..." / &>
        
        <!-- list tags for a specified entry only.
             show, limit, order are ignored. the template attribute is applicable -->
        <& tags plugin="blog" entry="42" / &>

Result:

        Tags: <a href="?action=filter;tags=bar">bar</a>,
        <a href="?action=filter;tags=foo">foo</a>, ...

Perl interface

        my $tags = use_plugin 'tags';
        
        #get all tags
        my $all_tags = $tags->get();
        
        #get all tags for a specified plugin
        my $all_blog_tags = $tags->get('blog');
        
        #get tags for a specified content entry (blog entry #42)
        my $all_entry_tags = $tags->get('blog', 42);
        
        #get all entries for a specified tag query
        my $entries = $tags->get_entries('must have all this tags');
        
        #get all blog entries matching the query
        my $entries = $tags->get_entries('must have all this tags', 'blog');
        
        #simple OR sets are also possible
        my $entries = $tags->get_entries('must have all this tags {and one of those}');
        
        #set tags
        $tags->set('blog', 42, 'some tags here');
        
        #delete all tags for a specified entry
        $tags->delete('blog', 42);

DESCRIPTION

This plugin offers easy content tagging and tag managements for other plugins. You can add tagging to your plugin in an instant.

#TODO: devdoc

CONFIGURATION

You may do some configuration in your konstrukt.settings to let the plugin know where to get its data and which layout to use. Default:

        #backend
        tags/backend                  DBI

        #layout
        tags/template_path            /templates/tags/
        tags/default_style            cloud #may be "cloud" or "list"
        tags/default_order            count #may be "count" or "alpha"
        
        #user levels
        tags/userlevel_write          1 #TODO: needed or done by each plugin?

See the documentation of the backend modules (e.g. "CONFIGURATION" in Konstrukt::Plugin::tags::DBI) for their configuration.

METHODS

init

Initializes this object. Sets $self->{backend} and $self->{template_path}. init will be called by the constructor.

install

Installs the templates.

Parameters:

none

get

Returns the tags for the given criteria. You may optionally specify the plugin and the identifier of a content entry to which the tags belong.

Parameters:

  • $plugin - Optional: Only return tags of this plugin.

  • $entry - Optional: Only return tags of this entry (of the specified plugin).

  • $order - Optional: The order of the tags. May be "alpha" or "count". Defaults to the Settings tags/default_order. Doesn't apply, when only retrieving the tags of a specified plugin and entry where the list will always be sorted alphabetically.

  • $limit - Optional: Only return a specified number of the most popular tags.

No plugin and no entry specified If you don't specify the plugin and the entry, a list of all tags will be returned as an array reference of hash references. The tag will be unique in this list. Additionally a count for each tag will be returned:

        [
                { title => 'tag title', count => 23 },
                { title => 'foo',       count => 42 },
                ...
        ]

Only plugin specified

If you only specify the plugin, the same output as above will be returned. But only the tags of the specified plugin will be returned (and counted).

Plugin and entry specified.

Will return a reference to an array containing only the tags for the specified entry of the specified plugin:

        [
                'tag1',
                'tag2',
                ...
        ]

get_entries

Returns the entries, that match a specified tag query string and optionally belong to a specified plugin.

If a plugin is specified the identifier of entries will be returned in an arrayref:

        [ 'someentry', 'someother', 23, 42, ... ]

Otherwise the entries will be returned as a reference to an array containing hash references with the identifier and the plugin for each entry:

        [
                { entry => 'someentry', plugin => 'someplugin' },
                ...
        ]

Parameters:

  • $tagquery - Tag query string. Multiple, space separated tags will be AND-combined and parsed into an arrayref:

            sometag "some other tag" foo bar
        ->
        ["sometag", "some other tag", "foo", "bar"]

    To get an OR-combination, put multiple tags into curly brackets, which will be parsed in a nested array ref:

            sometag {one of these seven tags is enough} baz
        ->
        ["sometag", [qw/one of these seven tags is enough/], "baz"]

    More complex (nested AND/OR-groups) are not supported.

  • $plugin - Optional: Only return entries of this plugin.

set

Sets the tags for a specified entry.

Parameters:

  • $plugin - The plugin the entry belongs to

  • $entry - The identifier of the entry

  • $tags - String containing all tags which should be set. The tags are space separated. You may put a tag, which contains whitespaces, into quotes:

            sometag "some other tag" last_tag

delete

Deletes the tags for a specified entry or all tags for a specified plugin or even all tags.

Parameters:

  • $plugin - Optional: The plugin the entry belongs to

  • $entry - Optional: The identifier of the entry

default :Action

Default (and only) action for this plugin. Will display a list of tags according to the attributes set in the <& tags / &> tag.

The attributes can be almost freely combined where it makes sense and some will have a default value if not set.

For some examples take a look at the synopsis.

Tag attributes:

  • template - Optional: The path to the template to display the tags. Defaults to "tags/template_path tags/default_style .template", which can be adjusted in the settings. You probably want to use your own template depending on the place/purpose you want to list the tags. The template must have a list definition with the name tags and list fields named title and count (with count being optional depending on which tags should be listed). There will also be field values with the names min_count and max_count which may help you to create tag clouds.

  • limit - Optional: Max. number of tags to display. Defaults to 0 = no limit.

  • order - Optional: Order of the tags. Either by their total count (count) or alphabetically (alpha). Defaults to the setting tags/default_order.

  • plugin - Optional: Only show tags of the specified plugin. When not specified all tags will be shown.

  • entry - Optional: Only show tags of the specified entry (of a specified plugin). Only works, when the plugin attribute is also supplied.

Parameters:

  • $tag - Reference to the tag (and its children) that shall be handled.

  • $content - The content below/inside the tag as a flat string.

  • $params - Reference to a hash of the passed CGI parameters.

AUTHOR

Copyright 2006 Thomas Wittek (mail at gedankenkonstrukt dot de). All rights reserved.

This document is free software. It is distributed under the same terms as Perl itself.

SEE ALSO

Konstrukt::Plugin::tags::DBI, Konstrukt::Plugin, Konstrukt