PottisJS

A JavaScript library for interacting with SVG.

Why?

Getting started

Download

You need 3 files to get started:

  1. pottis.js library (0.0.2)
  2. tutorial.xhtml XHTML template
  3. apple.svg SVG image of an apple.

You can also get it from the GitHub: PottisJS at GitHub. (patches welcome!)

PottisJS works with Firefox (3.5) and Safari (4.0). Sorry Opera!

Examples

Thanks for the images!

What else?

In order to really do interactive stuff, animation is clearly needed, as seen on the SVG Open 2009 workshop. Three of the four teams there included some (JavaScript) animation in their prototype. That's something to wait for in PottisJS 2.0 :)

API Documentation

Loading

new Pottis(targetSVG, [clickCallback]) → PottisInstance

Initialize a new PottisJS library for targetSVG SVG element. If callback is given, callback(e) is called on the first click onto the targetSVG element. This is because some things don't work until all the external SVG files imported with importSVG have completely loaded, waiting for the mouse click gives them time to load.

var svg = document.getElementById("tutorial");
var pottis = new Pottis(svg);

<svg id="tutorial" version="1.1" width="900" height="600"
  xmlns="http://www.w3.org/2000/svg"
  xmlns:xlink="http://www.w3.org/1999/xlink" />

Behaviour

addClick(element, callback) → null

When element is clicked, callback(event) is fired.

addDoubleClick(element, callback) → null

When element is double-clicked, callback(event) is fired.

addDrag(element, [targetElement], [callback]) → null

Make element draggable. If targetElement is given, then element works as a handle for dragging the targetElement.

// Draggable apple
pottis.addDrag(apple);

// Group moves when the basket is dragged.
var basketAndApples = pottis.group("basket_apples", [basket, green_apple, red_apple])
pottis.addDrag(basket, basketAndApples);

addDrop(receiverElement, callback) → null

Make receiverElement droppable. Dropping draggables (made with addDrag) into receiverElement fires callback(receiver, dropped).

pottis.addDrop(basket, insertAppleIntoBasket);

addMouseOut(element, callback) → null

When mouse leaves the element, callback(event) will be fired.

addMouseOver(element, callback) → null

When mouse hovers over element, callback(event) will be fired.

addRightClick(element, callback) → null

When element is right-clicked, callback(event) will be fired.

addRotate(element, [targetElement], [callback]) → null

Element will rotate when dragged. If targetElement is given, then element works as handle for rotating the targetElement.

// Element will rotate when dragged
pottis.addRotate(apple);

// Dragging basket will rotate apples
var apples = pottis.group("apples", [green_apple, red_apple])
pottis.addRotate(basket, apples);

addScale(element, [targetElement], [callback]) → null

Element will be scaled when dragged. If targetElement is given, then element works as a handle for scaling.

// Element will scale when dragged
pottis.addScale(apple);

// Dragging basket will scale a group
var basketAndApples = pottis.group("basket_apples", [basket, green_apple, red_apple])
pottis.addScale(basket, basketAndApples;

removeDrag(element) → null

Removes drag from an element

Manipulation

group(groupId, elements) → SVGGroupElement

Groups elements (array) into svg group element.

var basketAndApples = pottis.group("basket_apples", [basket, green_apple, red_apple]);

hide(element) → null

Hides element. See show.

moveAbove(element, peerElement) → null

Moves element above the peerElement in rendering order.

moveBelow(element, peerElement) → null

Moves element below the peerElement in rendering order.

moveToBack(element) → null

Moves element to the bottom of all other elements in rendering order.

moveToFront(element) → null

Moves element to the top of all other elements in rendering order.

remove(element) → null

Removes element from the DOM.

show(element) → null

Shows element. See hide.

Transformations

rotate(element, angle, [cx], [cx]) → null

Rotate an element by angle (originally 0). By default, rotates relatively to element center. This can be changed with cx and cy, which specify the center point for rotate, relative to element top-left.

rotateAdd(element, angleToAdd, [centerX], [centerY]) → newAngle (integer)

Increment element rotation by angleToAdd. Returns new new rotation angle.

scale(element, sx, [sy], [cx], [cy]) → null

Scale an element by sx and sy (originally 1 and 1). If sy is not specified, it's the same as sx. By default, scales relatively to element center. This can be changed with cx and cy, which specify the center point for scale, relative to element top-left.

scaleAdd(element, sx, [sy]) → { sx: integer, sy: integer }

Increment element scale. Returns the new scale.

translate(element, [tx=0], [ty=0]) → null

Translate an element.

translateAdd(element, dx, [dy]) → { x: integer, y: integer }

Add to existing translation of an element. Values can be negative. Returns the new translation.

Adding elements

image(url, [imageId], [x=0], [y=0]) → SVGImageElement

Creates SVGImageElement with url as the source.

pottis.image("http://images.encyclopediadramatica.com/images/3/34/Longcat_buildings.jpg", "longcat_buildings");

importSVG(SVGFileName, groupId) → null

Imports external SVG to the DOM and wraps import in a group groupId. Quite experimental!

pottis.importSVG("apple.svg", "apple");
pottis.use("apple", "fresh_apple");

shape(element, attributes) → SVGElement

Inserts a new shape into the SVG DOM. element can be any valid SVG element. See W3C specification for attributes.

pottis.shape("rect", { x: 10, y: 10, width: 200, height: 100, fill: "blue" });

text(textContent, [textId], [x=0], [y=0]) → SVGTextElement

Creates SVGTextElement with textContent as the text content.

pottis.text("Thanks for using PottisJS!", null, 200, 100);

use(defId, useId, x, y) → SVGUseElement

Inserts an SVG use element into the SVG DOM. The use element references to a defs element with id defId.

pottis.use("apple", "another_fresh_apple");

Utilities

getMouseCoords(event, parentElement) → { x: integer, y: integer }

Returns mouse coordinates inside of the parent element.

randomInt(maxValue) → integer

Retuns a random integer between [0, maxValue-1].

// Plots element in x: [0,499], y: [100,399]
pottis.use("apple", "red_apple", pottis.randomInt(500), pottis.randomInt(300)+100);