plug-in 1

[tsref:plugin.tx_vgetagcloud_pi1]

-> referenceConfigs

[tsref:plugin.tx_vgetagcloud_pi1.referenceConfigs]

plug-in 2

[tsref:plugin.tx_vgetagcloud_pi2]

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

Below are examples of use.

Default setup

The default value of the tagWrap property makes use of most of the special values introduced above:

plugin.tx_vgetagcloud_pi1

tagWrap {

typolink {

parameter.data = field:tag_link

additionalParams.dataWrap = &tx_vgetagcloud_pi2[pages]={field:tag_pages} &tx_vgetagcloud_pi2[keyword]={field:tag_keyword}

ATagParams.dataWrap = id="tag{field:tag_id}" title="{field:tag_keyword}"

useCashHache = 1

}

dataWrap = <li style="font-size: {field:tag_style}%">|</li>

}

}

Let's look at the above code in detail. First of all we define the link that should be placed around the keyword using the typolink property. The target of the typolink is set using the tag_link special value, since it contains the number of the page to link to. Then we define additional parameters to add to the link. It should use the tag_keyword value (which contains the keyword itself) and set it as the value of the tx_vgetagcloud_pi2[keyword] query parameter. The same goes for tag_pages which is used as the value of tx_vgetagcloud_pi2[pages]. This second parameter is the critical one. Without it, the results page will not know what pages to display. The first one (keyword) is only important if you want to display the keyword as a reminder.

What is more, we add a unique id attribute to the A tag thanks to the tag_id special value and repeat the keyword itself in the title attribute. Lastly the link is wrapped inside a list item, on which the relative weight is applied as a percentage of font size, using the tag_style special value.

Note the activation of useCacheHash in the typolink setup. This is necessary because the link refers to the pi2 plugin which is cached (its type is USER). If the useCacheHash is not enabled you risk running into the empty cHash problem (if you don't understand what this is all about, please refer to the article, “The Mysteries of &cHash”, http://typo3.org/development/articles/the-mysteries-of-chash/).

The wrap around the cloud completes the setup:

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

All tags are wrapped inside an unordered list and search engine markers are set so that the tag cloud is not indexed. The default styles provided by the extension ensure that the tags are displayed as floating elements and not as actual list items.

Linking to the indexed search engine

Using the individual keywords from the tag cloud to launch a search is very easy. Little configuration needs to be changed from the default setup.

plugin.tx_vgetagcloud_pi1

tagWrap {

typolink {

additionalParams >

additionalParams.data = field:tag_keyword

additionalParams.wrap = &tx_indexedsearch[sword]=|

}

}

}

Of course the destination of the typolinks must be a page containing the indexed search plug-in.

Linking to tt_news and TIMTAB

This example shows how to build a tag cloud based on tt_news. This means this method can also be used for basing a tag cloud on TIMTAB entries. Very little needs to be changed from the default setup.

plugin.tx_vgetagcloud_pi1

referenceTable = tt_news

referenceField = keywords

tagWrap {

typolink {

additionalParams >

additionalParams.data = field:tag_keyword

additionalParams.wrap = &tx_ttnews[swords]=|

}

}

}

With this each keyword will start a tt_news search. Of course, the links on the keywords must point to a page containing the tt_news plug-in with code SEARCH.

Querying multiple tables

The tag cloud can be built using data from multiple tables. This can only be achieved using TypoScript and not with the FlexForm configuration. Here is an example of such setup:

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        }    }}

In this example code we decide to query three tables: the pages, the content elements and the news items. In the pages table, we will use the title and keywords fields, the header field of content elements and the title field of the news items. Furthermore the pages are restricted to being only of doktype = 1. This will be added to the WHERE clause of the SQL query that will run on the pages table.

Precedence of FlexForm and TypoScript

FlexForm settings always override TypoScript set up. The only exception to that is when querying multiple tables. In this case, the TypoScript property “references” is used no matter what values are entered into the FlexForm “Reference table” and “Reference fields” selectors.

Consistency between pi1 and pi2

Depending on your setup you must take care to ensure consistency between the pages found by pi1 and the pages displayed by pi2. In the latter the default rendering for the list of pages uses a HMENU content object. This object takes care of all the hassle of enable fields (hidden, deleted, access restrictions, publication dates), language overlay and versioning. The pi1 code does the same. But the HMENU object is also going to respect the “Not in menu” field. This is why the default pi1 setup excludes those pages (includeNotInMenu = 0). If you change this setup, you must also change the HMENU in pi2 to display the pages that are not in menu (results.includeNotInMenu = 1).

The “includeNotInMenu” property in the pi1 plug-in is also important, for example, when retrieving your keywords from content elements. With the default settings, the pi1 plug-in will not reference content elements on pages that are not in menu. That way when the pi2 is called, the results are coherent. If you want to take words also from not in menu pages, you have to set includeNotInMenu to 1 in both plug-ins setup.

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 “\\”).

It is 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 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.