vendor/zendframework/zend-tag/doc/book/tag-cloud.md

   1 # Creating tag clouds
   2
   3 `Zend\Tag\Cloud` is the rendering aspect of zend-tag. By default, it comes with
   4 a set of HTML decorators, allowing you to create tag clouds for a website. It
   5 also supplies you with two abstract classes to create your own decorators; one
   6 use case might be to create tag clouds in PDF documents.
   7
   8 You can instantiate and configure `Zend\Tag\Cloud` either programmatically or
   9 via a configuration sturcture (either an array or an instance of `Traversable`).
  10
  11 The following options are available:
  12
  13 Option | Description
  14 ------ | ------
  15 `cloudDecorator` | Defines the decorator for the cloud. Can either be the name of the class which should be loaded by the plugin manager, an instance of `Zend\Tag\Cloud\Decorator\AbstractCloud` or an array containing the decorator under the key decorator and optionally an array under the key options, which will be passed to the decorator’s constructor.
  16 `tagDecorator` | Defines the decorator for individual tags. This can either be the name of the class which should be loaded by the plugin manager, an instance of `Zend\Tag\Cloud\Decorator\AbstractTag` or an array containing the decorator under the key decorator and optionally an array under the key options, which will be passed to the decorator’s constructor.
  17 `decoratorPluginManager` | A different plugin manager to use. Must be an instance of `Zend\ServiceManager\AbstractPluginManager`.
  18 `itemList` | A different item list to use. Must be an instance of `Zend\Tag\ItemList`.
  19 `tags` |  Array of tags to assign to the cloud. Each tag must either implement `Zend\Tag\TaggableInterface` or be an array which can be used to instantiate `Zend\Tag\Item`.
  20
  21 ## Using Zend\\Tag\\Cloud
  22
  23 This example illustrates a basic example of how to create a tag cloud, add
  24 multiple tags to it, and finally render it.
  25
  26 ```php
  27 // Create the cloud and assign static tags to it
  28 $cloud = new Zend\Tag\Cloud([
  29     'tags' => [
  30         [
  31             'title'  => 'Code',
  32             'weight' => 50,
  33             'params' => ['url' => '/tag/code'],
  34         ],
  35         [
  36             'title'  => 'Zend Framework',
  37             'weight' => 1,
  38             'params' => ['url' => '/tag/zend-framework'],
  39         ],
  40         [
  41             'title' => 'PHP',
  42             'weight' => 5,
  43             'params' => ['url' => '/tag/php'],
  44         ],
  45     ],
  46 ]);
  47
  48 // Render the cloud
  49 echo $cloud;
  50 ```
  51
  52 This will output the tag cloud with the three tags, spread with the default
  53 font-sizes:
  54
  55 ```php
  56 <ul class="zend-tag-cloud">
  57     <li>
  58         <a href="/tag/code" style="font-size: 20px;">
  59             Code
  60         </a>
  61     </li>
  62     <li>
  63         <a href="/tag/zend-framework" style="font-size: 10px;">
  64             Zend Framework
  65         </a>
  66     </li>
  67     <li>
  68         <a href="/tag/php" style="font-size: 11px;">
  69             PHP
  70         </a>
  71     </li>
  72 </ul>
  73 ```
  74
  75 > ### Formatting
  76 >
  77 > The HTML code examples are preformatted for a better visualization in the
  78 > documentation.  You can define a output separator for the [HTML cloud
  79 > decorator](#html-cloud-decorator).
  80
  81 The following example shows how create the **same** tag cloud from a `Zend\Config\Config` object.
  82
  83 ```ini
  84 ; An example tags.ini file
  85 tags.1.title = "Code"
  86 tags.1.weight = 50
  87 tags.1.params.url = "/tag/code"
  88 tags.2.title = "Zend Framework"
  89 tags.2.weight = 1
  90 tags.2.params.url = "/tag/zend-framework"
  91 tags.3.title = "PHP"
  92 tags.3.weight = 2
  93 tags.3.params.url = "/tag/php"
  94 ```
  95
  96 ```php
  97 // Create the cloud from a Zend\Config\Config object
  98 $config = Zend\Config\Factory::fromFile('tags.ini');
  99 $cloud = new Zend\Tag\Cloud($config);
 100
 101 // Render the cloud
 102 echo $cloud;
 103 ```
 104
 105 ## Decorators
 106
 107 `Zend\Tag\Cloud` requires two types of decorators to be able to render a tag cloud:
 108
 109 - A decorator for rendering an individual tag.
 110 - A decorator for rendering the surrounding cloud.
 111
 112 `Zend\Tag\Cloud` ships a default decorator set for formatting a tag cloud in
 113 HTML. This set will, by default, create a tag cloud as a `<ul>/<li>` list,
 114 spread with different font-sizes according to the weight values of the tags
 115 assigned to them.
 116
 117 ### HTML Tag decorator
 118
 119 The HTML tag decorator will by default render every tag in an anchor element, surrounded by a
 120 `<li>` element. The anchor itself is fixed and cannot be changed, but the surrounding element(s)
 121 can.
 122
 123 > #### URL parameter
 124 >
 125 > As the HTML tag decorator always surounds the tag title with an anchor, you
 126 > should define a URL parameter for every tag used in it.
 127
 128 The tag decorator can either spread different font-sizes over the anchors or a
 129 defined list of classnames. When setting options for one of those possibilities,
 130 the corresponding one will automatically be enabled.
 131
 132 The following configuration options are available:
 133
 134 Option | Default | Description
 135 ------ | ------- | -----------
 136 `fontSizeUnit` | `px` | Defines the font-size unit used for all font-sizes. The possible values are: em, ex, px, in, cm, mm, pt, pc and %.
 137 `minFontSize` | `10` | The minimum font-size distributed through the tags (must be numeric).
 138 `maxFontSize` | `20` | The maximum font-size distributed through the tags (must be numeric).
 139 `classList` | `null` | An array of classes distributed through the tags.
 140 `htmlTags` | `array('li')` | An array of HTML tags surrounding the anchor. Each element can either be a string, which is used as element type, 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.
 141
 142 The following example shows how to create a tag cloud with a customized HTML tag decorator.
 143
 144 ```php
 145 $cloud = new Zend\Tag\Cloud([
 146     'tagDecorator' => [
 147         'decorator' => 'htmltag',
 148         'options'   => [
 149             'minFontSize' => '20',
 150             'maxFontSize' => '50',
 151             'htmlTags'    => [
 152                 'li' => ['class' => 'my_custom_class'],
 153             ],
 154         ],
 155     ],
 156     'tags' => [
 157        [
 158            'title'  => 'Code',
 159            'weight' => 50,
 160            'params' => ['url' => '/tag/code'],
 161        ],
 162        [
 163            'title'  => 'Zend Framework',
 164            'weight' => 1,
 165            'params' => ['url' => '/tag/zend-framework'],
 166        ],
 167        [
 168            'title'  => 'PHP',
 169            'weight' => 5,
 170            'params' => ['url' => '/tag/php']
 171        ],
 172    ],
 173 ]);
 174
 175 // Render the cloud
 176 echo $cloud;
 177 ```
 178
 179 The output:
 180
 181 ```php
 182 <ul class="zend-tag-cloud">
 183     <li class="my_custom_class">
 184         <a href="/tag/code" style="font-size: 50px;">Code</a>
 185     </li>
 186     <li class="my_custom_class">
 187         <a href="/tag/zend-framework" style="font-size: 20px;">Zend Framework</a>
 188     </li>
 189     <li class="my_custom_class">
 190         <a href="/tag/php" style="font-size: 23px;">PHP</a>
 191     </li>
 192 </ul>
 193 ```
 194
 195 ### HTML Cloud decorator
 196
 197 By default, the HTML cloud decorator will surround the HTML tags with a `<ul>`
 198 element and add no separation. Like the tag decorator, you can define multiple
 199 surrounding HTML tags and additionally define a separator. The available options
 200 are:
 201
 202 Option | Default | Description
 203 ------ | ------- | -----------
 204 `separator` | `' '` (a whitespace) | Defines the separator which is placed between all tags.
 205 `htmlTags` | `array('ul' => array('class' => 'zend-tag-cloud'))` | An array of HTML tags surrounding all tags. Each element can either be a string, which is used as element type, 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.
 206
 207 ```php
 208 // Create the cloud and assign static tags to it
 209 $cloud = new Zend\Tag\Cloud([
 210     'cloudDecorator' => [
 211         'decorator' => 'htmlcloud',
 212         'options'   => [
 213             'separator' => "\n\n",
 214             'htmlTags'  => [
 215                 'ul' => [
 216                     'class' => 'my_custom_class',
 217                     'id'    => 'tag-cloud',
 218                 ],
 219             ],
 220         ],
 221     ],
 222     'tags' => [
 223         array(
 224             'title'  => 'Code',
 225             'weight' => 50,
 226             'params' => ['url' => '/tag/code'],
 227         ],
 228         [
 229             'title'  => 'Zend Framework',
 230             'weight' => 1,
 231             'params' => ['url' => '/tag/zend-framework'],
 232         ],
 233         [
 234             'title' => 'PHP',
 235             'weight' => 5,
 236             'params' => ['url' => '/tag/php'],
 237         ],
 238     ],
 239 ]);
 240
 241 // Render the cloud
 242 echo $cloud;
 243 ```
 244
 245 The ouput:
 246
 247 ```php
 248 <ul class="my_custom_class" id="tag-cloud"><li><a href="/tag/code" style="font-size:
 249 20px;">Code</a></li>
 250
 251 <li><a href="/tag/zend-framework" style="font-size: 10px;">Zend Framework</a></li>
 252
 253 <li><a href="/tag/php" style="font-size: 11px;">PHP</a></li></ul>
 254 ```