Real-time data-driven visualisation for the web.
Live example: http://spaxe.github.io/BVG.js/
Bindable Vector Graphics was born out of frustration for lack of a middle level SVG library. D3.js abstracts too much logic, and SVG.js provides only low-level SVG drawing. Bindable Vector Graphics offers SVG elements that change as the data change, and gives you tools to control their look.
The heart of this library is a trinity: SVG + Data + Binding. This
connects your data to the SVG element through the binding function, which
creates a living connection that can react to change. BVG uses
Object.observe()
which is
available on Chrome 36+, Opera 27+ and Android Browser 37+.
If you wish to use this for older browsers, you can polyfill with
MaxArt2501/Object.observe
.
Install using npm
:
-
Install Node.js: https://docs.npmjs.com/getting-started/installing-node
-
In your working directory:
npm install bvg
-
Use
browserify
to bundle your scripts. In your code:var BVG = require("bvg");
You can also include
bvg.js
as a standalone script as below.
Install via GitHub:
-
Clone this repo:
git clone https://github.com/Spaxe/BVG.js.git
-
Copy
bvg.js
into your working directory. -
Include
bvg.js
in your webpage:<script src="path/to/bvg.js"></script>
HTML:
<div id="bvg-container"></div>
CSS (Make the container large enough):
html, body, #bvg-container {
height: 100%;
margin: 0;
}
Javascript:
// Create a BVG container based on selected HTML element
var bvg = BVG.create('#bvg-container');
// Create a Bindable circle, colour it orange
var circle = bvg.ellipse(0, 0, 150, 150)
.fill(220, 64, 12);
// Change its size based on mouse movement
bvg.tag().addEventListener('mousemove', function (event) {
circle.data({
rx: event.clientX,
ry: event.clientY
});
});
The rest of the documentation will assume bvg
as our BVG container
created by the example below.
Create a BVG container inside htmlElement
.
Return the BVG container object.
htmlElement
: Either a CSS Selector or any HTMLElement.
// Create a new BVG container and append it to an existing HTML element.
var bvg = BVG.create('#bvg-container');
All BVG objects, including the container, have access to drawing functions and return reference to the new shape, which is also a BVG.
// Create a rectangle at (0, 0) with dimensions 100x100 px and add it to bvg
var rect = bvg.rect(0, 0, 100, 100);
The BVG module also has drawing functions, which return the BVG object:
// Create a rectangle at (0, 0) with dimensions 100x100 px
// Note it uses the BVG module directly to create the rectangle.
var rect = BVG.rect(0, 0, 100, 100);
// Add the rectangle to an existing BVG container
bvg.append(rect);
Drawing functions can be called in a number of ways. Take bvg.rect(x, y, width, height)
as an example below. Sometimes it is easier to use one over another style.
bvg.rect(0, 10, 30, 70); // Arguments style
bvg.rect({ // Object style
x: 0,
y: 10, // Name of the object properties must match
width: 30, // names of the arguments in the functions,
height: 70 // but the order can be any.
});
Create a rectangle at position (x, y)
at width
x height
in size.
var rect = bvg.rect(100, 100, 300, 150);
Create a circle centred on (cx, cy)
with radius r
.
var circle = bvg.ellipse(100, 100, 50);
Create a ellipse centred on (cx, cy)
with radii rx
and ry
.
var ellipse = bvg.ellipse(100, 100, 200, 180);
Create a line from (x1, y1)
to (x2, y2)
.
var line = bvg.line(100, 100, 200, 300);
Create a series of lines from point to point.
var polyline = bvg.polyline([[100, 200], [200, 300], [400, 800]]);
Create a closed polygon from point to point. The last point will be connected back to the first point.
var polygon = bvg.polygon([[100, 200], [200, 300], [400, 800]]);
Create a group to contain BVG objects. It acts like a BVG container with
an optional transform
attribute.
// Create a new group and fill it with dashes.
var dashes = bvg.group();
for (int i = 0; i < 5; i++) {
dahses.rect(10, 10 + i * 30, 50, 20);
}
Create a hyperlink BVG to target URL url
. It does not have any display
elements. Make sure to append elements to it.
// Clicking on this element will bring them to the Github page
var githubLink = bvg.hyperlink('https://github.com/spaxe/BVG.js');
// Make a button and attack it to the link
githubLink.ellipse(200, 200, 50, 50);
Create a regular triangle centred on (cx, cy)
with vertices r
distance
away.
var triangle = bvg.triangle(50, 50, 10);
Create an arc centred on (cx, cy)
with radius rx
and ry
, starting
from startAngle
anti-clockwise to endAngle
, where 0 is the positive
x-axis.
var arc = bvg.arc(50, 50, 50, 100, 0, Math.PI);
Create a string of text
text at location (x, y)
.
var text = bvg.text('Mrraa!', 20, 10);
BVGs are SVGs with extra superpowers.
Return an array of BVGs matching selector
inside BVG. selector
is
defined as CSS Selectors.
Insert child_bvg
inside bvg
. This is useful to add elements inside a
BVG.group()
.
Remove itself from its parent. Return self reference.
Return the parent BVG. If there is no parent (such is the case for the BVG container itself), return null.
Return a list of BVG elements inside bvg
.
Return thw BVG graphical content, a SVG.
Get/set the data
object in a BVG. There are four ways to use this
function.
bvg.data()
: Returndata
bound to the BVG.bvg.data(newData)
: Updatedata
withnewData
object.bvg.data(property)
: Returndata[property]
from the BVG.bvg.data(property, newValue)
: Updateproperty
withnewValue
.
Return bvg
object reference.
Get/set attributes on a BVG.
bvg.attr(attr)
: Return attribute value.bvg.attr(attr, value)
: Updateattr
withvalue
.
Get/set the filling colour.
bvg.fill()
: Returnfill
colour as [r, g, b, a], or''
(empty strig) if fill is not specified on the object.bvg.fill(rgb)
: Setfill
with a greyscale colour with equal values(rgb, rgb, rgb)
.bvg.fill(r, g, b, [a])
: Setfill
with(r, g, b, a)
. Ifa
is omitted, it defaults to1
.
r
, g
, b
should be in the range of 0-255 inclusive.
Remove BVG object's colour filling completely.
Get/set the outline colour.
bvg.stroke()
: Returnstroke
colour as [r, g, b, a]. Ifstroke
is not specified, return''
(empty string).bvg.stroke(rgb)
: Setstroke
with a greyscale colour with equal values(rgb, rgb, rgb)
.bvg.stroke(r, g, b, [a])
: Setstroke
with(r, g, b, a)
. Ifa
is omitted, it defaults to1
.
r
, g
, b
should be in the range of 0-255 inclusive.
Get/set the outline thickness.
Returns the current outline thickness if width
is omitted. Otherise,
it assigns the outline thickness with a new value, and returns the bvg
object reference.
width
: Outline thickness in pixels.
Remove BVG object's outline completely.
Add a class name to the element.
Remove a class name to the element.
Return true if the element has class c
.
Add or remove the class c
to the element.
Apply a moving translation by x
and y
units. If y
is not given, it
is assumed to be 0.
Return a string in the form of rgba(r, g, b, a)
.
If only r
is given, the value is copied to g
and b
to produce a
greyscale value.
Return the CSS representation in hsla()
as a string.
hue
: A value between0
and360
, where0
is red,120
is green, and240
is blue.saturation
: A value between0
and100
, where0
is grey and100
is fully saturate.lightness
: A value between0
and100
, where0
is black and100
is full intensity of the colour.
Return an array [x, y, z, ...]
from a string containing common-separated
numbers.
Make a pull request or post an issue. Say hello to contact@xaiverho.com.