Adobe Edge Runtime API - Version 0.1.5

Companion to Adobe Edge Preview 5

Quick Start

Triggers, Events and Actions

In Edge, you can create triggers that will execute your code at a specific position on a Timeline. You can also bind code to the document, Timeline and specific Elements. Your code is called in the context of a Symbol even when handling Element actions. The current symbol is stored in the "this" variable as well as an argument "sym." You can call Symbol APIs like this.play() or sym.play(). The "sym" variable is more durable when you use things like setTimeout.

When your code is called from Edge it is passed an Event object "e" that can be used to learn more about the context in which the handler is being called.

Working with Elements Directly

Often it is necessary to get at the underlying HTML Elements. This is especially useful when handling a click event. The code to access an underlying element with the name "TextOne" is sym.$("TextOne")[0];

Anatomy of an Edge Composition

The HTML Page

Edge inserts a single JavaScript tag in the <head> of the HTML page that causes the composition to be downloaded progressively.

Note: when debugging (especially in Chrome or Safari) you may need to refresh the browser in other to see all the files used by your composition.

<!--Adobe Edge Runtime-->
<script type="text/javascript" charset=\"utf-8\" src="xxxxxx_edgePreload.js"></script>
<!--Adobe Edge Runtime End-->

Important: You must leave the comments intact in order to use the file in Edge.

xxxxxx_edgePreload.js

The xxx_edgePreload.js file pulls in other files needed to run the composition, but does not hold up the page from loading.

Edge Runtime

Edge animations depend on the Edge timeline and symbol JavaScript libraries. This documentation corresponds with version 0.1.5 of those libraries.

jQuery

The Edge runtime depends on jQuery. Version 0.1.5 of the Edge Runtime depends on version 1.7.1 of jQuery.

xxxxxx_edge.js

Edge symbol definitions (graphics and timelines) are stored in these files. Edge overwrites these files each time the composition is saved. If you edit these files directly, any information that Edge does not understand may be lost. Formatting changes to these files will be not be maintained when saved from Edge.

xxxxxx_edgeActions.js

Edge uses anonymous functions to provide encapsulation and restriction of variable scope. The entire xxxxxx_edgeActions.js file is contained in a single anonymous function scope. This provides a place where you can define composition-scoped variables or functions. Be sure to define variables as "var" and functions using a locally scoped syntax.

DO
var myVar = "This is scoped and should not conflict with other code.";
AVOID
myVar = "this is global and might conflict with other code in the page";
DO
function handleClick() { alert('This is scoped properly and should not conflict with other code.'); }
AVOID
window.handleClick=function() { alert('This might conflict with other code in the page.'); };

Edge Symbols

The Edge Runtime is organized around the concept of Symbols. A symbol is a set of behaviors, timelines and graphics that are self contained. The stage is a Symbol and there is always a single root stage in every Edge composition.

The stage and other Symbol instances are "attached" to an element in the DOM. The child elements of a Symbol instance are owned by that symbol and are referred to as Actors.

Symbols are extensible. You can define Actions, Bind events to Actions or otherwise change Symbols "on the fly".

Symbol Closures

//Edge symbol: 'stage'
(function(symbolName) {

//Symbol code
var mySymbolVariable = "hello";

})();

Each Symbol's actions are contained in a JS function closure. This provides encapsulation at the Symbol level.

Edge Triggers, Events and Actions

Actions are bits of JavaScript code (functions) that are executed in response to various types of Events. The binding of an action to an Event, potentially for a given Element can be done either in Edge or in code within xxxx_edgeActions.js. Binding actions in Edge will result in generated code in xxxx_EdgeActions.js. As long as the structure of the generated code and comments is maintained, this code can be hand-edited and later edited in Edge. One thing to note when adding hand-edited code is that it should not be blocking calls like 'alert("Hello");' since this will block the rest of the animation.

Triggers

Triggers can be placed on a timeline at a specific time. When the timeline is playing and reaches the trigger, it executes the specified JavaScript code.

Page DOM Events

Edge exposes the following page level events:

Page DOM Events

Edge exposes the following composition level events:

Element DOM Events

Edge exposes the raw desktop browser element events. Only click is always generated on touch devices. Other mouse events will be simulated if the click event is bound. For touch devices, you can also listen for touch events in addition to the mouse events.

