PERGOLA JavaScript Library for SVG
The framework that swings SVG into action. Easy. Flexible. Innovative.

OVERVIEW

Pergola is a JavaScript SVG native framework with libraries of controls, widgets, services, and SVG objects (filters, patterns, etc.). Its API allows you to produce works ranging from bare artwork, through the simplest presentation or web page, to the most complex web app of systemic type. Its Object Oriented Development model is designed to be used internally by its classes, and by the developer, in a consistent manner across all the development phases. Classes and inheritance model are pure JavaScript. Pergola does not define a proprietary pseudo-language. Its development started in 2007 after a design resulting from exhaustive research, and never needed a redesign, or rewriting.

DOM

Pergola does not define any pseudo-language or proprietary representation of the DOM classes and methods. Instead it exposes the SVG library (the browser's implementation) directly thanks to its progressive DOM helper, which is at the core of all the building blocks of the Pergola classes as well as the user's objects. This is done through the pergola.SVG() function and its derivatives pergola.HTML() and pergola.HTML_FO(). Those functions are therefore interfaces to instantiate SVG elements while accepting the complete collection of any element's attributes to set/override, in one pass, using directly SVG (or HTML) vocabulary and grammar (the rationale behind this concept is explained in this article in the July 2011 issue of SVG magazine). It also means zero learning curve, because the attribute values are clearly specified as attribute value pairs, and don't need processing, unlike libraries using the fossil method of defining redundant proprietary classes like “paper.rect” or “paper.circle” and the like, expecting anonymous parameter values relating to the limited subset of an element's required attributes, then expecting calls to other methods for setting attributes, possibly with proprietary attribute names, as in textAnchor (proprietary representation) vs "text-anchor" (qualified property), the former needing processing. This, along with other innovations, gives a terrific edge to Pergola in terms of performance, capabilities, and conciseness.

CONTEXTS

Pergola runs equally well in a standalone SVG context or in HTML. All the examples are shown in HTML and you will find the same examples 100% SVG in the package. The selection is done in the configuration file bound to each project. Learn more in the Configuration section of the Tutorial.

CLASSES

One of the core components of Pergola is a comprehensive collection of classes specializing in the production of system objects, widgets, and services. Classes are bound to the pergola namespace, and most of them inherit from the Class superclass, which defines prototype methods and other generic properties. The classes define prototype extensions, basically specific properties and methods.

The pergola object defines also the Undo class, the Timer class, the Key class, the DOM functions, a collection of geometry functions, a collection of color functions, class operations functions, loading external resources functions, miscellaneous functions, system constants, references to system components, libraries, and builds the system layers structure in the DOM. The overhead weight of the system built by Pergola is light, partly due to lazy loading for several system components. Full scale applications are very fast and reactive.

Pergola implements both method chaining and deferred construction for instantiation. The latter gives a range of opportunities like predefining objects and their component objects, dynamic or conditional construction, capability of self-referencing and of accessing the inherited properties and methods. Instantiation is dissociated from construction.

LIBRARIES

Pergola libraries define essentially SVG objects. A library is an object bound to the pergola namespace. The libraries defined by Pergola are:

pergola.filters is an object whose properties are functions that create a filter object with unique ID based on initial and overridden values, and append it to pergola.defs if it doesn't exist. The filter functions expect an optional object specifying filter attributes to override the default values. The property names use SVG vocabulary, and names containing illegal characters for JavaScript variable names are specified using the string notation, for example "flood-opacity". The function returns the URL string.

See Filter examples.

pergola.patterns is an object whose properties are functions that create a pattern object with unique ID based on initial and overridden values, and append it to pergola.defs if it doesn't exist. The pattern functions expect an optional object specifying overriding properties. Some properties have arbitrary names, and some use SVG vocabulary (names containing illegal characters for JavaScript variable names are specified using the string notation, e.g. "stroke-width"). The function returns the URL string.

See Pattern examples.

pergola.markers is an object whose properties are functions that create a marker element and append it to pergola.defs if it doesn't exist. The function returns the URL string.

See Marker examples.

pergola.shapes is an object whose properties represent a collection of shapes. Each object property defines the element string property –typically "path", "polyline", "polygon", but can be any primitive– and the corresponding geometrical attribute(s) ("d", "points"). A shape object does not define paint attributes. Each object property defines the element string property –typically "path", "polyline", "polygon", but can be any primitive– and the corresponding geometrical attribute(s) ("d", "points"). A shape object does not define paint attributes, leaving total control over stroke width/scaling. To use a library shape you invoke the pergola.use() utility function.

See Shape examples.

pergola.symbols is an object whose properties represent a collection of symbols. Each property is an array with one or more object elements defining SVG primitives, or text, or image elements, in the format expected by the pergola.SVG() node builder (without the appendTo property). A library symbol can be referenced when instantiating a class that implements the symbol property, or can be used as standlone by passing it to pergola.symbol() utility function.

See Symbol examples.

pergola.cursors is a function that defines and appends cursors elements to the pergola.defs.

REQUESTS

Pergola provides a set of utilities that allow to:

It also provides the File Dialog, which shows the updated file list in the specified directory and allows “Open” and “Save As” operations.

LOOK & FEEL

Pergola has a versatile pergola.skins library. A skin is a function, and the name of the skin to use for a project is set in the config file, where you also set the theme color (any legal RGB value, color keyword, or custom color keyword):

The function creates the presentationAttributes object, where initial values for the prototype properties of all classes are defined. Those prototype properties are then simply references, the values are hardcoded in the skin file, so you don't need to go through the headache of hacking a class. You edit the skin instead. So far then the skin behaves much like a style sheet for SVG presentation attributes. Where it becomes interesting is that you can have multiple definitions of the same classes in one unique file. This means that different projects can share the same sheet. Unlike what happens for style sheets, the new class definitions do not override the previous ones.

The function also builds gradients and patterns referenced by the skin properties, and any other gradient or pattern that you may need to define for your objects. To learn more read the Skins and Making A New Skin sections of the Tutorial.

SYSTEM LOGIC AND HIERARCHY

At runtime Pergola establishes layers hierarchy: pergola.desktop is first created and appended to pergola.doc; pergola.user and pergola.systemComponents are then created and appended to pergola.desktop.

The pergola.user layer is a safe residence for your objects, but this is in no way a requirement, you can append Pergola objects or other elements anywhere in the document, knowing however that they might partially mask some higher ranking layers with system objects (dragarea, preemptive dialogs, context menus, etc.).

All classes implement system logic, where applies. The system is unobtrusive and transparent. Several system components–as well as outputs of libraries components– use lazy loading, and only some system objects like pergola.dragarea, pergola.rubberBox, and pergola.coordinates are created at runtime. Therefore the overhead weight of the system ir irrelevant in small applications, and in all cases, it never affects performance or usability. Where you may encounter minor preformance bottlenecks, is in overloading the DOM with several thousands+ text elements (as in a datagrid for example) or image elements. Note however that the continuous evolution in hardware and browsers' performance gradually minimizes the impact of this traditional issue.

INTERACTIVITY AND ACCESSIBILITY READINESS

User events and functions are implemented in all the low level component classes. They are defined during instantiation by setting the instance properties ev and/or fn. The ev property gets an event type string or array of one or more event type strings that are all registered with the same fn callback function. The fn property can be of different types, function/method name, function literal, or string, to cope with a variety of situations. This consistent and powerful feature is well documented and widely used throughout the examples. This, together with the possibility of overriding properties and methods, allows the addition of accessibility extensions by developers with the right know how, who may also find interesting the possibility of defining a global accessibility skin.

COMPATIBILITY

Pergola is compatible with all the major SVG implementations: Firefox, Opera, Safari, IE 9+, Chrome, ASV *.

*Compatibility with ASV is ensured up to version 1.3.7, except for mapping extensions. It was abandoned definitively from version 1.3.8.