BVG - Bindable Vector Graphics

Real-time data-driven visualisation for the web.

!Example

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.

Installation

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

!Quickstart Example

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
numbers.

Contribute to this library

Make a pull request or
post an issue. Say hello to
contact@xaiverho.com.