⚓ API design

Pablo provides methods like circle() and line() to create each kind of SVG element. There are methods for manipulating SVG and HTML, to change the appearance, size, position or some other property. There are also methods for filtering and sorting elements. The simple plugin system allows new functionality to be added.

Using Pablo is to use SVG, so a growing knowledge of SVG goes hand-in-hand with using the library. See the Resources page for links and books on SVG.

Tip: In the docs, you can click and edit any code snippets that have ‘Run’ buttons.

⚓ Collections

When creating elements or selecting SVG and HTML from the page, Pablo encloses these elements within an array-like “collection”. A number of collection methods are equivalent to the methods on standard JavaScript Arrays, such as push, forEach, map and filter.

Elements are usually manipulated and filtered via the methods on the collection object, although the elements objects can also be worked with directly.

Method chaining

Collection methods are generally chainable:

/* Append an <svg> element to an HTML element */
var svg = Pablo(demoElement).svg({
    width: 220,
    height: 220
});

/* Append a <rect> element to the <svg> */
svg.rect({width:200, height:100})

    // Transform the <rect>
    .transform('translate', 70)
    .transform('rotate', 45)

    // Change attributes
    .addClass('guernica')
    .attr('fill', 'turquoise')

    // Add events
    .on('click', function(){
        alert('yes');
    });

Read/write methods

Many methods can either get or set properties on the elements:

/* Set an attribute */
shape.attr('fill', 'orange');

/* Get the attribute */
shape.attr('fill') === 'orange'; // true

⚓ Pablo()

The Pablo() method creates an array-like collection of new or pre-existing HTML or SVG elements.

Pablo()

Returns a new, empty Pablo collection.

Pablo(elements, [attributes])

Returns a new collection containing the elements.

elements could be a DOM element, another collection, an array of elements, a DOM node list, jQuery collection or other array-like object.

If attributes are specified, they are set on each element.

Pablo(selectors, [context])

Returns a collection of elements that match the specified CSS selectors. By default, this searches the global document, but an optional context element or elements can be passed.

Pablo(elementName, attributes)

Creates a named element with the specified attributes, and returns it in a collection.

Pablo(elementNames, [attributes])

Creates multiple named elements and returns them in a collection.

Pablo(markup, [attributes])

Converts SVG markup into a collection of elements. (experimental)

Pablo(dataUrl, [attributes])

Converts a data URL for an SVG file into a collection of elements.

⚓ Element methods

Any elements can be created with the Pablo() method. However, usually elements are created by calling a specific element method.

Pablo.ELEMENT_NAME([attributes])

Creates a new element with the same name as the method, wrapped in a collection. E.g. to create a new <circle> element, call Pablo.circle(). Optional attributes can be passed.

ELEMENT_NAME([attributes])

The same element methods can be called directly on collections, to create and append a new element to each element in the collection

⚓ Collection manipulation

These collection methods are used to pluck, add, remove or re-order elements in the collection. See also Iteration and Duplication

length

Returns the number of elements in the collection.

[index]

Square-bracket array notation to get a DOM element from a collection, e.g. collection[3].

eq(index)

Returns a collection containing the element specified by the array index, e.g. collection.eq(3). Negative numbers are counted from the end of the collection, e.g. collection.eq(-2).

first()

alias: eq(0)

Returns a collection containing the first element of the collection.

last()

alias: eq(-1)

Returns a collection containing the last element of the collection.

slice(start, [end])

Slice the elements from the collection, according to the passed indices, and return them wrapped in a new collection.

toArray()

Returns the collection as a native JavaScript array.

push(elements)

alias: add(element)

Return the collection with one or more elements added to the end of it.

concat(elements)

Return a new collection with one or more elements added to the end of it.

unshift(elements)

Return the collection with one or more elements added to the start of it.

pop()

Remove the last element in the collection and return it, wrapped in a new collection.

shift()

Remove the first element in the collection and return it, wrapped in a new collection.

reverse()

Reverse the collection and return it.

⚓ Element manipulation

These collection methods manipulate DOM elements. See also CSS

attr()

Get or set attributes on elements in the collection.

removeAttr(attributeName)

Remove a named attribute from each element in the collection.

transform()

Visually transform the elements, such as rotate, scale or translate them, using CSS transformsm using SVG’s transform attribute.

bbox()

Get the bounding box for the sum total of all elements in the collection.

append(elements)

Append the specified elements to each element in the collection.

appendTo(elements)

Append the elements in the collection to each element specified.

prepend(elements)

Prepend the specified elements to each element in the collection.

prependTo(element)

Prepend the elements in the collection to each element specified.

after(element)

Insert the specified elements after each element in the collection.

before(element)

Insert the specified elements before each element in the collection.

insertAfter(element)

Insert the elements in the collection after each element specified.

insertBefore(element)

Insert the elements in the collection before each element specified.

remove()

Remove each element in the collection from its parent element and remove any associated data and events.

detach()

Remove each element in the collection from its parent element, but don’t remove associated data and events.

empty()

Remove the child elements of each element in the collection and remove any associated data and events.

content(string)

Get or set the text content of elements in the collection.

crop()

Crop the dimensions of an <svg> element.

viewbox()

Manipulate an <svg> element’s viewbox attribute as an array of values.

