EXT: A Better Tag Cloud¶

What does it do?¶

This extension can take content from (nearly) any table in the TYPO3 database, split it into words and create a tag cloud by counting the occurrences of each word. It offers a lot of flexibility for sorting, filtering and styling the results. It is also capable of handling multiple languages and workspaces.

The extension also provides a second plug-in to display a list of pages based on a list of page numbers associated with each keyword. The content of both plug-ins is cached properly.

Screenshots¶

Here is a screenshot of the result. A tag cloud...

Credits¶

The development of this extension was funded by the Geneva City Council. It was part of a workshop on TYPO3 extension development. Thus you will find that the source code is very clean and extensively commented. As such this extension may be useful as an example for other extension developers.

Note that since the initial development the TYPO3 Coding Guidelines have evolved and though this plugin is still pretty clean, it doesn't represent state of the art code anymore.

Questions?¶

If you have any questions about this extension, please ask them in the TYPO3 English mailing list (typo3.english), so that others can benefit of the answers.

Keeping the developer happy¶

It's unfortunately not possible to rate extensions anymore (maybe that will change again), so feel free to send thanks to the developers or praise the extension in general. If you really want to give something back, you may consider my Amazon wish list: http://www.amazon.co.uk/registry/wishlist/G7DI2AN99Y4F

You may also take a step back and reflect about the beauty of sharing. Think about how much you are benefiting and how much yourself is giving back to the community.

Installing the extension¶

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.

Upgrading¶

There are some minor issues to pay attention to when upgrading from older versions.

Compatibility¶

Since version 1.7.0, TYPO3 4.5 or higher is required.

General considerations¶

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).

Usage as a content element¶

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 three tabs. The properties that can be set in each tab are described below.

The only exceptions are the starting page and the level of recursing, which are set in the "Behaviour" tab of the content element.

The tag cloud will be assembled based on the selected pages and any children page encompassed in the “recursive” setting. If no starting point is defined, the default TypoScript setup will make it start from the root page of the web site. In case no TypoScript is defined at all, the tag cloud will take the current page as a starting point.

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).
• Unique keywords for each item: if this option is checked, a given keyword is counted only once in each item considered by the tag cloud. Example: you are building the tag cloud based on news title and have two news entitled “It's so good I could cry” and “Cry baby cry”. By default “cry” would have a count of 3 (1 in the first title and 2 in the second). By checking this box, “cry” counts only once in the second title and its total count is now 2.
• 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.
• Minimum word length: a minimum length for words to be included in the tag cloud. Any word shorter that the given number will be left out.
• 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”.
• Scaling (if using weights): choose a scaling method other than "linear" to smoothen or – on the contrary – enhance the differences between the weights of the various tags. This is useful when there are wide differences in weight or when a given word has an extraordinary weight compared to others. The picture below gives an idea of the effect of each setting.
• 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).

TypoScript

The last tab contains a single text field in which some TypoScript can be entered. This can be any TypoScript configuration that is described in the “Configuration” section below. It is entered without the plugin.tx\_vgetagcloud\_pi1 prefix (see example in screenshot above).

This TypoScript will override any values coming from the main TS template and also values defined in the other tabs of the FlexForm.

There are limits to what can be done inside this field. Actually the TS entered here is only parsed and merged with the main TS. This means that operator like >, <, =< and := will not work. This means that it is not possible to unset properties. They must actually be overridden by some other value. Empty values will override non-empty values.

Also note that conditions and constants cannot be used inside this field, although include files can.

Usage in a template¶

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.

Setting up a results page¶

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 search 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:

Done. There's nothing more to do here. Configuration is done using TypoScript.

TypoScript Constants¶

TypoScript Setup¶

TypoScript examples¶

Several values are available for use inside the tagWrap property. They are dynamically defined for each keyword. They are:

• tag_keyword: the keyword itself;
• tag_link: the id of the page to link to. Note: this value is the same for all keywords;
• tag_weight: the absolute weight of the keyword (i.e. the number of occurrences);
• tag_style: the relative weight or style from the list that apply to this keyword;
• tag_id: an incremented unique number that can be used if you want to place a “id” attribute on each keyword;
• tag_pages: a list of page numbers the keyword was found in, separated by underscores;
• tag_startpage: the id of the page chosen as a start page for collecting keywords (corresponds to the “Startingpoint” field or to the “startPage” TypoScript property). Note: this value is the same for all keywords.

Below are examples of use.

plugin.tx_vgetagcloud_pi1 {
        tagWrap {
                htmlSpecialChars = 1
                typolink {
                        parameter.data = field:tag_link
                        additionalParams.cObject = TEXT
                        additionalParams.cObject {
                                field = tag_keyword
                                rawUrlEncode = 1
                                dataWrap = &tx_vgetagcloud_pi2[pages]={field:tag_pages}&tx_vgetagcloud_pi2[keyword]=|
                        }
                        ATagParams.cObject = TEXT
                        ATagParams.cObject {
                                field = tag_keyword
                                htmlSpecialChars = 1
                                dataWrap = id="tag{field:tag_id}" title="|"
                        }
                        useCacheHash = 1
                }
                dataWrap = <li style="font-size: {field:tag_style}%">|</li>
        }
}

