ko-tagCloud

A tag cloud creator using SVG and KnockoutJS.

Features

The example uses KnockoutJS custom bindings. But the tagCloud.js can be used without KnockoutJS too.
Dependent on Scalable Vector Graphics.
Lightweight - 7kb.
Simple, well documented and easy to use.

Usage

<head>
  <!-- KnockoutJS is required only if ko_click option is used -->
  <script type="text/javascript" src="https://github.com/SamratK/ko-tagCloud/raw/master/knockout-3.4.0.js"/>
  <script type="text/javascript" src="https://github.com/SamratK/ko-tagCloud/raw/master/tagCloud.js"/>
</head>

API

Calling the TagCloud function with parameters will generate a tag cloud and append it to the 
element with given id. The parameters are :-
id - HTML element id.
data - javascript array of JSON objects with data for tag cloud elements.
parameters - JSON object with tag cloud level settings.
TagCloud(element.id, data, parameters);

parameters argument

This is an optional argument. If skipped, all values will be set to defaults.

Option	Value	Default	Description
width	Any value allowed for SVG container	500	The given value for width or default value of 500 is treated as maximum width of the tag cloud. After the elements are created the space is optimized. If the elements seem to overflow then the value and/or the element weightage can be adjusted.
height	Any value allowed for SVG container.	500	The given value for height or default value of 500 is treated as maximum height of the tag cloud. After the elements are created the space is optimized. If the elements seem to overflow then the value and/or the element weightage can be adjusted.
bgColor	Value in format #ffffff or rgb(255,255,255).	rgb(255,255,255)	This option sets the background color of the tag cloud.
fill	Value in format #ffffff or rgb(255,255,255).	rgb(0,0,0)	This option sets the text color of all the tag elements in the cloud. It can be also set on specific cloud element.
font-family	Name of font family like Arial, Calibri etc.	Helvetica Neue,Helvetica,Arial,sans-serif,Impact	This option sets the font family of all the text elements. It can be also set on specific cloud element.
weightage	Value between 1 - 5. Decimal numbers are also allowed.	30	This option sets the font size of all the text elements. It can be also set on specific cloud element. It is recommended to set this option on specific element so that they are displayed as per their prominence.
font-weight	Values allowed for font-weight of SVG text element.	400	This option sets the font weight of all the text elements. This will set the value for boldness of the text. It can be also set on specific cloud element.
font-style	Values allowed for font-style of SVG text element.	normal	This option sets the font style of all the text elements. It can be also set on specific cloud element.
font-stretch	Values allowed for font-stretch of SVG text element.	normal	This option sets the font stretch of all the text elements. It can be also set on specific cloud element.

data argument

This is a required argument. The data argument should be a javascript array with JSON objects with following options :-

Option	Value	Description
url	href of a link. Eg. http://www.github.com	With the value of url an anchor element will be created around the given text of the could element. On clicking the element, the page will navigate to the given url.
target	Target of the anchor element. Eg. _blank, _self, _parent etc. Default value is _top.	The url will be loaded as per the target value. This option is only used when url option is set.
onclick	Name of the function to be called, on clicking the tag cloud element.	This option is to be used when url option is not set. Instead of loading a page, the click action will be sent to a function. Eg. function setContentOfPage(){ //Code to set content of page based on //clicked tag cloud element. } //cloud element JSON inside array should be cloudElement = {......."textContent":"GitHub" , "onclick" : "setContentOfPage"........}; //the text element in tag cloud will be created as - <text ..... onclick="setContentOfPage('GitHub',this);" ......> GitHub </text> As given above, the function with given name will be called by passing the textContent of that element and also the text element itself so that other properties of it can be read.
ko_onclick	Name of the knockout function to be called, on clicking the tag cloud element.	This option is to be used when url option is not set. Instead of loading a page, the click action will be sent to a knockout function. Eg. function tagCloudViewModel (){ var self = this; ........ self.setContentOfPage = function(){ //Code to set content of page based //on clicked tag cloud element. } ....... } ko.applyBindings(new tagCloudViewModel()); //cloud element inside data array should be cloudElement = { ......."textContent":"GitHub" , "ko_onclick" : "setContentOfPage" ........}; //the text element in tag cloud will be //created as - <text ..... data-bind="click : setContentOfPage" ......> GitHub </text> As given above, a knockout click binding will be created with the given function name. Knockout will call the function with data and event arguments from which the clicked element can be identified.

Screenshot

Current style of the tag cloud is rectangular. The elements are sorted in descending order of their weightages.

Notes

As mentioned above, the tag cloud generator code optimizes the space. Example, let the bounds be given as width : 400 and height : 400. And the text elements are given with respective weightages. The code will create the tag elements with SVG texts. After creating, the code will check if there is extra space around the tag elements and then re-sizes the SVG container accordingly by adjusting the height and width attributes of SVG element. So the given bounds will be taken as maximum bounds. If the user wants the tag cloud to be of fixed bounds on the page, then one can use a container element like <div> tag with the required bounds. And let the SVG tag cloud be created inside it.
The weightages of elements based on which their size depends can be adjusted to match the requirement of the user. Optimum display for the elements on the page can be obtained by a little experimentation.
If the page is required to follow a responsive design, which means that on re-sizing the browser, the tag cloud should also be re-sized then the user can have it handled in a function which can detect resize events and then call the TagCloud function to recreate the elements. User can have the weightages to be dynamically scaled as per the changed bounds so that all elements fit inside the container and get displayed properly.

SamratK / ko-tagCloud

readme