Quick Start

1. Install the addon
2. Add a Word Cloudify block to a page

Congratulations! You now have a working Tag Cloud on your page!

Installation

The recommended method to install, is simply using your target website marketplace page. However, if you wish not to use concrete5 internal feature, you can follow the next instructions :

1. Download the zip archive
2. Uncompress the zip archive into your packages/ directory
3. Visit your Add Functionality page (located at http://yoursite.com/index.php/dashboard/extend/install)
4. Click on the Install button

After installing  (either through downloading or preferably directly through your concrete5 website interface), you will be provided with a new block Word Clodify in the Social Networking block set.

Word Cloudify block

Simple Usage

Adding a Cloud

To add a word cloud to your page, just add the

block to your page (in edit mode). You will be presented the add/edit dialog:

add/edit dialog

The block is initially configured to display a cloud of all existing tags (all site page) and redirect clicks on those words to the search page (using the tag as a search keyword). Off course all those options (and many more) can be changed from the edit dialog, each tab being described in the following sections.

All Source configuration happens in the Tags Source tab:

add/edit dialog (Tags Source tab)

Configuring Sources

Words displayed on the cloud can come from various sources. All sources are computed from the site, then words are counted, and assigned a weight depending on the number of occurrences the word is found in the total of all words gathered in those sources (frequency).

 can gather words from a variety of content:

• Page Tags: from page 'tags' attribute
• Pages summary, from the page summary (or description)
• Page Main Area Content rendered from the page Main area,
• Manually Entered Text,
• Manually entered list allowing sizes, link and colors to be specified

In all but the last case, words are gathered and then counted to assign a specific weight based on their frequency. The Source type can be chosen on the Tags Source tab.

In case words are gathered from the site content, you have the ability to select which pages this content is gathered from:

• All site PagesAll pages (without distinction)
• Pages directly under this page Immediately Under the current page (first children)
• All pages under this page that is, all pages under the current page (at any level)
• Pages directly under another page (to be selected) Immediately under a specific page (first children)
• All pages under another page (to be selected) all pages under specific page
• Only the current page
• Only a specific page

For all selections involving multiple pages (that is, all except the last two), the selection can then be further restricted to specific page types. The page types are computed from the concrete5 installation directly, so all currently installed page types are supported for filter.

In case the selection requires a specific page (or base page), a page selector will be displayed allowing its selection.

Here is an example of a block configured to pull content from pages tags of all pages directly under the "Search" Page:

Example of restricted selection

The number of words shown in the cloud can be limited to a specific amount by setting the number in the first selection "Get ...". If this number is empty or 0, all words will be shown. (By default this is set to 200). The selected words will be the words with the higher frequency in the analysed content.

Finally a comma separated list of word can be entered to exclude specific words from the result (this is particularly useful when analysing a human text, where all articles such as 'the', 'a', etc... would show up with a high frequency, completely clobbering the cloud instead of more important but a little less frequent words).

Configuring Behavior

The word cloud can be configured to redirect users in a various way upon click:

Add/Edit dialog (Behavior tab)

• Redirect to url
• Redirect to a page

In the later case, a page selector will allow to select a specific page.

Next, the word being clicked on can be sent to different targets:

• Search in site (query) to the core search block
• Search in page tags to the core search block again
• Use a custom variable to a custom variable name in the GET request
• No search to not send the word at all

In case the word is configured to be sent to the tags search, it is possible to add it to a custom variable too by selecting the Add custom variable option.

Here is an example of such behavior

Example of search to tags behavior with custom variable

Configuring Display

 offer a fully configurable effect:

Add/Edit dialog (Display Options tab)

By default, words frequency is calculated by ignoring the case (upper-cased, lower-cased or mixed-cased words are counted together). Words are then displayed with a case matching their first occurrence in the pulled content.

This behavior can be disabled by deactivating the case insensitive option.

Moreover, words can be made upper case in the display by ticking the make words upper case option

After being counted to calculate their frequency, words can be sized (within the font size range, see bellow) according to their frequency along different scaling methods:

• Linear
• Logarithm (default)
• Square Root
• Random

In the case of the Random scaling method, the frequency will be ignored.

The block geometry can be set by changing the X and Y fields (Geometry). Currently, the geometry can only be set in pixels (px), responsive geometry is not yet supported).

