libsvg.js is a javascript library to aid in the development of SVG application.
It does not try to provide a new API to replace the native JavaScript APIs or provide abstractions, as other popular JS library do (Raphael or svg.js). The goal is to complement the existing native JavaScript APIs and to make these APIs easier to use in the context of an IDE by providing js-documented prototypes that the IDE can use for code completion, contextual documentation an code analysis. I use and develop the API in conjuction with the WebStorm IDE, but other IDEs could be used as well (NetBeans, Aptana, Eclipse + JS…) provided they have good support for jsdoc and js prototype declaration analysis.
The library is hosted on Github at https://github.com/laaglu/libsvg.js.
An example of published code using the API is the FirefoxOS push puzzle, playable at http://push.fos-games.org and hosted on Github at https://github.com/laaglu/push-puzzle.js.
libsvg.js comes itself is made up of two files:
- libsvg-ide.js
- is just a collection of JavaScript prototype declarations, adorned with documentation extracted from the spec and injected at the proper location as jsdoc comment. If your IDE is smart enough (Webstorm actually is), it will be capable to infer the type of js variables and provide autocompletion and contextual documentation based on this file, as well as warn you of errors if you do not respect the method signatures. The file is not intended to ever be loaded by an actual web browser. It just lives in the IDE as a helper, you do not need or want it in actual production.
- libsvg.js
- contains the utilities part of lib-gwt-svg, as well as helper methods to help the IDE infer the proper type for JS variables method.
In libsvg.js, there are two main classes of helper methods provided.
- Factory methods
- have been added to the Document prototype to let you create SVG elements from scratch:
// Create a circle using the extra factory method added to the Document prototype.
var circle = document.createSVGCircleElement();
// Now the IDE is aware of the type of the circle variable, because it has read the prototype and javadoc of SVGCircleElement from the libsvg-ide.js file and knows createSVGCircleElement returns a SVGCircleElement. The line below is typed with autocompletion.
var circle.cx.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PX, 100); - Hinter methods
- have been added to the Element prototype to let you specify the type of elements you retrieve using calls to getElementById, XPath, DOM traversal. Technically, these methods do nothing except return the element itself, but they do it with a properly crafted jsdoc comment which the IDE can use to infer the type of the element. This presents an overhead, but it is tolerable in most cases and JS optimizers are probably capable of figuring out they are useless at runtime and eliminate the extra code altogether (though I have not verified this claim !).
var circle = document.getElementById("c1").asSVGCircleElement();
// Now the IDE is aware of the type of the circle variable, because it has read the prototype and javadoc of SVGCircleElement from the libsvg-ide.js file and knows asSVGCircleElement returns a SVGCircleElement. The line below is typed with autocompletion.
var circle.cx.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PX, 100);