graphing with raphael

5 files changed, 555 insertions, 0 deletions

diff --git a/test/g.raphael/docs/bar.markdown b/test/g.raphael/docs/bar.markdown
new file mode 100644
index 0000000..150e7dc
--- /dev/null
+++ b/test/g.raphael/docs/bar.markdown
@@ -0,0 +1,104 @@
+# g.bar.js #
+
+## Requirements ##
+
+ + raphael.js
+ + g.raphael.js
+ + g.bar.js
+ 
+## Overview ##
+
+Creates a bar chart.
+
+## Parameters ##
+
+**1. x** number **X coordinate of the centre**
+
+**2. y** number **Y coordinate of the centre**
+
+**3. width** number **width**
+
+**4. height** number **height**
+
+**5. values** array of numbers **Values for your bars.**
+
+**5. opts** object **Options (more info soon.)**
+
+_opts_
+
+**type**
+
+Values are,
+
+    + "round"
+    + "sharp"
+    + "soft"
+    + "square"
+    
+Defaults to "square" if type is not specified.
+
+**stacked**
+
+Values are,
+
+    + true
+    + false
+    
+Defaults to false. Use this to stack your bars instead of displaying them side by side.
+
+**gutter**
+
+Values given as a string, denoting %. E.g. "40%"
+
+Defaults to "20%". For horizontal barcharts, this is calculated as,
+
+    bargutter = Math.floor(barheight * gutter / 100)
+    
+e.g. if my height was 220, and I had 4 bars, then my barheight is calculated as,
+
+    Math.floor(height / (len * (100 + gutter) + gutter) * 100); // where len is 4 and height is 220, and if not specified, gutter is 20
+    
+then according to the above, my bargutter = 8px.
+    
+    
+## Methods ##
+
+**1. .hover(fin, fout)** - fin/fout: **callbacks to trigger when mouse hovers in and out respectively over the bars.**
+
+## Usage ##
+
+Create a bar chart,
+
+
+    // bare bones
+    var barchart = r.g.barchart(_params);
+    // example
+    var barchart = r.g.barchart(10, 10, 300, 220, [[30, 20, 10]]);
+    // horizontal barchart 
+    var hbarchart = r.g.hbarchart(10, 10, 300, 220, [[30, 20, 10]]);
+    
+    
+Create a stacked bar chart,
+
+
+    // example
+    var barchart = r.g.barchart(10, 10, 300, 220, [[30, 20, 10], [44, 66, 88]], {stacked:true});
+    
+    
+Attach hover event to piechart,
+
+
+    // example
+    r.g.barchart.hover(function() {
+        this.bar.attr({fill: "#333"}); 
+    }, function() {
+        this.bar.attr({fill: "#666"});
+    });
+
+## Others ##
+
+N/A
+
+## Written by ##
+
+Kenny Shen, www.northpole.sg.
\ No newline at end of file
diff --git a/test/g.raphael/docs/dot.markdown b/test/g.raphael/docs/dot.markdown
new file mode 100644
index 0000000..03fa76f
--- /dev/null
+++ b/test/g.raphael/docs/dot.markdown
@@ -0,0 +1,135 @@
+# g.dot.js #
+
+## Requirements ##
+
+ + raphael.js
+ + g.raphael.js
+ + g.dot.js
+ 
+## Overview ##
+
+Creates a dot chart.
+
+## Parameters ##
+
+**1. x** number **X coordinate of the centre**
+
+**2. y** number **Y coordinate of the centre**
+
+**3. width** number **width**
+
+**4. height** number **height**
+
+**5. valuesx** array of numbers **Values for x-axis.**
+
+**6. valuesy** array of numbers **Values for y-axis.**
+
+**7. size** array of numbers **Values for dot data.**
+
+**8. opts** object **Options (more info soon.)**
+
+_opts_
+
+**symbol**
+
+Values are,
+
+_(shorthand: full name)_
+
+    + o: "disc"
+    + f: "flower"
+    + d: "diamond"
+    + s: "square"
+    + t: "triangle"
+    + *: "star"
+    + x: "cross"
+    + +: "plus"
+    + ->: "arrow"
+
+If omitted, an empty "" is assigned to indicate no symbols.
+
+**max**
+
+Value - number. If omitted, this defaults to 100. This sets the max radius for the maximum value of your dot.
+
+**href**
+
+Value - array of links(string). This is positional and will be mapped from left to right. For example, if you supply 'href:["http://www.google.com","http://www.yahoo.com"]' and you have 4 dots, the links will be applied to the first two.
+
+**axis**
+
+Value - "_top_ _right_ _bottom_ _left_". If omitted, no axis will be rendered for the line chart. For example, if you wanted axis rendered for the left and bottom, (as in a typical x-y chart), you'll add 'axis:"0 0 1 1"' to opts. The axis is created using g.axis (for more information, see the g documentation).
+
+**axisxlabels**
+
+Value - array of labels.
+
+**axisylabels**
+
+Value - array of labels(string).
+
+**axisxstep**
+
+Value - number. Sets the stepping for the x-axis.
+
+**axisystep**
+
+Value - number. Sets the stepping for the y-axis.
+
+**heat**
+
+Value - boolean. If omitted, defaults to false. Sets a spectrum of color based on your values evenly across the dots.
+
+## Methods ##
+
+**1. .hover(fin, fout)** - fin/fout: **callbacks to trigger when mouse hovers in and out respectively over the dots.**
+
+**2. .click(f)** - f: **callback to trigger on click event.**
+
+**3. .each(f)** - f: **callback applied to each iteration.**
+
+## Usage ##
+
+Create a Raphael instance, 
+
+
+    // bare bones
+    var r = Raphael();
+    // create at top left corner of #element
+    var r = Raphael('dot-chart');
+    
+    
+Create a dot chart,
+
+
+    // bare bones
+    var dotchart = r.g.dotchart(_params);
+    // example
+    var dotchart = r.g.dotchart(10,10,300,220,[5,10,15,20,25],[220,220,220,220,220],[1,2,3,4,5], {max:10});
+    
+    
+Create labels,
+
+
+    // example
+    var axisx = ["dot1","dot2","dot3","dot4","dot5"]
+    r.g.dotchart(10,10,300,220,[5,10,15,20,25],[220,220,220,220,220],[1,2,3,4,5], {max:10, axis: "0 0 1 0", axisxlabels: axisx, axisxstep: 4, heat: true});
+
+    
+Attach click event to dotchart,
+
+
+    // example
+     var dots = r.g.dotchart(10,10,300,220,[5,10,15,20,25],[220,220,220,220,220],[1,2,3,4,5], {max:10, href: ["http://www.google.com","http://www.yahoo.com",,,"http://www.raphaeljs.com"]});
+      dots.each(function() {
+        this.click(function() {
+          // alerts href, if defined
+          alert(this.attrs.href);
+        });
+      });
+    
+## Others ##
+
+## Written by ##
+
+Kenny Shen, www.northpole.sg.
\ No newline at end of file
diff --git a/test/g.raphael/docs/g.markdown b/test/g.raphael/docs/g.markdown
new file mode 100644
index 0000000..10faea2
--- /dev/null
+++ b/test/g.raphael/docs/g.markdown
@@ -0,0 +1,7 @@
+# g.raphael.js #
+
+_in progress_
+
+## Written by ##
+
+Kenny Shen, www.northpole.sg.
\ No newline at end of file
diff --git a/test/g.raphael/docs/line.markdown b/test/g.raphael/docs/line.markdown
new file mode 100644
index 0000000..9ee4c96
--- /dev/null
+++ b/test/g.raphael/docs/line.markdown
@@ -0,0 +1,159 @@
+# g.line.js #
+
+## Requirements ##
+
+ + raphael.js
+ + g.raphael.js
+ + g.line.js
+ 
+## Overview ##
+
+Creates a line chart.
+
+## Parameters ##
+
+**1. x** number **X coordinate of the centre**
+
+**2. y** number **Y coordinate of the centre**
+
+**3. width** number **width**
+
+**4. height** number **height**
+
+**5. valuesx** array of numbers **Values for x-axis.**
+
+**6. valuesy** array of numbers **Values for y-axis.**
+
+**7. opts** object **Options (more info soon.)**
+
+_opts_
+
+**colors**
+
+Value - an array of color values, such as ["#444","#666"...]. If omitted, random colors will be used. (actually, Raphael.fn.g.colors. More info on this in the g.raphael.js documentation) For more information, refer to the [supported color formats](http://raphaeljs.com/reference.html#colour) section of the Raphaeljs documention.
+
+**symbol**
+
+Values are,
+
+_(shorthand: full name)_
+
+    + o: "disc"
+    + f: "flower"
+    + d: "diamond"
+    + s: "square"
+    + t: "triangle"
+    + *: "star"
+    + x: "cross"
+    + +: "plus"
+    + ->: "arrow"
+
+If omitted, an empty "" is assigned to indicate no symbols.
+
+**shade**
+
+Value - boolean. If omitted, false is assumed. If true, the area underneath the line will be shaded with the same color as the line, with opacity set to .3. You can affect this by setting nostroke (see below) option to true.
+
+**nostroke**
+
+Value - boolean. If omitted, false is assumed.
+
+**axis**
+
+Value - "_top_ _right_ _bottom_ _left_". If omitted, no axis will be rendered for the line chart. For example, if you wanted axis rendered for the left and bottom, (as in a typical x-y chart), you'll add 'axis:"0 0 1 1"' to opts. The axis is created using g.axis (for more information, see the g documentation).
+
+**smooth**
+
+Value - boolean. If omitted, false is assumed. If true, smoothing/rounding is applied to the path between data points.
+
+**gutter**
+
+Value - number. If omitted, value of '10' is assigned. Think of this as a general padding value between the chart and the bounding box/container. 
+
+
+## Methods ##
+
+**1. .hover(fin, fout)** - fin/fout: **callbacks to trigger when mouse hovers in and out respectively over the data points.**
+
+**2. .click(f)** - f: **callback to trigger on click event.**
+
+**3. .each(f)** - f: **callback applied to each iteration.**
+
+.each(f) works by iterating through each of the data points and returning each as a 'dot' object to the callback f(). Within the callback, you can access the object returned on each iteration in the context of 'this', for example
+
+
+	var f = function() {
+		
+		console.log(this.symbol);	// the symbol used to represent the data point on the line chart
+
+	}
+	
+**4. .hoverColumn(fin, fout)** - fin/fout: **callbacks to trigger when mouse hovers in and out respectively over the data columns.**
+
+**5. .clickColumn(f)** - f: **callback to trigger on click event.**
+
+**6. .hrefColumn(cols)** - _coming soon_
+
+**7. .eachColumn(f)** - f: **callback applied to each iteration.**
+
+
+## Usage ##
+
+Create a Raphael instance, 
+
+
+    // bare bones
+    var r = Raphael();
+    // create at top left corner of #element
+    var r = Raphael('line-chart');
+    
+    
+Create a line chart,
+
+
+    // bare bones
+    var linechart = r.g.linechart(_params);
+    // example
+    var linechart = r.g.linechart(10,10,300,220,[1,2,3,4,5],[10,20,15,35,30], {"colors":["#444"], "symbol":"s", axis:"0 0 1 1"});
+
+
+Attach hover event to linechart,
+
+
+    // example
+	r.g.linechart.hover(function() {
+		this.symbol.attr({'fill':'#CCC'});
+	}, function() {
+		this.symbol.attr({'fill':'#444'});
+	});
+	
+
+Attach click event to linechart,
+
+
+    // example
+    r.g.linechart.click(function() {
+       alert("You clicked on the line chart!"); 
+    });
+
+
+## Others ##
+
+There's two important internal methods that are used to create and return the objects for interaction with a gRaphael line chart, based on what methods you call.
+
+.hover(), .click(), .each() create and return representations ('dots') of the data points used to plot the line. The dots have the following properties when they're returned in the context of 'this' to the methods you call,
+
+	+ x
+	+ y
+	+ value
+	+ line
+	+ shade
+	+ symbol
+	+ symbols 
+	+ axis
+	
+.hoverColumn(), .clickColumn(), .eachColumn() create and return groupings of data 'dots'. Columns have similar properties to their atomic counterparts but are usually array of values. 
+
+## Written by ##
+
+Kenny Shen, www.northpole.sg.
\ No newline at end of file
diff --git a/test/g.raphael/docs/pie.markdown b/test/g.raphael/docs/pie.markdown
new file mode 100644
index 0000000..3dbc6d3
--- /dev/null
+++ b/test/g.raphael/docs/pie.markdown
@@ -0,0 +1,150 @@
+# g.pie.js #
+
+## Requirements ##
+
+ + raphael.js
+ + g.raphael.js
+ + g.pie.js
+ 
+## Overview ##
+
+Creates a pie chart.
+
+## Parameters ##
+
+**1. x** number **X coordinate of the centre**
+
+**2. y** number **Y coordinate of the centre**
+
+**3. r** number **radius**
+
+**4. values** array of numbers **Values for your slices.**
+
+**5. opts** object **Options (more info soon.)**
+
+_opts_
+
+**legend**
+
+Values are,
+
+    + legend - e.g. ["apples", "oranges"]
+    + legendothers
+    + legendmark 
+    + legendpos - e.g. "west"
+
+legend is required. If legendpos is omitted, 'east' is assumed. If legendmark is omitted, 'disc' is assumed. The current possible options for legendmark and legendpos are,
+
+**legendmark**
+
+Values are,
+
+_(shorthand: full name)_
+
+    + o: "disc"
+    + f: "flower"
+    + d: "diamond"
+    + s: "square"
+    + t: "triangle"
+    + *: "star"
+    + x: "cross"
+    + +: "plus"
+    + ->: "arrow"
+
+**legendpos**
+
+Values are,
+
+    + "north"
+    + "south"
+    + "east"
+    + "west"
+    
+## Methods ##
+
+**1. .hover(fin, fout)** - fin/fout: **callbacks to trigger when mouse hovers in and out respectively over the pie sectors.**
+
+**2. .click(f)** - f: **callback to trigger on click event.**
+
+**3. .each(f)** - f: **callback applied to each iteration.**
+
+.each(f) works by iterating through each of the slices and returning each as an object to the callback f(). Within the callback, you can access the object returned on each iteration in the context of 'this', for example
+
+
+	var f = function() {
+		
+		console.log(this.r);	// the radius of the slice
+
+	}
+
+## Usage ##
+
+Create a Raphael instance, 
+
+
+    // bare bones
+    var r = Raphael();
+    // create at top left corner of #element
+    var r = Raphael('pie-chart');
+    
+    
+Create a pie chart,
+
+
+    // bare bones
+    var pie = r.g.piechart(_params);
+    // example
+    var pie = r.g.piechart(10, 10, 90, [10,20,30]);
+    
+    
+Create legends,
+
+
+    // example
+    r.g.piechart(320, 240, 100, [10,20,30,40], {legend:['%% apples', '%% bananas', '%% cherries', '%% durians'], legendmark:"*", legendpos: "south"});
+    
+Attach hover event to piechart,
+
+
+    // example
+    r.g.piechart(10, 10, 90, [10,20,30]).hover(function() {
+        // when mouse hovers over slice, change color 
+        this.sector.attr({fill:"#FAA"});
+    }, function() {
+        // when mouse hovers out, restore color
+        this.sector.attr({fill:"#666"});
+    });
+    
+Attach click event to piechart,
+
+
+    // example
+    r.g.piechart.click(function() {
+       alert("You clicked on the pie chart!"); 
+    });
+    
+## Others ##
+
+Each pie chart in g.raphael.js is composed of a 'series', or a collection of slices/sectors. Each slice has its own 'sector' property which carries information like the value, the color and other attributes, as well as its own 'cover' which can be thought of as a layer (really set to opacity 0) to which you attach events like click or hover.
+
+When you iterate through each slice of the pie chart using .each(), the returned slice has the following properties:
+
+	+ sector
+	+ cover
+	+ cx
+	+ cy
+	+ x (middle x coordinate of the sector)
+	+ y (middle y coordinate of the sector)
+	+ mangle
+	+ r (radius)
+	+ value
+	+ total
+	+ label
+
+When you attach a hover event for example, using .hover(), g.raphael.js is essentially iterating through each slice, as it does in .each(), and passing the returned slice to the callbacks to be called, and setting the events to happen by binding mouseover and mouseout events to the covers.
+
+All of this is container within the 'chart' object, which is initialized and returned to you when you first call g.piechart.
+
+## Written by ##
+
+Kenny Shen, www.northpole.sg.
\ No newline at end of file