Words are randomly rotated at various angles specified within the range in degrees (along a specific number of steps). The default is to rotate words along 5 steps from -60° to 60° (that is -60°, -36°, -12°, 12°, 36° and 60°). Beware though that crossing 90° or -90° will result in reversed words that could be hard to read for the visitors.

Words are sized accordingly to the scale chosen and their frequency in the content analysed. The scaling happens within the range of the font size boundary specified in pixels.

Words color can be selected between various options:

• D3 category 20                     
• D3 category 20B                      
• D3 category 20C                     
• D3 category 10                     
• Gradient A gradient between two selectable colors
• Monochrome Single color (selectable)
• Bi-colored Two Colors (selectable)
• Inherit from CSS No color set, will take the color of parent

When selecting a color scheme, a preview of the range will be shown in the dialog.

Within the color range, the color can be selected following the word index (by order of appearance in the pulled content), or according the word size (weight), that is, according to the word frequency (low frequency on the left, high frequency on the right).

Here are some example of clouds with different color scales:

Example of clouds, using d3 color 20 (left) and a custom gradient (right)

Basic Cook Book

1. Add the block to the page
2. Select the Page Tags as a source
3. Select the search options (either all pages or anything specific)
4. Save the block

1. Create your cloud
2. select the "cache tags" options (in the Advanced Options Panel)
3. save the block
4. edit the block again
5. set the tag source to "Manually entered list (advanced)"
6. edit all the properties you want in the array

Advanced Usage

Advanced Options

Add/Edit dialog (Advanced option tab)

The advanced options allow the following configuration:

• Load Effect if deactivated, no rotation effect will be shown
• Load D3.js deselect only if d3.js is already loaded
• Use local d3.js allow switch between local or remote version (on d3js.org)
• pre-calculate if selected, calculate the word sizes/color on the server not the client
• shuffle words shuffle words before display (only effective without effect loaded/IE8)
• cache tags only pull content and calculate tags on block save
• enforce block size will force the block geometry (only effective without effect loaded/IE8)

Creating a Custom Cloud

As mentioned earlier in this documentation, words are calculated from content pulled or from a manual list.embeds a grid editor to allow the cloud to be defined word by word:

Advanced list edition

Using this interface, each word can be specified, including its size, link, and color. The link field can also hold a specific javascript code to run (using the href syntax). To change a color, click on the color itself and a color editor will be opened.

Here is an example of custom edited cloud:

Example of custom cloud

Custom Cloud from an Existing One

If you want to create a custom cloud from an existing (non custom) cloud, and not have to re-enter every single word/properties, you can do it following these simple steps:

1. Create your cloud (the template one)
2. select the "cache tags" options (in the Advanced Options Panel)
3. save the block
4. edit the block again
5. set the tag source to "Manually entered list (advanced)"
6. edit all the properties you want in the array

Trouble Shooting

Browser compatibility

This addon creates an SVG inline image. All major browsers now support inline SVG images, but that was not always the case for old ones. For this reason, the effect is not loaded on IE8. Visitors using IE8 will be presented graceful degradation of the effect:

Example of cloud shown to IE8 visitors

All other behavior/display options (eg: gradient colors, redirect, links, size etc...) are still compatible with IE8 and will display properly. Also, you may want to use the Shuffle Words option so show a more random display to those visitors.

To check how your block would look for older browsers, you can untick the Load effect option in the Advanced option pane.

Missing words

Words are sized according to their frequency (if you are using a non manual list), or according to the size you enter in the advanced custom editor. In case a word, once sized and displayed on the SVG image, is bigger than the image itself, it is clipped away from the image.

To prevent this from happening you can change the range of font size (display options) or adjust the image size directly.

Slow Loading

If you experience slow loading, you may want to use the local version of d3.js. From some countries (eg: China), loading external javascript resources on shared server located abroad considerably slow down the page loading. (see Advanced Options for more information).

Credits

This addon embeds the js plugin created by Jason Davies, (released under MIT license) and available here http://www.jasondavies.com/wordcloud

Requests and Support

You can contact me for support or question through the Concrete5.org PM system, or you can use the support system builtin. I usually answer within the hour if I am online, or within 1 business day otherwise. (Please just keep in mind that we might sit in different timezones which might end up in me answering you while you sleep ...).

Need a feature ? need to make sure you can use this addon in a specific situation, just ask!