Word Cloud API

General

A word cloud is a tool that represents the frequency of words in text. I’ve taken D3’s word cloud plugin, and did 2 things:

1. Engulfed it with an angularjs directive.
2. Added some features to it according to certain requirements.

Description of requirements

1. Get the input text by one column or more columns from an Excel table.
2. Words size will be normalized linearly.
3. The word cloud will be responsive and adaptive.
4. Configuration file: delimiters of the text will be taken from an external configuration file that the user will be able to edit without any code change.
5. Events: add several events, and expose each event to external directive/application:
   1. Hover – the hovered word will be highlighted.
   2. Select – the selected word will be highlighted and all the other word’s opacity will be reduced.
   3. Multi select (using CTRL key) – the selected words will be highlighted and all the other word’s opacity will be reduced.
6. All the above events can be dispatched by any directive that has exposed to the API of the word cloud.
7. Parse text algorithm: calculation of word frequency in text, normalize linearly, and create index of each occurrence of the word in text.
8. API. See more in below API Description.

D3-cloud

I used d3-cloud.js, which is great plugin for d3, created by Jason Davies.

As Jason Davies wrote himself:

Note that this is the only the layout algorithm and any code for converting text into words and rendering the final output requires additional development.

As Jason (a great name for a JS developer, right? JSON) promised, it is not a full fledged plugin.  What’s missing:

1. Accept a string and create a word cloud from it.
2. No configuration file option,
3. No Mouse events on the words.
4. No API

Code and API Description

Word Cloud directive

The directive is responsible for the cloud’s initiation including the SVG insertion into the DOM.  When the directive finishes its $compilation, an onInit method is called, passing the API for its parent component/app.  The directive also handles the incoming events: hover/select/multi-Select and is responsible to expose these events when they occur.

Word Cloud service

The service holds several helper methods.  Those are used by the directives to parse words, handle the configuration file etc.

Usage

The WC directive needs only one bound object – the config object.  It is bound like:

<wbx-word-cloud word-cloud-config="myCtrl.configObj"></wbx-word-cloud>

The config must have an “initCloud” method that will be triggered when the directive is ready. 

configObj = {
   initCloud: function(wcApi){
             //save the wcApi for future reference
    },
}

API Description

General

The API of the Word Cloud allows the user to control the cloud.  Each directive is separate from the other and has its own wcApi.  This means, you can add as many clouds to a single page, and manage them separately.

API exposed functions

• setText(data, append)

Parameters:

Data {[String]|String} –  a string or an array of strings. Words in string should be separated by the set delimiters (if not set, default delimiters will be used).

Append {Bool} – If true, data is appended to current data, else, data replaces current data.

• setListener(eventName, callback)

Parameters:

eventName {String} – of event from Exposed events.

Callback {Function} – a function to be called on mentioned event.

Exposed events

• ‘onSelect’ – parameters:
  Word – the word that was selected/unselected. Undefined if clicked on an empty area (not on a word).
  [Word] – the words that are currently selected. Undefined if just one word selected without Ctrl key.  Empty array if selection was cleared.
• ‘onHover’ – parameters:
  Word – the hovered word

Configuration JSON file 

Configuration file: wbxCloudConfig.json contains the desired delimiters, for example:

 “delimiters”: [“,”, ” “,”;”]

The file can be edited externally by the user without changing any row in code.

The path of the file will be sent by configObj, in the configUrl property, for example:

configObj = {
   initCloud: function(wcApi){
             //save the wcApi for future reference
    },
    configUrl:"http://localhost:3000/",
    configParams:{"delimiters": [",", " "]}
 }

Without configuration file, every character except of letters, will treat as delimiter, and will not appear

in the word cloud.

Another option is to send an Object with delimiters, as configParams in above example.

Dependencies

The main dependencies:

Angular v1.4.

d3.js v3.

d3-cloud.js v.1.2.1

Live Versions

Demo version is available.

Also there is a simple plunker .

The project has repository on github, feel free to contribute.