The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


HTML::TagClouder - Configurable Tag Cloud Generator


  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);


  # or in your template
  [% cloud %]


*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'


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 %]


Incorporate "hot" tags.
Set maximum for tag list

Patches welcome!


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.


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.


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


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


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


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


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


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


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


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


Renders the tag cloud and returns the html.


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


Copyright (c) 2007 Daisuke Maki <>


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