Element Touch Events

Edge exposes the raw device touch events.

Preventing Default Behavior on Element Events

Some browsers, notably Android versions of WebKit, show highlighting around touched elements if you listen for mouse events. If you don't want this to happen, call preventDefault in your handler code, like this:

e.preventDefault();

Timelines Events

Working with Symbols

When using symbol instances and accessing symbol timelines, it’s important to remember that you are handling the element name of the symbol and not the symbol name itself. For example, in my Symbol Library I have a symbol named "kitten_sym". In the elements panel I have an instance of that symbol called "kitten_1". When accessing the symbol, I will be using the name "kitten_1".

Access a Symbol Timeline From the Main Stage

To access the timeline of a symbol from the main stage, use the following in your event:

sym.getSymbol("symbolName").play(); // Plays the symbol timeline

You can also control elements within a symbol from the main stage. For example:

sym.getSymbol("kitten_1").$("kitten_paw").hide(); // Hides the element “kitten_paw” within the symbol “kitten_1”

Access a Symbol Timeline from Within Another Symbol

To access another symbol element from within a symbol, use the following in your event:

sym.getComposition().getStage().getSymbol("symbolName").play(); // Gets the stage from the composition level, then gets the symbol and plays the timeline

To access a nested symbol timeline from within a symbol, use the following:

sym.getComposition().getStage().getSymbol("symbolName1").getSymbol("symbolName2").play(0); // Gets the stage from the composition level, gets the parent symbol, then gets the nested symbol timeline

You can access elements from within a symbol timeline from within another symbol. For example:

sym.getComposition().getStage().getSymbol("kitten_1").$("kitten_paw").hide(); // Gets the symbol element “kitten_1” and hides the element “kitten_paw”

Access a Nested Symbol Timeline from the Main Stage

To access the timeline of a nested symbol, use the following in your event:

sym.getSymbol("symbolName").getSymbol("nestedElementName").play();

You can also access elements within a nested symbol from the stage. For example:

sym.getSymbol("kitten_1").getSymbol("kitten_paw").$("paw").hide();// Hides the element “paw” from within a nested symbol

Access a Nested Symbol Timeline from Another Symbol

To access the timeline of a nested symbol, use the following in your event:

sym.getComposition().getStage().getSymbol("symbolName").getSymbol("nestedElementName").play();

You can also access elements within a nested symbol from the stage. For example:

sym.getComposition().getStage().sym.getSymbol("kitten_1").getSymbol("kitten_paw").$("paw").hide(); // Hides the element “paw” from within a nested symbol

Using Symbol Elements

Formerly getSymbolElementNode();

To access an element associated with a symbol:

sym.getSymbolElement();

This returns returns the jQuery handle for the element. For example:

sym.getSymbolElement().hide();

Another example:

sym.createChildSymbol("kitten_paw", "Stage"); // Creates a new symbol "kitten_paw" on the Stage
var kitten_sym = kitten_paw.getSymbolElement(); // Reference the symbol
kitten_sym.animate({opacity: 0}, 500); // Animates the opacity to 0

Getting Symbol Children

Use the following to target all direct child symbol instances of a parent:

sym.getChildSymbols();

For example, if you set the following in an event on stage level, all direct symbol children of the stage will be affected while grandchildren remain unaltered:

var childSymbols = sym.getChildSymbols(); // Set the child symbols variable
for(var i=0; i<childSymbols.length; i++) // Returns the amount of direct children childSymbols[i].stop(); // Stops all of the children

Getting Symbol Parents

To control a parent symbol, use the following:

sym.getParentSymbol();

This will get the parent symbol of a child. For example:

I have a symbol hierarchy which looks like this: Stage > kitten_sym > kitten_paw. The below code is placed a click event in “kitten_paw”.

sym.getParentSymbol().stop(); // Stops the parent symbol timeline of “kitten_sym”

Dynamically Creating Symbols

To create a child symbol, use the following:

sym.createChildSymbol();

This takes the parent element name and returns a single symbol object. For example:

sym.createChildSymbol("kittenpaw_sym", "kitten") // Creates a child symbol instance of "kittenpaw_sym" inside the element "kitten". Note: "kitten_sym" is the name as it appears in the symbol library, not the elements panel.

