<<

NAME

Konstrukt::Plugin::tags - Tagging plugin

SYNOPSIS

Tag interface

        <!-- 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" / &>

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:

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:

set

Sets the tags for a specified entry.

Parameters:

delete

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

Parameters:

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:

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

<<