/ 
HTML-TagClouder-0.02
River stage zero No dependents
/ HTML::TagClouder

NAME

HTML::TagClouder - Configurable Tag Cloud Generator

SYNOPSIS

use HTML::TagClouder;

# All arguments are optional!
my $cloud = HTML::TagClouder->new(
  collection_class      => 'HTML::TagClouder::Collection::Simple',
  collection_class_args => { ... },
  processor_class       => 'HTML::TagClouder::Collection::Processor::Simple',
  processor_class_args  => { ... }, 
  render_class          => 'HTML::TagClouder::Render::TT',
  render_class_args     => {
    tt_args => {
      INCLUDE_PATH => '/path/to/templates'
    }
  }
);
$cloud->add(HTML::TagClouder::Tag->new($label, $uri, $count, $timestamp));
$cloud->add($label, $uri, $count, $timestamp);

$cloud->render;

# or in your template
[% cloud %]

DESCRIPTION

*WARNING* Alpha software! I mean it!

HTML::TagClouder is another take on generating Tagclouds.

It was build because a coleague complained that he wanted to customize the HTML that gets generated for tag clouds. Other modules generated their own HTML and it was hardcoded, hence HTML::TagClouder was born.

Currently it does just the bare minimum to generate a cloud (see CAVEATS), but the entire process is completely configurable by allowing you to pass in class names to do the particular job in each phase of generating the tag cloud.

HTML::TagClouder goes through 3 phases before generating a tag cloud:

1. Data Collection

Build up your tag list via $cloud->add($tag). The tag collection is built using HTML::TagClouder::Collection.

2. Process The Tags

The processor specified in processor_class (HTML::TagClouder::Processor::Simple by default) will iterator through the collection that was built, and will do any required calculation.

3. Render The Tags

The tags will be rendered as appropriate. By default we use Template Toolkit for this via HTML::TagClouder::Render::TT.

The main difference between the other tag cloud generators is that each phase of the cloud generation is completely configurable. For example, by default it uses a very naive algorithm to calculate the font sizes for the tags, but you can easily change the logic by simple changing the 'processor' class to something you built:

my $cloud = HTML::TagClouder->new(
  processor_class => 'MyProcessor'
);

Or, should you decide to use a different rendering engine than the default Template Toolkit based renderer, you can do:

my $cloud = HTML::TagClouder->new(
  render_class => 'MyRenderClass'
);

STRINGIFICATION

HTML::TagClouder objects automatically stringify as HTML, so you can simply place it in your favorite template's variable stash. For example, in Catalyst with Template Toolkit:

# in your controller
sub cloud : Local {
   my ($self, $c) = @_;
   my $cloud = HTML::TagClouder->new(...);
   # add tags to cloud

   $c->stash->{cloud} = $cloud;
}

# in your template
[% cloud %]

The above will simply insert the HTML generated by HTML::TagClouder. No methods! Of course, you can achieve the equivalent by doing:

[% cloud.render %]

TODO

Incorporate "hot" tags.
Set maximum for tag list

Patches welcome!

CAVEATS

The interface allows a timestamp argument, but it does nothing at this moment. I don't plan on using it for a while, so if you want it, patches welcome.

The above also means that currently there's no way to change the color of the tags. Of course, you can always create your own subclasses that does so.

METHODS

new %args

new() constructs a new HTML::TagClouder instance, and may take the following parameters. If a parameter is omitted, some sane default will be provided.

collection_class

The HTML::TagClouder::Collection class name that will hold the tags while the cloud is being built

collection_class_args

A hashref of arguments to be passed to the collection class' constructor.

processor_class

The HTML::TagClouder::Processor class name that will be used to normalize the tags. This is responsible for calculating various attributes that will be used when rendering the tag cloud

processor_class_args

A hashref of arguments to be passed to the processor class' constructor.

render_class

The HTML::TagClouder::Render class name that will be used to render the tag cloud for presentation

render_class_args

A hashref of arguments to be passed to the render class' constructor.

setup

Sets up the object.

add $tag

add $label, $uri, $count, $timestamp

Adds a new tag. Accepts either the parameters passed to HTML::TagClouder::Tag constructor, or a HTML::TagClouder::Tag instance

process

Processes the tags. This method will be automatically called from render()

render

Renders the tag cloud and returns the html.

SEE ALSO

HTML::TagCloud::Extended, HTML::TagCloud

AUTHOR

Copyright (c) 2007 Daisuke Maki <daisuke@endeworks.jp>

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html