Adobe Edge Runtime API - Version 0.1.6

Companion to Adobe Edge Preview 6

Updated API Available

Quick Start

Triggers, Events and Actions

In Edge, you can create triggers that 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 calling your code, Edge passes an Event object, e, which you can use to learn more about the context in which the handler is being called.

Working with Elements Directly

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

Edge Runtime

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

jQuery

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

Anatomy of an Edge Composition

The HTML Page

Edge inserts a single JavaScript tag in the <head> of the HTML page, which 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="project-name_edgePreload.js"></script>
<!--Adobe Edge Runtime End-->

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

project-name_edgePreload.js

The project-name_edgePreload.js file imports other files needed to run the composition, but does not prevent the page from loading.

project-name_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 are not maintained when saved from Edge.

project-name_edgeActions.js

Edge uses anonymous functions to provide encapsulation and restriction of variable scope. The entire project-name_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 using 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 self-contained behaviors, timelines, and graphics. 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

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.

Events

Page-level DOM Events

Edge exposes the following page level events:

Composition-level 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();

Timeline Events

Symbol Events

Actions

Actions are JavaScript 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 project-name_edgeActions.js. Binding actions in Edge will result in generated code in project-name_EdgeActions.js. As long as you maintain the structure of the generated code and comments, 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 in blocking calls, such as 'alert("Hello");' since this blocks the rest of the animation.

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:

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

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

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

Access a Symbol Timeline from Within Another Symbol

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

// Get the stage from the composition level, get the symbol, and play the timeline
sym.getComposition().getStage().getSymbol("symbolName").play();

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

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

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

// Get the symbol element "kitten_1" and hide the element "kitten_paw"
sym.getComposition().getStage().getSymbol("kitten_1").$("kitten_paw").hide();

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:

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

Access a Nested Symbol Timeline from Another Symbol

To access the timeline of a nested symbol from another 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:

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

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:

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

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:

// Set the child symbols variable
var childSymbols = sym.getChildSymbols();
for(var i=0; i<childSymbols.length; i++) // Return the number of direct children
   childSymbols[i].stop(); // Stop 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”.

// Stop the parent symbol timeline of "kitten_sym"
sym.getParentSymbol().stop();

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:

// Create 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.
sym.createChildSymbol("kittenpaw_sym", "kitten")

Another example:

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

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 project-name_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, elementSelector, eventName, 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. Returns -1 if the timeline has never been played.

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 project-name_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).