---

View Thumbnail Demo Using Servlets Data | View TagCloud Demo Using JSon Data | Download Source Code

---

Use this tutorial to understand how to use the Tag Cloud Wigdet and create tag clouds within your application.

A Tag Cloud (or weighted list in visual design) is used for visually depicting the tags you have used for various objects in your application. Tag Clouds are important as they are the most visible and attractive part of the tag concept, and help understanding tags.

In the demo, we use tag clouds to comprehend the trends in which data has been tagged, which data is most prevalent and least prevalent (illustrated by relative size), and the relation of the tags with each other. The demo alos illustrates editing, deleting and merging of tags in the tag cloud.

Terminology

A few terms you must know before reading the documentation on tag cloud.

Widgets

The widgets contain the basic building units for creating and managing the cloud tags and the dialog boxes displayed in the browser.

The tag cloud widget contains JavaScript files to create and manage the tag clouds, and also css files to style the tag cloud.

JavaScript Prototype Libraries

All the JavaScript files necessary for features such as effects, drag-and-drop, sliders etc. are stored in the directory, /libraries/prototype inside the tag cloud example.

These scripts are easy-to-use and cross-browser javascript libraries that provide different types of effects. These functions are called upon using the HTML script tags.

DataScripts

Tag Clouds can be created using a static array of tags, or retrieving the data from a database. To create datascripts using a database, you need to create tables in your database, query the database to grab the tags and build a data format (json array, xml or any other format of your choice), which is then returned to be used by the javascript.

HTML Files

HTML files are used to display the tag cloud in a web browser and connect to the data source files to retrieve the data by invoking javascript.

How to Use the Widget

This section helps you understand the Tag Cloud Widget, and the files used in this widget.

• Save the zip file, tagcloud.zip from the location, http://www.dekoh.org/widgets/tagcloud and unzip it into any location on your local machine.
• The unzipped folder structure looks like this:

Running the Demo on Dekoh Desktop

1. Store the tag cloud widget demo under an appropriate folder, for example the the public_html directory inside the Dekoh Desktop directory.
2. At the command prompt, navigate to the <DekohDesktop_Install_Dir>/server/bin directory by typing cd <install_dir>\server\bin
3. Start the Dekoh Desktop using the command, run_lw.bat
4. At the lwt prompt, deploy the tag cloud application.
5. To run the application, open your default browser and run the Index HTML page. You can now view the Tag Cloud created.

Understanding the Tag Cloud Widget

• The libraries/prototype folder contains the following JavaScript framework files to help ease development of dynamic User Interface. The files are:
  • builder.js
  • controls.js
  • debug.js
  • dragdrop.js - This script enables elements in your page to be dragged and dropped.
  • effects.js - This library has loads of functions for interesting effects.
  • extended_debug.js -
  • prototype.js - Prototype is a library that enables scriptaculous scripts to be nearly object oriented.
  • scriptaculous.js - This is the file that binds all other scripts together
  • slider.js - A slider is a simple fail-safe numerical input widget. You slide it up, the number goes up, you slide it down, the number goes down.
  • window.js
  • window_ext.js

• The web.xml file inside the WEB-INF is basically the web application deployment descriptor for your web application, and contains detailed information about your application. For example URL mappings, welcome files and so on.
• The widgets folder contains two widgets: dialog and tag cloud. The dialog widget contains a folder with images that will be displayed within the dialog box. The dialog.js file in this folder is used to modify the window object to adjust the top-bar and bottom-bar of the dialog box. It also provides customized positioning for the dialog status message and creates sub-dialogs to the main dialog.

To understand this better, read about the Prototype Window class.

• The tagcloud.js declares two important classes (a) roTagCloudDataSource: Read Only DataSource and (b) wTagCloudDataSource: Writable DataSource. Depending on the access you have to your database, you extend the required class in your interface-xyz.js file. In the demo provided (explained in the next section), we have extended the writable class of the datasource object.
  

Note: Ensure that you declare the methods inside all these class definitions as blank methods. These methods are later extended in the interface-xyz.js file.

• The dialog.css file is used to style the dialog box widget.
• The folder widgets/tagcloud contains the tag cloud widget. The file, tagcloud.js utilizes the tag cloud databse provided by the interface file and defines all the main functionalities for the tag cloud such as selecting tags, editing tags, adding tags, deleting tags and so on. This file also defines functions to return the font size depending on the frequency and rank of the tag. The container element is where the tag cloud is drawn into, and the contentdiv is the identifier of the div holding the actual HTML tags.
• The file, tagCloudDialog.js file opens the tag cloud dialog with the help of the file, window.js stored under the lib directory, and builds the header message for the dialog box. This file opens the appropriate dialog box, depending on whether the user wants to edit or select tags.
• The widget.css file defines the tag cloud styles.

