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

    <para>
        <classname>Zend_Tag</classname> is a component suite which provides a facility
        to work with taggable Items. As its base, it provides two classes to
        work with Tags, <classname>Zend_Tag_Item</classname> and
        <classname>Zend_Tag_ItemList</classname>. Additionally, it comes with the
        interface <classname>Zend_Tag_Taggable</classname>, which allows you to use any of
        your models as a taggable item in conjunction with
        <classname>Zend_Tag</classname>.
    </para>

    <para>
        <classname>Zend_Tag_Item</classname> is a basic taggable item implementation
        which comes with the essential functionallity required to work with
        the <classname>Zend_Tag</classname> suite. A taggable item always consists of
        a title and a relative weight (e.g. number of occurences). It also
        stores parameters which are used by the different sub-components of
        <classname>Zend_Tag</classname>.
    </para>

    <para>
        To group multiple items together, <classname>Zend_Tag_ItemList</classname> exists
        as an array iterator and provides additional functionallity to calculate
        absolute weight values based on the given relative weights of each
        item in it.
    </para>

    <example id="zend.tag.example.using">
        <title>Using Zend_Tag</title>
        <para>
            This example illustrates how to create a list of tags and spread
            absolute weight values on them.
        </para>
        <programlisting language="php"><![CDATA[
// Create the item list
$list = new Zend_Tag_ItemList();

// Assign tags to it
$list[] = new Zend_Tag_Item(array('title' => 'Code', 'weight' => 50));
$list[] = new Zend_Tag_Item(array('title' => 'Zend Framework', 'weight' => 1));
$list[] = new Zend_Tag_Item(array('title' => 'PHP', 'weight' => 5));

// Spread absolute values on the items
$list->spreadWeightValues(array(1, 2, 3, 4, 5, 6, 7, 8, 9, 10));

// Output the items with their absolute values
foreach ($list as $item) {
    printf("%s: %d\n", $item->getTitle(), $item->getParam('weightValue'));
}
]]></programlisting>
        <para>
            This will output the three items Code, Zend Framework and <acronym>PHP</acronym> with
            the absolute values 10, 1 and 2.
        </para>
    </example>
</sect1>
