Kentico CMS 7.0 Developer's Guide

Using the Tag cloud web part

Using the Tag cloud web part

Previous topic Next topic Mail us feedback on this topic!  

Using the Tag cloud web part

Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic!  

The Tag cloud web part is used to display tags that are associated with the current document. Tags are displayed in the form of links and those with higher occurrence are displayed in higher font size. If the site visitor clicks on some of the links, a list of all documents tagged with the given tag will be displayed.

 

devguide_clip0724

 

The web part has the following specific properties:

 

Tag filter

Site name

Code name of the website from which you want to display the tags. If you leave the value empty, the content is retrieved from the current website.

Tag group name

Name of the tag group from which the tags will be displayed.

Select top N tags

Number of tags which will be displayed. Top tags according to the order specified by the ORDER BY expression property will be displayed.

ORDER BY expression

ORDER BY part of the SQL query used to retrieve the tags.

Tag cloud settings

Document list URL

URL of the page on which the documents list will be displayed after clicking some of the tags (see below for an example).

Query string parameter name

Name of the parameter by means of which the tag ID will be transferred.

Tag separator

Separator that will be placed between tags in the tag cloud.

Minimal tag font size

Size of tags with the lowest occurrence.

Maximal tag font size

Size of tags with the highest occurrence.

Document filter

Use document filter

Indicates if the document filter will be used. If true, the web part will display only tags used in the documents specified by the properties below.

Path

Path of the documents the tags of which will be displayed by the web part.

Combine with default culture

Indicates if tags from the default language version of the document should be displayed if the document is not translated to the current language.

Culture code

Culture version of the displayed tags.

Maximum nesting level

Maximum nesting level. It specifies the number of sub-levels in the content tree of the document specified by the Path property that should be included in the displayed content (i.e. whose tags will be displayed).

Select only published

Indicates if only tags from published documents should be displayed. Applied only when 'Site name' or 'Alias path' property is defined. If disabled, all tags from the selected tag group will be displayed.

Where condition

WHERE part of the SQL query used to retrieve tags.

 

Common usage

 

The Tag cloud is designed to "work in pair" with some repeater web part. When a tag link is clicked in the tag cloud, a list of all documents tagged with this tag is displayed in the repeater. The repeater can be placed either on the same page as the tag cloud or on some other page to that the site visitor will be redirected. You can see an example of this behavior on the Corporate Site sample website under Examples -> Web parts -> Tagging & Categories -> Tag cloud.

 

devguide_clip0727

 

In order for the two web parts to cooperate correctly, you have to correctly set some of their properties:

 

Tag cloud:

 

The placement of the repeater is defined by the Tag cloud's Document list URL property. In case that the repeater is placed on the same page as the tag cloud, the value should be left blank. In case that it is placed on some other page, you should enter the alias path of that page.

 

ID of the clicked tag is transferred to the repeater in form of a query string parameter. The name of the parameter can be set using the Query string parameter name property. The repeater displays the appropriate list of documents based on the value that it gets by via this parameter.

 

Repeater:

 

Set the value of the Path parameter to the location in the content tree where the documents are stored.

 

Set the value of the Document types parameter to the document type(s) that is (are) to be displayed.

 

Select the transformations that you want to use for the Transformation and Selected items transformation.

 

Finally, use the following code as a value for the repeater's WHERE condition parameter. The tagid value should be replaced by the name set in the Tag cloud's Query string parameter name:

 

({?tagid|(toint)?} = 0 AND '{?tagname?}'='')

OR (DocumentID IN (SELECT DocumentID FROM CMS_DocumentTag WHERE TagID = {?tagid|(toint)?}))

OR (DocumentID IN (SELECT DocumentID FROM CMS_DocumentTag WHERE TagID IN (SELECT TagID FROM CMS_Tag WHERE TagName = '{?tagname?}' AND TagGroupID = {?groupid|(toint)?})))

 

The first line ensures displaying of all documents when no query string parameters (tagid nor tagname nor taggroupid) are received. The second line ensures displaying of documents based on the received tagid (or differently named parameter) from a Tag cloud web part. The third line ensures displaying of documents based on the received tagname and groupid from a blog post's Filed under section.

 

devguide_clip0731

 

If you would like to learn more on the use of the Tag cloud web part, please refer to Community Site Guide -> Part 2 -> Pre-development tasks -> Creating the tag groups. This is a step-by-step tutorial on how to create a tag group.

 

If you would like to see examples of how the Tag cloud web part is added to the site, please refer to:

 

Creating the Blogs section -> Creating the Blogs page in the same section of Community Site Guide

Creating the Blog posts page

Creating the News page

 

You will need to have the Community Site sample website installed to follow Kentico CMS Community Site Guide.