<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.tag.cloud">
    <title>Zend_Tag_Cloud</title>

    <para>
        <classname>Zend_Tag_Cloud</classname> is the rendering part of
        <classname>Zend_Tag</classname>. By default it comes with a set of <acronym>HTML</acronym>
        decorators, which allow you to create tag clouds for a website, but
        also supplies you with two abstract classes to create your own
        decorators, to create tag clouds in <acronym>PDF</acronym> documents for example.
    </para>

    <para>
        You can instantiate and configure <classname>Zend_Tag_Cloud</classname> either
        programatically or completely via an array or an instance of
        <classname>Zend_Config</classname>. The available options are:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <property>cloudDecorator</property>: defines the decorator for the
                cloud. Can either be the name of the class which should be
                loaded by the pluginloader, an instance of
                <classname>Zend_Tag_Cloud_Decorator_Cloud</classname> or an array
                containing the string 'decorator' and optionally
                an array 'options', which will be passed to the
                decorators constructor.
            </para>
        </listitem>

        <listitem>
            <para>
                <property>tagDecorator</property>: defines the decorator for individual
                tags. This can either be the name of the class which should be
                loaded by the pluginloader, an instance of
                <classname>Zend_Tag_Cloud_Decorator_Tag</classname> or an array
                containing the string 'decorator' and optionally
                an array 'options', which will be passed to the
                decorators constructor.
            </para>
        </listitem>

        <listitem>
            <para>
                <property>pluginLoader</property>: a different plugin loader to use.
                Must be an instance of
                <classname>Zend_Loader_PluginLoader_Interface</classname>.
            </para>
        </listitem>

        <listitem>
            <para>
                <property>prefixPath</property>: prefix paths to add to the plugin
                loader. Must be an array containing the keys prefix and path or
                multiple arrays containing the keys prefix and path. Invalid
                elements will be skipped.
            </para>
        </listitem>

        <listitem>
            <para>
                <property>itemList</property>: a different item list to use. Must be an
                instance of <classname>Zend_Tag_ItemList</classname>.
            </para>
        </listitem>

        <listitem>
            <para>
                <property>tags</property>: a list of tags to assign to the cloud. Each
                tag must either implement <classname>Zend_Tag_Taggable</classname> or be
                an array which can be used to instantiate
                <classname>Zend_Tag_Item</classname>.
            </para>
        </listitem>
    </itemizedlist>

    <example id="zend.tag.cloud.example.using">
        <title>Using Zend_Tag_Cloud</title>

        <para>
            This example illustrates a basic example of how to create a tag
            cloud, add multiple tags to it and finally render it.
        </para>

        <programlisting language="php"><![CDATA[
// Create the cloud and assign static tags to it
$cloud = new Zend_Tag_Cloud(array(
    'tags' => array(
        array('title' => 'Code', 'weight' => 50,
              'params' => array('url' => '/tag/code')),
        array('title' => 'Zend Framework', 'weight' => 1,
              'params' => array('url' => '/tag/zend-framework')),
        array('title' => 'PHP', 'weight' => 5,
              'params' => array('url' => '/tag/php')),
    )
));

// Render the cloud
echo $cloud;
]]></programlisting>

        <para>
            This will output the tag cloud with the three tags, spread with
            the default font-sizes.
        </para>
    </example>

    <sect2 id="zend.tag.cloud.decorators">
        <title>Decorators</title>

        <para>
            <classname>Zend_Tag_Cloud</classname> requires two types of decorators to be
            able to render a tag cloud. This includes a decorator which renders
            the single tags as well as a decorator which renders the surounding
            cloud. <classname>Zend_Tag_Cloud</classname> ships a default decorator set for
            formatting a tag cloud in <acronym>HTML</acronym>. This set will by default create a
            tag cloud as ul/li-list, spread with different font-sizes according
            to the weight values of the tags assigned to them.
        </para>

        <sect3 id="zend.tag.cloud.decorators.htmltag">
            <title>HTML Tag decorator</title>

            <para>
                The <acronym>HTML</acronym> tag decorator will by default render every tag in an
                anchor element, surounded by a li element. The anchor itself is
                fixed and cannot be changed, but the surounding element(s) can.
            </para>

            <note>
                <title>URL parameter</title>

                <para>
                    As the <acronym>HTML</acronym> tag decorator always surounds the tag title with
                    an anchor, you should define an <acronym>URL</acronym> parameter for every
                    tag used in it.
                </para>
            </note>

            <para>
                The tag decorator can either spread different font-sizes over
                the anchors or a defined list of classnames. When setting
                options for one of those possibilities, the corespondening one
                will automatically be enabled. The following configuration
                options are available:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <property>fontSizeUnit</property>: defines the font-size unit
                        used for all font-sizes. The possible values are:
                        em, ex, px, in, cm, mm, pt, pc and &#37;.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <property>minFontSize</property>: the minimum font-size
                        distributed through the tags (must be an integer).
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <property>maxFontSize</property>: the maximum font-size
                        distributed through the tags (must be an integer).
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <property>classList</property>: an arry of classes distributed
                        through the tags.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <property>htmlTags</property>: an array of <acronym>HTML</acronym> tags
                        surounding the anchor. Each element can either be a string, which
                        is used as element type then, or an array containing
                        an attribute list for the element, defined as key/value
                        pair. In this case, the array key is used as element
                        type.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.tag.cloud.decorators.htmlcloud">
            <title>HTML Cloud decorator</title>

            <para>
                The <acronym>HTML</acronym> cloud decorator will suround the <acronym>HTML</acronym>
                tags with an ul-element by default and add no separation. Like in the tag
                decorator, you can define multiple surounding <acronym>HTML</acronym> tags and
                additionally define a separator. The available options are:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <property>separator</property>: defines the separator which
                        is placed between all tags.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <property>htmlTags</property>: an array of <acronym>HTML</acronym> tags
                        surounding all tags. Each element can either be a string, which
                        is used as element type then, or an array containing
                        an attribute list for the element, defined as key/value
                        pair. In this case, the array key is used as element type.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>
    </sect2>
</sect1>