⚓ Duplication

clone([deepDom], [withData], [deepData])

Return a shallow or deep copy of the collection.

duplicate([amount])

Clone the elements in the collection, adding them to the DOM and to the end of the collection.

SVG native symbols and instances

See <symbol> and <use>.

⚓ CSS

These collection methods affect the CSS styling of DOM elements.

css()

Get or set the CSS rules on each element in the collection by setting their style attribute.

addClass(class)

Add a CSS class to each element in the collection.

removeClass(class)

Remove a CSS class from each element in the collection.

hasClass(class)

Return true if any element in the collection has the specified CSS class, otherwise false.

toggleClass(class)

Toggle the addition or removal of the specified CSS class for each element in the collection.

transformCss()

Visually transform the elements, such as rotate, scale or translate them, using CSS transforms.

⚓ Traversal

These collection methods return elements that have DOM-related associations with the elements in the collection.

find(selectors)

Return a collection containing elements that are descendents of the elements in the original collection and match the given CSS selector or comma-separated list of selectors.

children([filter])

Return a collection containing elements that are children of all the elements in the collection.

firstChild([filter])

Return a collection of the first child element for each element in the collection.

lastChild([filter])

Return a collection of the last child element for each element in the collection.

parent([filter])

Return a collection containing the parent element of each element in the collection.

parents([filter])

Return a collection containing all the ancestor elements of each element in the collection.

parentsSvg([filter])

Return a collection containing all the ancestor SVG elements of each element in the collection.

siblings([filter])

Return a collection containing elements that are siblings in the DOM for each element in the collection.

nextSiblings([filter])

Return a collection containing elements that appear later in the DOM for each element in the collection.

prevSiblings([filter])

Return a collection containing elements that appear earlier in the DOM for each element in the collection.

next([filter])

Return a collection containing the next sibling element in the DOM for each element in the collection.

prev([filter])

Return a collection containing the previous sibling element in the DOM for each element in the collection.

root([filter])

Return a collection containing the topmost <svg> ancestor for each element in the collection.

owner([filter])

Return a collection containing the closest <svg> ancestor for each element in the collection.

owners([filter])

Return a collection of all the ancestor <svg> elements for each element in the collection.

viewport([filter])

Return a collection of all the elements that establish the viewport elements for each element in the collection. This is usually the nearest <svg> ancestor.

viewports([filter])

Return a collection of all the viewport ancestors for each element in the collection.

⚓ Data

These collection methods manage the arbitrary data that can be associated with elements.

data([data], [value])

Get or set data associated with each element in the collection.

removeData([key])

Remove data associated with each element in the collection.

⚓ Events

These collection methods manage the native and custom events that can be bound to elements.

on(eventName, fn, [useCapture])

Bind a callback to a DOM or custom event, for each element in the collection.

off(eventName, fn, [useCapture])

Remove one or more event callbacks, for each element in the collection.

one(eventName, fn, [useCapture])

Bind a callback that will fire only once, before being automatically removed.

oneEach(eventName, fn, [useCapture])

Bind a callback that will fire only once per element in the collection.

trigger(eventNames)

Manually trigger one or more events, for each element in the collection.

⚓ Import / Export

These collection methods load and save SVG files and convert.

load(url, [callback], [replace])

Load an external SVG file and append it to each element in the collection.

markup([asCompleteFile])

Get a string of SVG or HTML markup for all the elements the collection.

dataUrl([type], [callback])

Convert the elements in the collection to a data URL for an SVG, PNG or JPEG image.

toCanvas([callback], [canvas])

Convert the elements in the collection to an HTML canvas element.

toImage([type], [callback])

Convert the elements in the collection to a single HTML image element, using either SVG, PNG or JPEG formats.

download([type], [filename], [callback])

Download the collection as a SVG, PNG or JPEG image file.

withViewPort()

Attach the elements in the collection to a new <svg> element, cropped.

⚓ Iteration

These collection methods are used to filter or perform a function on each element in the collection. Most of them are analagous to native Array methods.

each(fn, [context])

alias: forEach(fn, [context])

Call the iterator function for each element in the collection and return the collection.

map(fn, [context])

Call the iterator function for each element in the collection. For any elements returned by the iterator function, return them wrapped in a new collection.

sort(fn)

Re-order the elements in the collection based on the sort function.

pluck(propertyType, [attr])

Return an array of values from each element in the collection - e.g. attribute, data or object properties.

select(filter, [context])

Return a new collection of elements that match the filter, which can be a function, CSS selector or elements. Equivalent to Array.filter

every(filter, [context])

Return true if all elements in the collection match the filter, which can be a function, CSS selector or elements. Otherwise false.

some(filter, [context])

Return true if any elements in the collection match the filter, which can be a function, CSS selector or elements. Otherwise false.

indexOf(filter, [context])

Return the collection index of the first element in the collection that matches the filter, which can be a function, CSS selector or elements. Otherwise -1.

lastIndexOf(filter, [context])

Return the collection index of the last element in the collection that matches the filter, which can be a function, CSS selector or elements. Otherwise -1.

Pablo collections are extended Arrays, so all native Array methods should be supported. For example:

reduce(callback, [initialValue])

Performs a native array reduce() call on the collection, returning the result. The callback is passed previousValue, el, index and collection.