David Deraedt

Now that it's almost ready for launch, I think it's time to take a little more in-depth look at Edge Animate, from a technical perspective. As it's very likely to change over time, I'll try to maintain a (totally unofficial) reference over at my github, much like I did for Brackets.

Consider the following blog post as a glorified snapshot of the first part of this document. The second part is more focused on symbols and scripting and is available here. If want to check the latest version, go check / clone / fork its repo. This will probably be obsolete sooner or later, when Edge Animate has a proper documentation, but that's not the case for now.

Core concepts

At its core, Edge Animate is a tool which lets you animate DOM elements in visual way. The resulting animations, called compositions, can be published in any context capable of displaying modern web content, whether it's a web page, or, say, the Web View control of a native mobile app.

An Edge composition is typically displayed in a <div> of an HTML page. An HTML page can hold several compositions -- even though the tool can only edit one composition at a time.

The tool also lets you edit a whole pre-existing HTML page. In that case, the page itself is the composition, and each animated element will be added a single CSS class (edgeLoad-XXXXX). But the overall idea is pretty much the same in both cases.

By default, DOM elements created within the tool will be injected at runtime (ie in the HTML page source file, the stage <div> is empty). You can also choose to publish it as static content for better SEO.

Compositions manipulate DOM elements using a javascript framework called the Edge runtime, which has several dependencies, including jQuery.

File structure of an Edge Animate project

Here's a very humble animation I made to explain this structure, mainly for fun. The source is also availble in the repo.

Below it is a text only, shorter text description.

Here's a short description of each file involved (assuming your page was named index).

• index.an is a JSON file used by the authoring tool to open the project (not to be published).
• index.html is the host HTML file
• index_edgePreload.js is the yepnope based loader which loads everything else.
• index_edge.js describes the composition content (assets, symbols, timelines)
• index_edgeActions.js holds the custom javascript code added by the user
• images (folder) contains all images used by the tool
• edge_includes (folder) contains all required libraries:
  • JSON2: a library for working with the JSON format
  • jQuery
  • jQuery easing: a jQuery plugin describing easing functions for animations
  • Edge: the core Edge Animate library describing all JavaScript objects and classes used by an animation

Let's take a deeper look at the latter and what it creates exactly.

Main Javascript architecture

The role of compositions is to animate visual elements like text and images through their corresponding DOM element. If using javascript, you can typically manipulate those DOM elements using jQuery and, optionally, some of its plugins.

Rather than being an alternative to this method, the Edge animate library augments it in several ways, by describing a framework to make it easier to work with animations.

At the very top level of a page containing Edge Animate compositions, attached to jQuery, is one unique global Edge object, which knows about all compositions in the page.

Each composition object has exactly one Stage object, which can be considered as the root of the scene graph (the equivalent of root in flash animations).

The stage has a timeline using which lets you define animations of its child elements over time. That is because the stage is a particular kind of object named symbol.

Symbols vs. DOM elements

Symbols are objects which have a timleline using which you can animate its child elements. To manipulate this timeline, symbols have an API with methods such as play() and stop().

Symbols are reusable, so we need to distinguish between the symbol definition --which you can find in the Library panel-- and a symbol instance -- which you place on the stage and is actually used in the DOM.

For those of view coming from a Flash background, this will probably remind you of the notion of a MovieClip.

However, a symbol instance is not to be confused with its corresponding DOM element. It is not a visual object. A symbol instance can access its underlying DOM elements (usually through a jQuery handle), but those are different objects altogether.

Symbols can have child symbols, but again, those children are other symbol instances, not DOM elements.

symbol -(1-n)-> child symbols -(1-n)-> child symbols (…)

The DOM element tree is a parralel but separated hierarchical tree.

Note: The stage itself is a symbol, which is why it has timeline. However, it cannot be reused (you don't see it in the Library panel).

As a reminder, all Symbol definitions, DOM Elements descriptions, timeline content are all described in the index_edge.js file. You could edit this file manually to modify the content of a composition, however you should be careful in doing so because it might break the ability of the tool to reopen and modify the composition. The best advice is to stay as close as possible to the syntax originally generated, including comments.

Now, let's get deeper into scripting and symbol implementation in part two.