version 0.2.0 (add configuration options)

Luca Ongaro · Luca Ongaro · commit 5f4895c25dbc · 2011-07-13T14:09:40.000+02:00
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+.DS_Store
diff --git a/README.textile b/README.textile
@@ -9,7 +9,7 @@ h2. Installation
 Installing jQCloud is extremely simple:
 
 # Make sure to import the jQuery library in your project.
-# Download the jQCloud files. Place jqcloud-0.1.8.js (or the minified version jqcloud-0.1.8.min.js) and jqcloud.css somewhere in your project and import both of them in your HTML code.
+# Download the jQCloud files. Place jqcloud-0.2.0.js (or the minified version jqcloud-0.2.0.min.js) and 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.
 
@@ -23,7 +23,7 @@ bc. <!DOCTYPE html>
     <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-0.1.8.js"></script>
+    <script type="text/javascript" src="jqcloud-0.2.0.js"></script>
     <script type="text/javascript">
       /*!
        * Create an array of objects to be passed to jQCloud, each representing a word in the cloud and specifying
@@ -59,14 +59,37 @@ bc. <!DOCTYPE html>
   </body>
 </html>
 
+h3. Options:
+
+Since version 0.2.0, jQCloud accepts an object containing configuration options as the second argument:
+
+bc. $("#example").jQCloud(word_list, {
+  width: 300,
+  height: 200
+});
+
+The full list of available options is the following:
+
+* *width* (number): The width of the word cloud. Defaults to the width of the container element.
+* *height* (number): The height of the word cloud. Defaults to the height of the container element.
+* *center* (object): The x and y coordinates of the center of the word cloud (e.g.: {x: 300, y: 150}). Defaults to the center of the container element.
+* *callback* (function): A callback function to be called after the cloud is fully rendered. Undefined by default.
+* *delayed_mode* (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, delayed_mode is true when there are more than 50 words.
+
 h3. Note:
 
-Since drawing the cloud is rather computationally intensive, cloud rendering isn't instantaneous. If you want to make sure that some code executes after the cloud is rendered, you can pass to jQCloud a callback function:
+Since drawing the cloud is rather computationally intensive, cloud rendering isn't instantaneous. If you want to make sure that some code executes after the cloud is rendered, you can specify in the options a callback function:
 
-bc. $("#example").jQCloud(word_list, function(){
-  // This code executes after the cloud is fully rendered
+bc. $("#example").jQCloud(word_list, {
+  callback: function() {
+    // This code executes after the cloud is fully rendered
+  }
 });
 
+h4. Deprecation warning:
+
+Before version 0.2.0 jQCloud used to accept a callback function as the second argument. This way of specifying the callback function is deprecated and, although version 0.2.0 maintains backward compatibility, it will be removed in newer versions. If you need a callback function, use the 'callback' configuration option instead.
+
 h2. 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:
@@ -83,6 +106,8 @@ If you happen to use jQCloud in your projects, you can make me know (just contac
 
 h2. Changelog
 
+0.2.0 Add configuration options, passed as the second argument of jQCloud (include ideas proposed by "mindscratch":https://github.com/mindscratch and "aaaa0441":https://github.com/aaaa0441)
+
 0.1.8 Fix bug in the algorithm causing sometimes unbalanced layouts (thanks to "isamochernov":https://github.com/isamochernov)
 
 0.1.7 Remove duplicated @</span>@ when word has an URL (thanks to "rbrancher":https://github.com/rbrancher)
diff --git a/examples/index.html b/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-0.1.8.js"></script>
+    <script type="text/javascript" src="../jqcloud/jqcloud-0.2.0.js"></script>
     <script type="text/javascript">
       var word_list = [
         {text: "Lorem", weight: 13, url: "https://github.com/DukeLeNoir/jQCloud"},
diff --git a/jqcloud/jqcloud-0.1.8.min.js b/jqcloud/jqcloud-0.1.8.min.js
diff --git a/jqcloud/jqcloud-0.2.0.js b/jqcloud/jqcloud-0.2.0.js
@@ -1,21 +1,39 @@
 /*!
  * jQCloud Plugin for jQuery
  *
- * Version 0.1.8
+ * Version 0.2.0
  *
  * Copyright 2011, Luca Ongaro
  * Licensed under the MIT license.
  *
- * Date: Fri Apr 8 10:24:15 +0100 2011
+ * Date: Wed Jul 13 13:48:05 +0100 2011
  */ 
  
 (function( $ ){
-  $.fn.jQCloud = function(word_array, callback_function) {
+  $.fn.jQCloud = function(word_array, options) {
     // Reference to the container element
     var $this = this;
     // Reference to the ID of the container element
     var container_id = $this.attr('id');
 
+    // Default options value
+    var default_options = {
+      width: $this.width(),
+      height: $this.height(),
+      center: {
+        x: $this.width() / 2.0,
+        y: $this.height() / 2.0
+      },
+      delayed_mode: word_array.length > 50
+    };
+
+    // Maintain backward compatibility with old API, where the second argument of jQCloud was a callback function
+    if (typeof options === 'function') {
+      options = { callback: options }
+    }
+
+    options = $.extend(default_options, options || {});
+
     // Add the "jqcloud" class to the container for easy CSS styling
     $this.addClass("jqcloud");
 
@@ -51,13 +69,10 @@
 
       var step = 2.0;
       var already_placed_words = [];
-      var aspect_ratio = $this.width() / $this.height();
-      var origin_x = $this.width() / 2.0;
-      var origin_y = $this.height() / 2.0;
-
-      // Move each word in spiral until it finds a suitable empty place
-      $.each(word_array, function(index, word) {
+      var aspect_ratio = options.width / options.height;
 
+      // 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
         var word_id = container_id + "_word_" + index;
         var word_selector = "#" + word_id;
@@ -73,8 +88,8 @@
 
         var width = $(word_selector).width();
         var height = $(word_selector).height();
-        var left = origin_x - width / 2.0;
-        var top = origin_y - height / 2.0;
+        var left = options.center.x - width / 2.0;
+        var top = options.center.y - height / 2.0;
         $(word_selector).css("position", "absolute");
         $(word_selector).css("left", left + "px");
         $(word_selector).css("top", top + "px");
@@ -83,22 +98,38 @@
           radius += step;
           angle += (index % 2 === 0 ? 1 : -1)*step;
 
-          left = origin_x - (width / 2.0) + (radius*Math.cos(angle)) * aspect_ratio;
-          top = origin_y + radius*Math.sin(angle) - (height / 2.0);
+          left = options.center.x - (width / 2.0) + (radius*Math.cos(angle)) * aspect_ratio;
+          top = options.center.y + radius*Math.sin(angle) - (height / 2.0);
 
           $(word_selector).css('left', left + "px");
           $(word_selector).css('top', top + "px");
         }
         already_placed_words.push(document.getElementById(word_id));
-      });
+      }
+
+      var drawOneWordDelayed = function(index) {
+        index = index || 0;
+        if (index < word_array.length) {
+          drawOneWord(index, word_array[index]);
+          setTimeout(function(){drawOneWordDelayed(index + 1);}, 10);
+        }
+      }
+
+      // Iterate drawOneWord on every word. The way the iteration is done depends on the drawing mode (delayed_mode is true or false)
+      if (options.delayed_mode){
+        drawOneWordDelayed();
+      }
+      else {
+        $.each(word_array, drawOneWord);
+      }
 
-      if (typeof callback_function === 'function') {
-        callback_function.call(this);
+      if (typeof options.callback === 'function') {
+        options.callback.call(this);
       }
     };
 
     // Delay execution so that the browser can render the page before the computatively intensive word cloud drawing
-    setTimeout(function(){drawWordCloud();}, 100);
+    setTimeout(function(){drawWordCloud();}, 10);
     return this;
   };
 })(jQuery);
diff --git a/jqcloud/jqcloud-0.2.0.min.js b/jqcloud/jqcloud-0.2.0.min.js
