Skip to content

TagCloud 2.x

Jump to bottom
RomanPerin edited this page Sep 11, 2014 · 6 revisions

TOCSTART

TOCEND

The TagCloud component is used to display cloud of tags in several layout types.


Online Demo

Key Features

Specifying the Content

To add TagCloud component to the page, use the <o:tagCloud> tag. Then, set the source of items to required items attribute. As source of items you can use either a java collection or an array of objects of any type. Regardless of class which represents tag item, there are five properties of it, which you can set through the attributes:

  • The itemKey attribute specifies unique identifier of the item.
  • The itemText attribute specifies item's text. In addition, you are able use a converter for this attribute: just set one to the converter attribute.
  • The itemWeight attribute specifies weight of tag.
  • The itemTitle is rendered to the title attribute of html hyperlink.
  • The itemUrl should contain only EL expression that return an url string for each item. It will be rendered as href attribute of hyperlink.

Also, you can get access to the current item by request-scope variable, defined in var attribute.

Ordering

The TagCloud supports 5 different types of items ordering. Order in which items are displayed, is specified by order attribute. Available orders are given in the table below:

Values Description
"alphabetically" It's default order.
"original" In this case, component makes no ordering and display items as they are in the source.
"random" The TagCloud will show items randomly.
"weight" and "weightRevers" The TagCloud will sort items by weight ascending and descending.
Ajax and Server-Side Event Listeners

The TagCloud component allows you to trigger server-side actions with form submission or with Ajax (by click on tag item). Methods which will handle these actions should be specified in the action and/or actionListener attributes (to know the difference between these attributes, see the Ajax Framework documentation page). Naturally, these methods have access to the selected tag item as shown in an example below.

You can turn on the Ajax mode and configure the TagCloud to reload the specified set of components instead of reloading the whole page by specifying its render attribute. This attribute is specified as a space-separated list of component Ids in the same way as the render attribute of the Ajax component. Specifying this attribute will also make action and/or actionListener specified for the component to be executed during the Ajax request as well. If the Ajax mode is turned on it doesn't submit data for form's components for processing on the server by default, so if you'd like to include some particular components into the Ajax request, for their data to be available during action execution or be saved through bindings, you can specify the exeucte attribute. Like the render attribute, this attribute is specified as a space-delimited list of component Ids in the same way as for the Ajax component.

Here is the simple example of described features:

<h:form id="formID">
    <h:outputText value="#{ExampleBean.choosenTag}"
                  id="choosenTagOutputText"/>
    <o:tagCloud ... actionListener="#{ExampleBean.processAction}"
                    render="choosenTagOutputText" ... />
</h:form>

public void processAction(AjaxActionEvent event) {
    TagCloud cloud = (TagCloud) event.getComponent();
    Map<String, Object> requestMap = FacesContext.getCurrentInstance()
                                   .getExternalContext().getRequestMap();
    // Get the selected item
    ExampleItemClass item = (ExampleItemClass) requestMap.get(cloud
                                                         .getVar());
    // Set field that is defined as value of OutputText
    this.choosenTag = items.toString();
}
Client-Side Events

The TagCloud component supports a set of standard client-side events such as onclick, ondblclick, onmousedown, onmouseover, onmouseup, onmouseout, onmousemove, oncontextmenu. In addition, the TagCloud provides a component-specific onitemclick event which occurs when the user clicks on tag item.

Appearance

By default, every tag item is rendered without its weight, however, you can customize this option with boolean itemWeightVisible attribute. Also, you can configure weight displaying format with the itemWeightFormat attribute, which accepts java.text.DecimalFormat String patterns.

Layouts

The TagCloud component supports different layout types. Type of layout is specified by layout attribute that can take these values:

Values Description
"rectangle" In this case, cloud is rendered as rectangle of tag items. It's default layout.
"oval" Cloud is rendered as oval.
"vertical" Cloud is rendered as vertical stack of tag items.
"sphere" Cloud is rendered as 3D sphere, where you can customize a couple of parameters.
Sphere layout

Here are description of configurable properties of "sphere" layout.

      Attributes
Descriptions
rotationSpeed3D Speed of sphere rotation degrees per second.
shadowScale3D Coefficient of the text shadowing for the farthest sphere point. Value should lie in the interval from 0 to 1. In case of 1, the farthest item will have the same color as background, otherwise, if it's 1 then shadowing will be turned off.
stopRotationPeriod3D Time in seconds between mouseout and rotation stop. Can be a fractional number.
Customizing Styles

With the TagCloud component, you can define styles for the entire component as well as for individual tag items. The style-related attributes are given in the tables below.

Styles for the entire component:

Attributes Description
style and styleClass A style applied to the entire TagCloud component.
rolloverStyle and rolloverClass A style applied to the TagCloud component in the rollover state.
minItemStyle A style for the tag item with minimal weight.
maxItemStyle A style for the tag item with maximal weight.

All item-specific styles can be specified as a value-binding expression that uses variable specified in the "var" attribute. Here they are:

Attributes Description
itemStyle and itemClass A style applied to individual tag.
itemRolloverStyle and itemRolloverClass A style applied to individual tag in the rollover state.
itemTextStyle and itemTextClass A style for the tag item when mouse is over.
itemWeightStyle and itemWeightClass A CSS style class for item weight.
Clone this wiki locally