plugin.tx_vgetagcloud_pi1.cloudWrap.wrap = <!--TYPO3SEARCH_end--><ul>|</ul><div style="clear:both;"></div><!--TYPO3SEARCH_begin-->

plugin.tx_vgetagcloud_pi1 {
        tagWrap {
                typolink {
                        additionalParams >
                        additionalParams.field = tag_keyword
                        additionalParams.rawUrlEncode = 1
                        additionalParams.wrap = &tx_indexedsearch[sword]=|
                }
        }
}

plugin.tx_vgetagcloud_pi1 {
        referenceTable = tt_news
        referenceFields = keywords
        tagWrap {
                typolink {
                        additionalParams >
                        additionalParams.field = tag_keyword
                        additionalParams.rawUrlEncode = 1
                        additionalParams.wrap = &tx_ttnews[swords]=|
                }
        }
}

plugin.tx_vgetagcloud_pi1 {
    references {
        1 {
            table = pages
            fields = title,keywords
            where = doktype = 1
        }
        2 {
            table = tt_content
            fields = header
        }
        3 {
            table = tt_news
            fields = title
        }
    }
}

A note about word boundaries¶

In theory it is easy to split a block of text into single words. One needs only call the PHP function preg_split() and use the regular expression “b”. In practice it is not quite that simple, at least when using UTF-8 encoding. In this case b will split words on characters with diacritical marks (like “é” or “ü”) thus ruining the whole thing. In such a case it is necessary to be more specific, hence the TypoScript property “splitWords” to define which regular expression to use in preg_split() to find word boundaries.

The default value should cover most cases, but it is possible that you may have to modify it. Then again if you're just using English and no UTF-8 encoding, you may try to revert to simple “b”.

Note that the TypoScript property is included inside a single-quoted string and that single quotes and forward slashes inside the regular expression will be escaped for proper syntax. If you want to split words along backslashes too, you need to escape the backslash yourself (i.e. type “\”).

RealURL configuration¶

The extension includes a file for RealURL autoconfiguration. If you do not use this mechanism, it is still quite easy to set things up for the pi2 plug-in to work with RealURL. Here is an example configuration, but you may of course change it if you know what you're doing:

$TYPO3_CONF_VARS['EXTCONF']['realurl'] = array(
        '_DEFAULT' => array(
                'postVarSets' => array(
                        '_DEFAULT' => array(
                                'tagcloud' => array(
                                        array('GETvar' => 'tx_vgetagcloud_pi2[keyword]'),
                                        array('GETvar' => 'tx_vgetagcloud_pi2[pages]')
                                )
                        )
                )
        )
)

This will produce URLs like http://www.mydomain.com/tag-cloud- results/tagcloud/somekeyword/1_2_3 when calling the page where an instance of the pi2 plug-in resides.

Hooks¶

All hooks are listed below with their name and purpose. They all belong to the first plug-in (pi1).

• postProcessPages : this hook can be used to manipulate the list of pages from which keywords will be collected. It receives the list of pages as an array and is expected to return an array too.
• extractKeywords : this hook is used to register methods for extracting keywords from the raw data coming from the database. These methods are used instead of the default methods. They are expected to return simple arrays filled with keywords.
• postProcessRawKeywords : this hook allows the manipulation of the the full list of keywords before any sorting or capping is applied to it, but after case transformation. Methods called by this hook receive the list of all keywords and are expected to return a simple array with the full list of keywords.
• postProcessFinalKeywords : this hook is called just before the keywords are displayed and allows for a list-minute change. It receives the sorted and capped list of keywords, along with their count. It is expected to return an array with the same structure.
• processTagData : this hook comes in at an even later point and makes it possible to manipulate the cObj data just before the rendering is done. It receives a reference to the cObj data and can manipulate it at will. It returns nothing.

An example class for most of the hooks is provided in the file hooks/class.tx\_vgetagcloud\_hook\_example.php . For the the “extractKeywords” hook, the example method shows how to extract data from a flexform field, if such was chosen in the plugin's setup. For the “postProcessRawKeywords” hook, the example is a function that removes all keywords that are 2-letter long or less. One could also imagine, for example, removing all keywords that appear only once. The example for the “postProcessFinalKeywords” hook introduces a special sorting where keywords are arranged by length (rather useless, but looks nice).

The “processTagData” hook example shows how to link the tag cloud to extension “sg_glossary”. In the constructor of the tx\_vgetagcloud\_hook\_example class a list of keywords is loaded from the glossary. Then in the hook the keyword (as stored in tag\_keyword ) is matched against this list to retrieve the corresponding uid from the tx\_sgglossary\_entries table. This value is stored in a new field tag\_uid . To create the link to the glossary a simple modification is done to the TS setup:

plugin.tx_vgetagcloud_pi1
        tagWrap {
                typolink {
                        additionalParams >
                        additionalParams.field = tag_uid
                        additionalParams.wrap = &uid=|
                }
        }
}

Examples of how to register those hooks are found in the ext\_localconf.php file (the lines are commented out so that the example functions are not activated by default).