The installation is a pretty straightforward business:
download and install the extension using the Extension Manager
include the extension's static TS template into your template
- insert the tag cloud as an element on your page or via TypoScript to have it appear on a bunch of pages.
Before diving into the plug-in's options, it is important to understand how the data for the tag cloud is gathered and compiled, and what is done afterwards with it for rendering the actual tag cloud.
Data is fetched from one or more fields from a table inside the TYPO3 database. Only tables that are referenced in the TCA are available for selection. Similarly only columns (fields) form those tables that have a TCA description can be selected. The data gathered can be limited by selecting a starting point in the TYPO3 page tree.
Depending on which field is chosen, the data may either be single keywords or complete texts from which keywords must be extracted. So the plug-in's next work is to split the data into individual words. This list is then parsed and every occurrence of the same word is added to a running total. The result is a list of unique words with a number of occurrences for each. This is referred to as “weight” in the rest of this manual.
This weight is of course of utmost importance since the whole point of tag clouds is to highlight words according to their importance. The weight is thus used in the styling process when rendering the tag cloud. Two styling processes are available. The first one uses relative weight boundaries (defaults are 100% and 200%) which are directly used as font size attributes. According to its weight, a word receives a relative size somewhere between the minimum and maximum weight boundaries.
The other display possibility is using a list of predefined styles. For example if you define four styles, the words will be split into four weight groups and attributed the corresponding style.
How those weights and styles are actually used all depends on the TypoScript configuration.
Inside the tag cloud, each keyword is actually linked to a page. The same page is used for all keywords, but of course query parameters may vary. The default setup of the first plug-in (pi1) makes it ready to link to a page containing the second plug-in (pi2).
A Better Tag Cloud can be inserted as a traditional content element on a page, just like any other plug-in. Just choose the right type either from the plug-ins list in the content element form or from the new content wizard.
Most of the parameters can then be set using the provided flexform. A few special parameters can only be set using TypoScript (see Configuration). The flexform is split into two tabs. The properties that can be set in each tab are described below.
On top of the tab, you may want to define a starting point and a level of recursing.
General Setup
Reference table: choose the table from which you want to draw keywords.
Reference fields: choose one or more fields from the table selected above.
Include not in menu pages: choose whether to includes pages that are not in menu (when querying the pages table) or elements in pages that are not in menu (when querying the tt_content table, for example, on any other record that has a pid field).
Character for splitting field(s) value: define which character to use to split the values found in the selected fields into individual keywords. For example, if you choose the “keywords” field of the “pages” table, you have to define the comma as a separator. By default, no separator is defined, which means the field(s) will be split along word boundaries (however see “A note about word boundaries” in the Configuration section).
Case handling: define whether keywords should be left as is or converted to lower or upper case. Note that if keywords are left as is, they will be differentiated based on case. For example, “typo3” and “TYPO3” will appear as two different tags in the cloud. The default behavior is to convert all words to lower case.
Target page for tag links: choose the page the links on each tag should point to. This may be, for example, the page with the second plug-in (pi2) or the search results. Note that choosing a page is only part of the task. The actual links are built using TypoScript (see Configuration). The target page can also be defined globally by editing the plug-in's constants.
Sorting (before capping): you may limit the number of words that appear in the tag cloud (see below). However before cutting off the list of keywords you may want to sort them using this property. Possible values are natural (i.e. nothing), alphabetical or by weight (i.e. the number of occurrences of each keyword). The default is by weight.
Sort order: this property complements the previous one by allowing to choose an order for sorting. The default is descending (so highest goes first).
Maximum number of tags: set the maximum number of keywords that should appear in the tag cloud. An empty field (or a value of zero) means that all keywords get displayed.
Format & Style
Type of styling: choose to use styles or weights (if this is not clear, please refer to the General considerations above).
Minimum weight (if using weights)/Maximum weight (if using weights): define limits for the weights to be used. These fields support only numbers. Do not enter units here. Units belong to the TypoScript configuration. However those units condition what kind of value you need to enter here. If using percentages, you will want to enter values like “100” and “200”. If you use “em”, you will want to enter something like “1” and “2”.
List of styles, comma-separated (if using styles): list the name of the styles you have prepared in your CSS.
Separator: define some characters that you may want to insert between each keyword.
Sorting (for display): define the sorting of the keywords for the rendering. The default is alphabetical.
Sort order: this property complements the previous one by allowing to choose an order for sorting. The default is ascending (so lowest goes first).
It is possible to include the tag cloud in a template to have it displayed on a bunch of or even all pages of your web site. Simply include it as appropriate for the templating system that you use.
Here is an example for the traditional templates:
temp.cloud < plugin.tx_vgetagcloud_pi1
temp.cloud {startPage.data = leveluid: -2
recursive = 2
}
page.subparts.TAGCLOUD < temp.cloud
The same for TemplaVoilà:
lib.cloud < plugin.tx_vgetagcloud_pi1
lib.cloud {startPage.data = leveluid: -2
recursive = 2
}
then define a TemplaVoilà element as a TypoScript Object Path and set it to point at lib.cloud.
Although it is possible to imagine the tag cloud existing all by itself, the general use of such a tool is to be able to click on a given keyword and get a sensible result. This means that the links on each keyword must point to a page which knows what to do with the information that is passed to it. There are many ways to achieve that:
pass the keyword in a “tx_indexedsearch[sword]” variable and point to a page with the indexed search engine. This will trigger a search using the keyword;
something similar can be done with news, by passing the keyword inside a “tx_ttnews[swords]” variable and pointing to a page with the tt_news search engine;
pass the list of pages on which the keyword was found to a page containing the second plug-in. This will display those pages as a list.
using the TypoScript setup or some of the hooks it is possible to link to many other extensions. See the chapter on hooks for an example of how to link to a glossary extension.
The various TypoScript setups for such results pages are detailed in the “Configuration” chapter.
To set up a page with the indexed or the tt_news search engines, please refer to the manual of those extensions. To use this extension's second plug-in (pi2), just create a new content element and select the appropriate plug-in from the wizard:
