Bringing back the customClass option

README.md

@@ -9,7 +9,7 @@ You can see a demo here: http://www.lucaongaro.eu/demos/jqcloud/
 Installing jQCloud is extremely simple:
 
 1. Make sure to import jQuery in your project.
-2. Download the jQCloud files. Place [jqcloud-1.0.2.js](https://raw.github.com/DukeLeNoir/jQCloud/master/jqcloud/jqcloud-1.0.2.js) (or the minified version [jqcloud-1.0.2.min.js](https://raw.github.com/DukeLeNoir/jQCloud/master/jqcloud/jqcloud-1.0.2.min.js)) and [jqcloud.css](https://raw.github.com/DukeLeNoir/jQCloud/master/jqcloud/jqcloud.css) somewhere in your project and import both of them in your HTML code.
+2. Download the jQCloud files. Place [jqcloud-1.0.4.js](https://raw.github.com/fzero/jQCloud/master/jqcloud/jqcloud-1.0.4.js) (or the minified version [jqcloud-1.0.4.min.js](https://raw.github.com/fzero/jQCloud/master/jqcloud/jqcloud-1.0.4.min.js)) and [jqcloud.css](https://raw.github.com/fzero/jQCloud/master/jqcloud/jqcloud.css) somewhere in your project and import both of them in your HTML code.
 
 You can easily substitute jqcloud.css with a custom CSS stylesheet following the guidelines explained later.
 
@@ -31,7 +31,7 @@ Here is more detailed example:
     <title>jQCloud Example</title>
     <link rel="stylesheet" type="text/css" href="jqcloud.css" />
     <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js"></script>
-    <script type="text/javascript" src="jqcloud-1.0.2.js"></script>
+    <script type="text/javascript" src="jqcloud-1.0.4.js"></script>
     <script type="text/javascript">
       /*!
        * Create an array of word objects, each representing a word in the cloud
@@ -66,7 +66,7 @@ The container element must be visible and have non-zero dimensions when you call
 ### Word Options
 
 For each word object in your word array, you need to specify the following mandatory attributes:
- 
+
  * **text** (string): the word(s) text
  * **weight** (number): a number (integer or float) defining the relative importance of the word (such as the number of occurrencies, etc.). The range of values is arbitrary, and they will be linearly mapped to a discrete scale from 1 to 10.
 
@@ -95,15 +95,20 @@ All cloud-wide configurations are optional, and the full list of available optio
 * **center** (object): The x and y coordinates of the center of the word cloud, relative to the container element (e.g.: {x: 300, y: 150}). Defaults to the center of the container element.
 * **afterCloudRender** (function): A callback function to be called after the whole cloud is fully rendered.
 * **delayedMode** (boolean): If true, words are rendered one after another with a tiny delay between each one. This prevents freezing of the browser when there are many words to be rendered. If false, the cloud will be rendered in one single shot. By default, delayedMode is true when there are more than 50 words.
-* **shape** (string): the shape of the cloud. By default it is elliptic, but it can be set to `"rectangular"` to draw a rectangular-shaped cloud.
+* **shape** (string): The shape of the cloud. By default it is elliptic, but it can be set to `"rectangular"` to draw a rectangular-shaped cloud.
+* **customClass** (string): Custom CSS class to be added to all words.
+* **toggleClass** (string): Option to have more than one CSS class for each word weight (i.e. alternates between `wa1` and `wb1` instead of using just `w1`).
+* **overlapFactor** (integer): How much the words can overlap each other (default: 0).
+* **testBoundaries** (boolean): If true, jQCloud will make sure the words don't go past the container's boundaries (useful for long words).
+
 
 ## Custom CSS guidelines
 
 The word cloud produced by jQCloud is made of pure HTML, so you can style it using CSS. When you call `$("#example").jQCloud(...)`, the containing element is given a CSS class of "jqcloud", allowing for easy CSS targeting. The included CSS file `jqcloud.css` is intended as an example and as a base on which to develop your own custom style, defining dimensions and appearance of words in the cloud. When writing your custom CSS, just follow these guidelines:
 
 * Always specify the dimensions of the container element (div.jqcloud in jqcloud.css).
 * The CSS attribute 'position' of the container element must be explicitly declared and different from 'static' (if it is 'statis', jQCloud overwrites it to 'relative').
-* Specifying the style of the words (color, font, dimension, etc.) is super easy: words are wrapped in `<span>` tags with ten levels of importance corresponding to the following classes (in descending order of importance): w10, w9, w8, w7, w6, w5, w4, w3, w2, w1. 
+* Specifying the style of the words (color, font, dimension, etc.) is super easy: words are wrapped in `<span>` tags with ten levels of importance corresponding to the following classes (in descending order of importance): w10, w9, w8, w7, w6, w5, w4, w3, w2, w1 (or wa/wb + number if using toggleClasses).
 
 
 ## v1.0 and backward compatibility
@@ -114,7 +119,7 @@ Please note that version 1.0 is a redesign of the API that does not maintain bac
 
 This is a quick list of what changed in the new 1.0 API:
 
-  * in the word object, you can now specify any html attribute for the word <span> using the `html` option (e.g.: `{title: "A Title", "class": "custom-class", data-custom: "custom data attribute"}`). Since this allows for more flexibility, `title`, `customClass` and `dataAttributes` options are superfluous and dropped in v1.0.
+  * in the word object, you can now specify any html attribute for the word <span> using the `html` option (e.g.: `{title: "A Title", "class": "custom-class", data-custom: "custom data attribute"}`). Since this allows for more flexibility, `title` and `dataAttributes` options are superfluous and dropped in v1.0.
   * the `url` option was renamed `link` in v1.0, and can now be a URL string or an object. In the latter case, any html attribute for the `<a>` tag can be specified (e.g.: `{href: "http://myurl.com", title: "A Title"}`).
   * the cloud options `randomClasses` and `nofollow` are dropped in v1.0. They were indended for purposes which are better achieved using the new `html` and `link` word options.
   * `width` and `height` cloud options now set the width and height of the cloud container element, other than determining the aspect ratio of the cloud.
@@ -150,6 +155,10 @@ If you make changes to the JavaScript source, to the README, to examples or to t
 
 ## Changelog
 
+1.0.4 Added `toggleClass`, `overlapFactor` and `testBoundaries` ([fzero](https://github.com/fzero))
+
+1.0.3 Brought back the `customClass` convenience option ([fzero](https://github.com/fzero))
+
 1.0.2 Relative font sizes and easier to customize CSS (kudos to [daniel-toman](https://github.com/daniel-toman))
 
 1.0.1 Option to turn off URL encoding for links (thanks to [bboughton](https://github.com/bboughton))

examples/index.html

@@ -4,7 +4,7 @@
     <title>jQCloud Example</title>
     <link rel="stylesheet" type="text/css" href="../jqcloud/jqcloud.css" />
     <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.js"></script>
-    <script type="text/javascript" src="../jqcloud/jqcloud-1.0.2.js"></script>
+    <script type="text/javascript" src="../jqcloud/jqcloud-1.0.4.js"></script>
     <script type="text/javascript">
       var word_list = [
         {text: "Lorem", weight: 13, link: "https://github.com/DukeLeNoir/jQCloud"},

examples/rectangular.html

@@ -4,7 +4,7 @@
     <title>jQCloud Example</title>
     <link rel="stylesheet" type="text/css" href="../jqcloud/jqcloud.css" />
     <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.js"></script>
-    <script type="text/javascript" src="../jqcloud/jqcloud-1.0.2.js"></script>
+    <script type="text/javascript" src="../jqcloud/jqcloud-1.0.4.js"></script>
     <script type="text/javascript">
       var word_list = [
         {text: "Lorem", weight: 13},
@@ -51,7 +51,7 @@
         {text: "Sed", weight: 1}
       ];
       $(function() {
-        $("#my_favorite_latin_words").jQCloud(word_list, {shape: "rectangular"});
+        $("#my_favorite_latin_words").jQCloud(word_list, {shape: "rectangular", customClass: "tag"});
       });
     </script>
   </head>

examples/vertical_words.html

@@ -10,7 +10,7 @@
     </style>
     <link rel="stylesheet" type="text/css" href="../jqcloud/jqcloud.css" />
     <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.js"></script>
-    <script type="text/javascript" src="../jqcloud/jqcloud-1.0.2.js"></script>
+    <script type="text/javascript" src="../jqcloud/jqcloud-1.0.4.js"></script>
     <script type="text/javascript">
       var word_list = [
         {text: "Lorem", weight: 13},

jqcloud/jqcloud-1.0.2.js → jqcloud/jqcloud-1.0.4.js

@@ -1,14 +1,13 @@
 /*!
  * jQCloud Plugin for jQuery
  *
- * Version 1.0.2
+ * Version 1.0.4
  *
- * Copyright 2011, Luca Ongaro
+ * Copyright 2012, Luca Ongaro, Fabio Neves
  * Licensed under the MIT license.
  *
- * Date: Tue Oct 09 22:08:53 +0200 2012
+ * Date: 2012-12-03 15:04:52 -0500
 */
-
 (function( $ ) {
   "use strict";
   $.fn.jQCloud = function(word_array, options) {
@@ -22,12 +21,16 @@
       width: $this.width(),
       height: $this.height(),
       center: {
-        x: ((options && options.width) ? options.width : $this.width()) / 2.0,
-        y: ((options && options.height) ? options.height : $this.height()) / 2.0
+        x: ((options && options.width) ? options.width : $this.width() / 2.0),
+        y: ((options && options.height) ? options.height : $this.height() / 2.0)
       },
       delayedMode: word_array.length > 50,
       shape: false, // It defaults to elliptic shape
-      encodeURI: true
+      encodeURI: true,
+      customClass: '',
+      toggleClasses: false,
+      overlapFactor: 0,
+      testBoundaries: false
     };
 
     options = $.extend(default_options, options || {});
@@ -45,11 +48,20 @@
       var hitTest = function(elem, other_elems){
         // Pairwise overlap detection
         var overlapping = function(a, b){
-          if (Math.abs(2.0*a.offsetLeft + a.offsetWidth - 2.0*b.offsetLeft - b.offsetWidth) < a.offsetWidth + b.offsetWidth) {
-            if (Math.abs(2.0*a.offsetTop + a.offsetHeight - 2.0*b.offsetTop - b.offsetHeight) < a.offsetHeight + b.offsetHeight) {
+          // First test against canvas boundaries (depending on options)
+          if (options.testBoundaries) {
+            if (a.offsetLeft < 0 || a.offsetTop < 0 ||
+                a.offsetTop + a.offsetHeight > options.height ||
+                a.offsetLeft + a.offsetWidth > options.width) {
               return true;
             }
           }
+          // Then test a/b overlap
+          var ov = 2.0 + Math.abs(options.overlapFactor / 10);
+          if ( (Math.abs(ov * a.offsetLeft + a.offsetWidth - ov * b.offsetLeft - b.offsetWidth) < a.offsetWidth + b.offsetWidth) &&
+              (Math.abs(ov * a.offsetTop + a.offsetHeight - ov * b.offsetTop - b.offsetHeight) < a.offsetHeight + b.offsetHeight) ) {
+            return true;
+          }
           return false;
         };
         var i = 0;
@@ -74,6 +86,9 @@
           already_placed_words = [],
           aspect_ratio = options.width / options.height;
 
+      // Toggles between 'wa' and 'wb' classes for color variation.
+      var color_toggle = 'a';
+
       // Function to draw a word, by moving it in spiral until it finds a suitable empty place. This will be iterated on each word.
       var drawOneWord = function(index, word) {
         // Define the ID attribute of the span that will wrap the word, and the associated jQuery selector string
@@ -87,7 +102,7 @@
             quarter_turns = 0.0,
 
             weight = 5,
-            custom_class = "",
+            custom_class = options.customClass,
             inner_html = "",
             word_span = "";
 
@@ -106,7 +121,15 @@
           weight = Math.round((word.weight - word_array[word_array.length - 1].weight) /
                               (word_array[0].weight - word_array[word_array.length - 1].weight) * 9.0) + 1;
         }
-        word_span = $('<span>').attr(word.html).addClass('w' + weight + " " + custom_class);
+
+        var class_prefix = 'w'
+
+        if (options.toggleClasses) {
+          class_prefix = 'w' + color_toggle;
+          color_toggle = (color_toggle === 'a') ? 'b' : 'a';
+        }
+
+        word_span = $('<span>').attr(word.html).addClass(class_prefix + weight + " " + custom_class);
 
         // Append link if word.url attribute was set
         if (word.link) {