Find file
Fetching contributors…
Cannot retrieve contributors at this time
120 lines (70 sloc) 9.08 KB

See also: the development wiki on github.

Overview of existing packages

Here I present all the existing packages from a developer's perspective: how things work, why they are the way they are, what's uncertain or obviously wrong, what still needs to be done, etc.

Swallowapps specific packages


The visual package deals with instanciating and manipulating visual components created with the editor. It was created with the idea that eventually visual components could render themselves in the DOM, in a Canvas, in WebGL, or any other display system. From the start, the DOM is viewed as a rendering technology, not as a data storage system.

The visual package contains 4 different modules: dirty.js, position.js, themes.js, visual.js.

  • visual.js is the main thing. It defines a Visual as a subclass of EventEmitter (an client side implementation of the EventEmitter class in node) and implements functions that are common to all possible flavors of Visuals.

  • dirty.js implements a dirty list system. The future of this is not 100% system. At this point, since Visuals see the DOM as a rendering technology, they don't need the DOM to keep track of important information like positioning. Every time something is changed (ex: myVisual.setPosition('abc')), the changes are applied immediately to the javascript model but the DOM is only touched at the end of the processing of an event. This adds some complexity that is not necessarily needed (because the browser already deals with finding the right moment for updating things). Thoughts? Comments?

  • position.js implements the positioning system used by visual components. The setPosition function lets you pin a visual to a named position in its container's layout. Whenever the container is resized, children are repositioned. For dom elements, the normal 'absolute positioning' styles of html could have been used but we support more options. The fundamental positioning system use a matrix that is suitable to support 3d transformations (currently the editor does not support 3d manipulators but soon it will).

  • themes.js implements the styling and theming system. Every component can have its own style sheet (called a theme) that is created in the editor and stored as JSON data in the 'vis' file. This maps style data to style names. Style data consists of 'jsData', which is a collection of json encoded css styles (ex: color: {r: 10, g: 100, b: 200, a: 1}) generated by the editor. A style can define all available styles in this collection. A style can also inherit from one or more base styles that can be located in any visual (including visuals coming from other packages). Another notion defined in themes.js is the notion of skinning. The idea behind skins is that you can use a remote component and redefine its theme inside your own component. More concretely, you can use a slider defined in another package, and apply a local style to it. A skin defines a collection of style overrides for styles declared in other components.

An important goal for the visual package is to remain as small as possible. Any idea of simplification or reduction goes in the right direction.


The domvisual package implements the visual model inside the DOM. Domvisual contains the following modules: broweser.js, domhooks.js, domvisual.js, keycodes.js, styles.js.

  • browser.js implements broweser detection (and the current implementation is more than deficient but is sufficient to what I needed so far).

  • domhooks.js exposes DOM events as EventEmitter events. The bridging between DOM events and EventEmitter events is a bit ugly and somehow redoes stuff already done by the browser like preventing events to be fired on Visuals that are not connected to the main document. But the bridging is necessary (if we really want to support EventEmitter), because we don't want a Visual to register to all dom events by default (simply to register to dom events for which listeners have been added). Another ugly thing in this module is the use of events that have a 't' or 'c' suffix. The 'c' suffix is a way of differentiating between the captured and non captured version of an event.

  • keycodes.js transforms event keycodes to strings. The 'VK_' code is generated from the numeric code, and decorations are added for 'Ctrl', 'Shift', 'Meta', etc. This whole thing may be removed or moved to a completely different package (it is currently used in the editor but it should probably be separated from domvisual).

  • styles.js transforms json encoded styles to css styles. Stuff like gradients are converted in a compatible way (moz vs webkit). The whole thing (and the general conversion of json styles to styles and the dirty system should probably be revisited with a critical eye: not ultra urgent because things 'work' but there is probably plenty of room for


This package deals with exposing configuration sheets for components. Components can expose a property sheet that allow them to be configured from the editor. The config package exports the functions that can be used in property sheets. Significant cleanup and improvement needed here.


Utils exposes various functions (like a forEach, isString, isObject, isArray and that kind of stuff) that can be useful in any other package. Finding the most standard (wideley used) naming for these function would probably be appropriate at some point.


This is a temporary solution for transforming the json returned by dox to some HTML. Could be done better with whiskers perhaps. This is only really used in helpviewer (so: even if it can be improved a lot it is not critical to anything).


Exposes an EventSource as an EventEmitter. An http based implementation of EventSource should be added for the many browsers that do not support EventSource yet.


This package exposes a css query function and allows to manipulate a DOM directly. People could use jQuery for the same purpose (but jQuery does more than domquery). One big problem with the current version of domquery is its lack of event related functions. The reason for this is that I don't currently see a way to put a EventEmitter interface in there... This thing is not complete. I don't know how efficient the rudimentary selection system I put in place is (but most of css3 selectors are supported AND the code is easy to understand).


This package contains the visual components that were used to build the editor. These components are built on top of the framework but NOT with the editor that did not exist at that time. Some funky (ugly) stuff can be found in there. Migrating this to something cleanly done with the editor (and cleaned up as much as possible) would be a very useful project at some point.

Packages that implement NodeJS apis


Not much to say.


Not much to say. One non standard function was added to query the listeners without causing the generation of an array.


Not much to say. Well, maybe some would say that the node interface to http is not the easiest to use (but it is very easy to simplify it and doing things the same way on the client and the server is one of my goals). The implementation is not 100% compatible, some things seem difficult to do on the client.


This is the commonJS test thing. Partly implemented in fact. But I don't really use it anywhere. Should probably be removed.


This is the nodeJS url thing but I think that I don't implement the MOST recent thing variation of it.

External packages that have been ported


This is the matrix package that I use everywhere.


Ported from npm. Does not lint properly.


Ported from npm. Does not lint properly.

File format: the 'vis' file

The editor saves its data in a vis file that is in fact a json file. TODO: explain the format (pretty easy to understand by simply reading one of these files)

Current Todo List

Here are things that need to be done:

In the editor:

  • let the user switch between all the vis files of his packages from a single editor page
  • improve style picking (should probably be a popup) and make image picking more similar to style picking
  • add some youtube movies for everything that can be done with the editor
  • add support for all css features (urgent: multiple background image, support of image based background images)
  • add support for fonts
  • add support for 3d transforms (3d manipulators). We don't want to build 3d models, we want simple 3d effects (place positions in 3d).
  • add some minimal support for drag and drop


  • Cleanup (improve consistency of apis, and refactor accordingly)
  • Test (test all standard packages thoroughly)
  • Code reduction (remove stuff that is not absolutely needed or park it in optional packages)
  • Browser compatibility: Not sure I want to support non html5 browsers but a lot of testing and fixing is needed to make everything run smoothly

Coding standard

The coding standard for packages is pretty simple: they should successfully pass the jslint validator. Other than that, packages should be adequately tested (but this is not currently the case with all existing packages).

Discussion Group!forum/swallowapps