Demo Files in the Tag Cloud Widget

If you notice, the tagcloud.zip also ships with sample files to display basic tag cloud applications using JSON and XML. These files are placed at the root directory. The sample datascript files, tagcloud_json_exampledata.js and tagcloud_xml_exampledata.xml have been created using a database. You may use these files and modify the scripts to create a tag cloud with static data, or create your own dynamic data script using a database.

DataScript Format

Sample datascript for JSON

	var jsonResponse = new Array();
	var rCount=0;
	jsonResponse[rCount++] = {created:'1171020448890',freq:'170',rank:'100',tagtitle:'photography'};
	jsonResponse[rCount++] = {created:'1171111779109',freq:'136',rank:'80',tagtitle:'nightNikon'};
	jsonResponse[rCount++] = {created:'1171020449328',freq:'80',rank:'47',tagtitle:'macro'};
	jsonResponse[rCount++] = {created:'1171020449015',freq:'79',rank:'46',tagtitle:'flickr'};
	jsonResponse[rCount++] = {created:'1171020448890',freq:'78',rank:'45',tagtitle:'lattimore'};
	jsonResponse[rCount++] = {created:'1171020448953',freq:'77',rank:'45',tagtitle:'dlattimore'};
	jsonResponse[rCount++] = {created:'1171020449078',freq:'77',rank:'45',tagtitle:'deborahlattimore'};
	jsonResponse[rCount++] = {created:'1171020448875',freq:'77',rank:'45',tagtitle:'ddlatt'};
	jsonResponse[rCount++] = {created:'1171020449562',freq:'73',rank:'42',tagtitle:'wow'};

Sample datascript for XML

	<tag created="1171020448890" freq="170" rank="100" tagtitle="photography" />
	<tag created="1171111779109" freq="136" rank="80" tagtitle="nightNikon" />
	<tag created="1171020449328" freq="80" rank="47" tagtitle="macro" />
	<tag created="1171020449015" freq="79" rank="46" tagtitle="flickr" />
	<tag created="1171020448890" freq="78" rank="45" tagtitle="lattimore" />
	<tag created="1171020448953" freq="77" rank="45" tagtitle="dlattimore" />
	<tag created="1171020449078" freq="77" rank="45" tagtitle="deborahlattimore" />
	<tag created="1171020448875" freq="77" rank="45" tagtitle="ddlatt" />
	<tag created="1171020449562" freq="73" rank="42" tagtitle="wow" />

Important: When you create datascript files for your application, you must follow the given formats:

• created: Returns the epoch time when this tag was created.
• freq: Returns the frequency or the number of times the tag has been used.
• rank: Returns the relative significance rank for the number of times the tag is used.
• tagtitle: Returns the title of the tag created.
• The two sample javascript files, interface-json.js and interface-xml.js extend the tag cloud data source, retrieve the tag cloud objects, and store all the tag details (add, delete, edit, merge etc.) into arrays. These files are also used to return and save these values into the database.
• These files, interface-json.js and interface-xml.js are separate from the actual tag cloud class. The datasource (interface-xyz.js file) and tag cloud (tagcloud.js) has separate responsibilities. The former interacts with the server while the later ansynchronously handles everything in the user interface.
• The two sample HTML files, tagcloud_json_example.html and tagcloud_xml_example.html are used to display the tag cloud on a web browser. The HTML file loads the prototype script files, connect to the data source, creates the tag cloud with the default view, sets the widget defaults, and also calls the right dialog box, when the user clicks "Tag Cloud In Dialog Edit Mode" or "Tag Cloud In Dialog Select Mode".
• The lines of code

var datasource = new jsonTagCloudDataSource(jsonResponse,"#@@#"); 

and

var datasource = new xmlTagCloudDataSource("tagcloud_xml_exampledata.xml","#@@#"); 

is where we define a variable named jsonTagCloudDataSource and xmlTagCloudDataSource and pass parameters, jsonResponse and tagcloud_xml_exampledata.xml to the variable. This returns a formatted XML document as response to the variable, which contains all the tags that the widget will create the tag cloud with.

Creating a Tag Cloud for your Rails Project

Integrating Tag Cloud widget With your Rails Project

License

See Dekoh Widget License for more details.

Attachments