Another example:

sym.getComposition().createSymbolChild(("kitten_paw", "body > div"); // This will create an instance of symbol kitten_paw under very div element that's a direct child of the body element.

JavaScript API

Symbol and Composition Extension

These APIs extend a Symbol Definition by adding behaviors which will be inherited by all instances of that Symbol.

Note that xxx_edgeActions.js defines aliases "Symbol" for Edge.Symbol and "Composition" for Edge.Composition. These aliases are used in this section for brevity.

IMPORTANT: The action functions called when the event fires will have "this" set to the Symbol instance. For DOM, timeline and trigger events, the action function takes arguments "sym", which is the symbol instance, and "e" which is a jQuery event. The jQuery event object will have fields set depending upon the actual event type.

bindElementAction

Symbol.bindElementAction ( compId, symbolName, eventName, elementSelector, actionFunction )

bindTriggerAction

Symbol.bindTriggerAction ( compId, symbolName, timelineName, delay, triggerName, actionFunction )

bindTimelineAction

Symbol.bindTimelineAction ( compId, symbolName, timelineName, eventName,actionFunction )

For stop, complete, and play events, the action function takes no arguments. For update events, the argument is elapsed. the milliseconds elapsed since the start of the timeline's playing

bindSymbolAction

Symbol.bindSymbolAction ( compId, symbolName, eventName, actionFunction )

bindAPI

Symbol.bindAPI ( compId, symbolName, apiFunctionName, actionFunction )

Composition Instance Function

These functions act on a particular Composition instance, not a Composition Definition.

getStage

comp.getStage()

Returns the stage symbol instance for the composition. The stage is a Symbol JavaScript object.

getSymbols

comp.getSymbols ( symbolName )

Returns an array of all instances for the specified Symbol name in the composition. If the symbolName is blank, null or undefined, returns all the symbol instances in the composition.

createSymbolChild

comp.createSymbolChild ( symbolName, parentSelector, index )

Creates a new symbolInstance or instances as a child of the element(s) specified by parentSelector, at position "index" among its children. If index is null or undefined, the symbol's element is appended to the parent element's children. parentSelector is a global jQuery selector or handle for any html element(s) that can have child elements.

Returns an array of the new Symbol instance objects created under each of the element(s) specified by the parentSelector.

Symbol Instance

$

sym.$(elementName)

Returns the jQuery handle for the given Element name scoped to the Symbol instance

For Example:
sym.$("Text1").html("Some new text");

lookupSelector

sym.lookupSelector(elementName)

Returns the global DOM selector for the given composition-scoped Element

For Example:
$(sym.lookupSelector("Text1")).html("Some new text");

getComposition

sym.getComposition()

Return the composition that owns this symbol instance.

getSymbol

sym.getSymbol(elementName)

Returns the Symbol Instance object for the given element if the element is a symbol instance.

For Example:
sym.getSymbol("Symbol_1");

createChildSymbol

sym.createChildSymbol(symbolName, parentElementName, index )

Creates a new symbol instance as a child of the symbol-scoped element specified by parentElementName, at position "index" among its children. If index is null or undefined, the symbol is appended to the parent element's children.

Returns a symbol instance object created under parentElementName in symbol scope.

getChildSymbols

sym.getChildSymbols()

Returns the immediate child symbol instance objects of this symbol instance.

getParentSymbol

sym.getParentSymbol()

Returns the immediate parent symbol instance object of this symbol instance.

getSymbolElementNode

sym.getSymbolElementNode()

Returns the DOM element node for this symbol instance object.

Deprecated. Use sym.getSymbolElement instead.

getSymbolElement

sym.getSymbolElement()

Returns the jQuery handle to the DOM element for this symbol instance object.

setVariable

Formerly sym.setParamater();

sym.setVariable ( varName, varValue )

Sets the given parameter to the value provided. varName should be a string, but varValue can be any type.

getVariable

Formerly sym.getParamater();

sym.getVariable ( varName )

Returns the value of the given variable or undefined if the variabke is not found. varName should be a String.

play

sym.play ( position, executeTriggers )

Play the default timeline from the given position given in ms (if the parameter is a number) or as a label (if the parameter is a string). "position" defaults to the current playhead position (which defaults to 0); If play is issued and the playhead is at the end of the timeline, play from 0. "executeTriggers" indicates whether triggers at the starting position are fired. If "executeTriggers" is true, all triggers at the starting position are fired. If "executeTriggers" is false, no triggers are fired at the start point. If "executeTriggers" is null, undefined or omitted, triggers are fired at the starting position only if the timeline is being played for the first time, or if the starting position is different than the current playhead position as returned by getPosition().

playReverse

sym.playReverse ( position, executeTriggers )

Play the default timeline in reverse from the given position given in ms (if the parameter is a number) or as a label (if the parameter is a string). "position" defaults to the current playhead position (which defaults to 0); If play is issued and the playhead is at 0, play from the end of the timeline. "executeTriggers" indicates whether triggers at the starting position are fired. If "executeTriggers" is true, all triggers at the starting position are fired. If "executeTriggers" is false, no triggers are fired at the start point. If "executeTriggers" is null, undefined or omitted, triggers are fired at the starting position only if the timeline is being played for the first time, or if the starting position is different than the current playhead position as returned by getPosition().

stop

sym.stop ( position )

Stops the default timeline at the position given in milliseconds (if the parameter is a number) or as a label (if the parameter is a string). "position" defaults to the current playhead position.

getPosition

sym.getPosition ()

Returns the current playhead position of the default timeline.

getDuration

sym.getDuration ()

Returns the duration of the default timeline.

isPlaying

sym.isPlaying ()

Returns whether the default timeline is playing.

isPlayDirectionReverse

sym.isPlayDirectionReverse ()

Returns whether the default timeline play direction is reverse.

getLabelPosition

sym.getLabelPosition (aLabel)

Returns the position of the label "aLabel" in the default timeline, or undefined if "aLabel" is not a label on the timeline. Behavior is not guaranteed if "aLabel" is not a string.

deleteSymbol

sym.deleteSymbol ( options )

Delete this Symbol Instance as well all of its DOM elements.

Edge

The Edge interface is attached to the jQuery object. You can call jQuery.Edge.* or $.Edge if you are in a scope where $ is the same as jQuery.

Edge.getComposition

jQuery.Edge.getComposition( compId )

Return an Edge.Composition object for the given compId (provided one exists).

new Edge.Composition

new jQuery.Edge.Composition ( compId, symbolData, attachments, options )

Edge.registerCompositionReadyHandler

jQuery.Edge.registerCompositionReadyHandler( compId, handlerFn, options )

Registers a function that is invoked when the Composition with the given compId has been loaded and initialized.



Advanced Topics

Multiple Compositions in a Page

Edge now support multiple compositions in a single HTML page. As of Edge Preview 4, opening a page with more than one composition in it is not supported, but pages can be hand-authored to use multiple compositions.

Each xxxx_edgePreload.js file causes the definition for a single composition to be included in the page. You can include multiple compositions by including multiple composition preload JS files. Remember to move any images, CSS or other resources any of the compositions might need.

<!--Adobe Edge Runtime-->
<script type="text/javascript" charset="utf-8" src="composition_one_edgePreload.js"></script>
<script type="text/javascript" charset="utf-8" src="composition_two_edgePreload.js"></script>
<!--Adobe Edge Runtime End-->

Each composition requires a stage Element to attach to:

<div id="stageOne" class="EDGE-1010101"></div>
<div id="stageTwo" class="EDGE-8338338"></div>

In this example...

composition_one_edgePreload.js has the composition ID set to EDGE-1010101 at the end of the file:

})(jQuery, jQuery.Edge, "EDGE-1010101");

composition_two_edgePreload.js has the composition ID set to EDGE-8338338 at the end of the file:

})(jQuery, jQuery.Edge, "EDGE-8338338");

Positioning the divs

By default, Edge makes sure that a stage div is positioned. If the div is not positioned either absolute or relative with CSS, Edge makes it "position: relative" so all of its elements are animated relatively to the stage, rather than the page.. You will need to use either flow-based or absolute position CSS to put your stages where you want them in your page.

Calling Edge APIs on a different composition

Edge APIs can be called specifying the composition ID see Edge.getComposition(compId).