NAME

App::ZofCMS::Plugin::TagCloud - generate "tag clouds"

SYNOPSIS

In your ZofCMS template or main config file:

    plug_tag_cloud => {
        unit => 'em',
        tags => [ qw(
                foo /foo 2
                bar /bar 1
                ber /ber 3
            )
        ],
    }

In your HTML::Template template:

    <style type="text/css">
        <tmpl_var name="tag_cloud_css">
    </style>

    <tmpl_var name="tag_cloud">

DESCRIPTION

The module is a plugin for App::ZofCMS; it generates "tag clouds" (bunch of different-sized links).

This documentation assumes you have read App::ZofCMS, App::ZofCMS::Config and App::ZofCMS::Template

ZofCMS TEMPLATE/MAIN CONFIG FILE KEYS

    plug_tag_cloud => {
        id          => 'tag_cloud_container',
        class       => 'tag_cloud_tag',
        unit        => 'em',
        shuffle     => 1,
        uri_prefix  => 'http://site.com/',
        fg          => '#00d',
        bg          => 'transparent',
        fg_hover    => '#66f',
        bg_hover    => 'transparent',
        fg_visited  => '#333',
        bg_visited  => 'transparent',
        tags => [ qw(
                foo /foo 2
                bar /bar 1
                ber /ber 3
            )
        ],
    }

Plugin gets its data through plug_tag_cloud first-level key in either ZofCMS template or main config file. Specifying this key in ZofCMS template will completely override whatever you set under that key in main config file.

The key takes a hashref as a value. Possible keys/values of that hashref are as follows:

tags

    tags => [ qw(
            foo /foo 2
            bar /bar 1
            ber /ber 3
        )
    ],

    # or

    tags => [
        [ qw(foo /foo 2) ],
        [ qw(bar /bar 1) ],
        [ qw(ber /ber 3) ],
    ],

Mandatory. The tags key takes an arrayref as a value. Elements of that arrayref can be either either plain strings or arrayrefs. You cannot mix the two. If elements are plain strings they will be converted internally into the "arrayref form" by grouping by three (see examples above, they are equivalent).

The elements of the inner arrayrefs are as follows: first element is the text for the link in the tag cloud. Second element is the URI to which the tag points. Third element is the "weight" of the tag, the larger the number the larger the tag will be. The third element actually also serves for the font-size value in the CSS code generated by the plugin.

id

    id => 'tag_cloud_container',

Optional. The id key takes a string as a value. This sting will be used for the id="" attribute of the tag cloud <ul> element. Defaults to: zofcms_tag_cloud

class

    class => 'tag_cloud_tag',

Optional. The class key takes a string as a value. This sting will be used to generate class names for cloud tags. Defaults to: zofcms_tag_cloud

unit

    unit => 'em',

Optional. The unit key takes a string as a value. This string must be a valid CSS unit for font-size property. Whatever you pass in here will be directly used in the generated CSS code and the number for that unit will be taken from the "weight" of the cloud tag (see tags key above). Defaults to: %

shuffle

    shuffle => 1,

Optional. Takes either true or false value. When set to a true value the elements of your tag cloud will be shuffled each and every time. Default to: 0

uri_prefix

    uri_prefix  => 'http://site.com/',

Optional. The uri_prefix takes a string as a value. This string will be prepended to all of the URIs to which your tags are pointing. Defaults to: empty string.

fg

    fg => '#00d',

Optional. Specifies the color to use for foreground on <a href=""> elements; will be directly used for color property in generated CSS code. Defaults to: #00d.

bg

    bg => 'transparent',

Optional. Specifies the color to use for background on <a href=""> elements; will be directly used for background property in generated CSS code. Defaults to: transparent.

fg_hover

    fg_hover => '#66f',

Optional. Same as fg except this one is used for :hover pseudo-selector. Defaults to: #66f

bg_hover

    bg_hover => 'transparent',

Optional. Same as bg except this one is used for :hover pseudo-selector. Defaults to: transparent

fg_visited

    fg_visited  => '#333',

Optional. Same as fg except this one is used for :visited pseudo-selector. Defaults to: #333

bg_visited

Optional. Same as bg except this one is used for :visited pseudo-selector. Defaults to: transparent

HTML::Template TEMPLATE VARIABLES

The plugin will stuff two keys into {t} special key in your ZofCMS templates. This means that you can use them in your HTML::Template templates.

tag_cloud

    <tmpl_var name="tag_cloud">

This one will contain the HTML code for your tag cloud.

tag_cloud_css

    <style type="text/css">
        <tmpl_var name="tag_cloud">
    </style>

This one will contain the CSS code for your tag cloud. You obviously don't have to use this one and instead code your own CSS.

EXAMPLE OF GENERATED HTML CODE

    <ul id="tag_cloud">
        <li class="tag_cloud_tag3"><a href="http://site.com/ber">ber</a></li>
        <li class="tag_cloud_tag2"><a href="http://site.com/foo">foo</a></li>
        <li class="tag_cloud_tag1"><a href="http://site.com/bar">bar</a></li>
    </ul>

EXAMPLE OF GENERATED CSS CODE

    #tag_cloud li {
        display: inline;
    }
        #tag_cloud a {
            color: #f00;
            background: #00f;
        }
        #tag_cloud a:visited {
            color: #000;
            background: transparent;
        }
        #tag_cloud a:hover {
            color: #FFf;
            background: transparent;
        }
        .tag_cloud_tag1 { font-size: 1em; }
        .tag_cloud_tag2 { font-size: 2em; }
        .tag_cloud_tag3 { font-size: 3em; }

REPOSITORY

Fork this module on GitHub: https://github.com/zoffixznet/App-ZofCMS

BUGS

To report bugs or request features, please use https://github.com/zoffixznet/App-ZofCMS/issues

If you can't access GitHub, you can email your request to bug-App-ZofCMS at rt.cpan.org

AUTHOR

Zoffix Znet <zoffix at cpan.org> (http://zoffix.com/, http://haslayout.net/)

LICENSE

You can use and distribute this module under the same terms as Perl itself. See the LICENSE file included in this distribution for complete details.

cpanm App::ZofCMS

perl -MCPAN -e shell
install App::ZofCMS