Bindable Vector Graphics provides real-time data-driven visualisation for the web.
npm install bvgLive 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 usesObject.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 withMaxArt2501/Object.observe.
Install using npm:
1. Install Node.js: https://docs.npmjs.com/getting-started/installing-node
2. In your working directory:
```
npm install bvg
Install via GitHub:
1. Clone this repo:
``
git clone https://github.com/Spaxe/BVG.js.git
2. Copy require.js and bvg.js into your working directory.
To include BVG.js in your webpage:
1. In your HTML
, include this script using require.js:
`HTML
` 2. In
your-script.js, define your own code with
`Javascript
require(['path/to/bvg.js'], function (BVG) {
// your code goes here ...
});
`Quickstart
HTML:
`HTML
`CSS (Make the container large enough):
`CSS
html, body, #bvg-container {
height: 100%;
margin: 0;
}
`Javascript:
`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 BVG Container
The rest of the documentation will assume bvg as our BVG container
created by the example below.
$3
Create a BVG container inside htmlElement.Return the BVG container object.
-
htmlElement : Either a CSS Selector
or any HTMLElement.`Javascript
// Create a new BVG container and append it to an existing HTML element.
var bvg = BVG.create('#bvg-container');
`
BVG Elements
All BVG objects, including the container, have access to drawing functions
and return reference to the new shape, which is also a BVG.`Javascript
// 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:
`Javascript
// 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.`Javascript
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.
});
`
$3
Create a rectangle at position (x, y) at width x height in size.`Javascript
var rect = bvg.rect(100, 100, 300, 150);
`
$3
Create a circle centred on (cx, cy) with radius r.`Javascript
var circle = bvg.ellipse(100, 100, 50);
`
$3
Create a ellipse centred on (cx, cy) with radii rx and ry.`Javascript
var ellipse = bvg.ellipse(100, 100, 200, 180);
`
$3
Create a line from (x1, y1) to (x2, y2).`Javascript
var line = bvg.line(100, 100, 200, 300);
`
$3
Create a series of lines from point to point.`Javascript
var polyline = bvg.polyline([[100, 200], [200, 300], [400, 800]]);
`
$3
Create a closed polygon from point to point. The last point will be
connected back to the first point.`Javascript
var polygon = bvg.polygon([[100, 200], [200, 300], [400, 800]]);
`
Grouping Elements
$3
Create a group to contain BVG objects. It acts like a BVG container with
an optional
transform attribute.`Javascript
// 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);
}
`
Hyperlinks
$3
Create a hyperlink BVG to target URL
url. It does not have any display
elements. Make sure to append elements to it.`Javascript
// 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);
`
Other Geometry
$3
Create a regular triangle centred on (cx, cy) with vertices r distance
away.`Javascript
var triangle = bvg.triangle(50, 50, 10);
`
$3
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.`Javascript
var arc = bvg.arc(50, 50, 50, 100, 0, Math.PI);
`
$3
Create a string of text text at location (x, y).`Javascript
var text = bvg.text('Mrraa!', 20, 10);
`
The BVG Object
BVGs are SVGs with extra superpowers.
$3
Return an array of BVGs matching selector inside BVG. selector is
defined as CSS Selectors.
$3
Insert child_bvg inside bvg. This is useful to add elements inside a
BVG.group().
$3
Remove itself from its parent. Return self reference.
$3
Return the parent BVG. If there is no parent (such is the case for the BVG
container itself), return null.
$3
Return a list of BVG elements inside bvg.
$3
Return thw BVG graphical content, a SVG.
$3
Get/set the data object in a BVG. There are four ways to use this
function. -
bvg.data(): Return data bound to the BVG.
- bvg.data(newData): Update data with newData object.
- bvg.data(property): Return data[property] from the BVG.
- bvg.data(property, newValue): Update property with newValue.Return
bvg object reference.
$3
Get/set attributes on a BVG. -
bvg.attr(attr): Return attribute value.
- bvg.attr(attr, value): Update attr with value.
$3
Get/set the filling colour. -
bvg.fill(): Return fill colour as [r, g, b, a], or '' (empty
strig) if fill is not specified on the object.
- bvg.fill(rgb): Set fill with a greyscale colour with equal
values (rgb, rgb, rgb).
- bvg.fill(r, g, b, [a]): Set fill with (r, g, b, a). If a
is omitted, it defaults to 1.r, g, b should be in the range of 0-255 inclusive.
$3
Remove BVG object's colour filling completely.
$3
Get/set the outline colour. -
bvg.stroke(): Return stroke colour as [r, g, b, a]. If stroke is
not specified, return '' (empty string).
- bvg.stroke(rgb): Set stroke with a greyscale colour with equal
values (rgb, rgb, rgb).
- bvg.stroke(r, g, b, [a]): Set stroke with (r, g, b, a). If a
is omitted, it defaults to 1.r, g, b should be in the range of 0-255 inclusive.
$3
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.
$3
Remove BVG object's outline completely.
$3
Add a class name to the element.
$3
Remove a class name to the element.
$3
Return true if the element has class c.
$3
Add or remove the class c to the element.
Affine Transformations
$3
Apply a moving translation by x and y units. If y is not given, it
is assumed to be 0.
Utility Methods
$3
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.
$3
Return the CSS representation in hsla() as a string. -
hue: A value between 0 and 360, where 0 is red, 120 is green,
and 240 is blue.
- saturation : A value between 0 and 100, where 0 is grey and
100 is fully saturate.
- lightness: A value between 0 and 100, where 0 is black and
100 is full intensity of the colour.
$3
Return an array [x, y, z, ...]` from a string containing common-separated