Edge Commons - Dirty Little Helpers for Edge Animate

The purpose of this extension library is to improve the workflow and enhance the possibilities of Animate compositions. There are several components available, such as Parallax Scrolling, Spotlight Overlay or Adaptive Layouts. The components listed here are already tested and documented. We are, however, steadily working on new features and components.

The Edge Commons are completely open source and therefor free to use in personal and commercial projects. If you are interested, you can also contribute to the project on GitHub.

This page will take you through the current features and will also explain, what the Edge Commons are and how you can include them in your projects. You don't have to code yourself, you can simply follow the instructions and copy all the code you need from this page.

Feature Overview:

Using Edge Commons
Helper Functions
Parallax
Spotlight
Adaptive Layouts
Sound
Interactive SVG
Advanced Logging
Configuration Management

Watch Adobe TV episode on Edge Commons now

In this episode you will learn everything about Edge Commons. This video covers the integration process and shows how to use the Spotlight feature for media overlays.

Using Edge Commons

The Edge Commons library consists of several packages. If you are new to Edge Commons we recommend the “All-in-one” package. This package includes all available features (except the experimental ones). If you deploy your final compositions you should consider loading only the modules that you actually use.

There are two ways to add Edge Commons to your Animate project:

(1) Loading at runtime

You can simply use Animate’s built-in function “yepnope()” to load the library at runtime (e.g. at “creationComplete” of your stage). In this case you can download the Edge Commons files (http://cdn.edgecommons.org) and extract them to a folder relative to your projec (e.g. /libs). The easier way, though, is to use the hosted files from the public server (http://cdn.edgecommons.org). In this case you don’t have to download anything at all. To load the downloaded or hosted library at runtime you can use one of the following snippets:

Basic loading procedure (be careful with this one. You have to make sure that everything is loaded properly before actually using the Edge Commons features.)

// Load All-in-One (in creationComplete)
yepnope( { load: "http://cdn.edgecommons.org/an/1.0.0/js/min/EdgeCommons.js" } );

Recommended loading procedure with complete callback (using the EdgeCommons features within the complete function is safe)

// Load All-in-One (in creationComplete)
yepnope({
    load: "http://cdn.edgecommons.org/an/1.0.0/js/min/EdgeCommons.js",
	complete: function() {
		EC.debug("Ready to go!");
	}
});

If you decide to only load specific modules you can setup the list of files to load like this:

// Load specific Modules (in creationComplete)
yepnope({
    load: [
		"http://cdn.edgecommons.org/an/1.0.0/js/min/EdgeCommons.Core.js",
		"http://cdn.edgecommons.org/an/1.0.0/js/min/EdgeCommons.Spotlight.js",
		"http://cdn.edgecommons.org/an/1.0.0/css/style.css",
	],
	complete: function() {
		EC.debug("Ready to go!");
	}
});

(2) Using script tag in head section

If you don’t want to handle the asynchronous loading process at runtime, you can of course add the reference to the JavaScript file to the <head> section of your html document:

<head>
  <!-- EdgeCommons All-in-one -->
  <script src="http://cdn.edgecommons.org/an/1.0.0/js/min/EdgeCommons.js" type="text/javascript"></script>

  <!-- EdgeCommons Spotlight CSS -->
  <link href="http://cdn.edgecommons.org/an/1.0.0/css/style.css" rel="stylesheet">
</head>

Helper Functions

The clue is in the name: Dirty Little Helpers. There are several modules but also some smaller helper functions available, e.g. to load/nest compositions or to get the name of dynamically created symbols.

Center Stage

Edge Animate places the stage of the composition in the upper left corner. If you want to center the composition you can simply use EC.centerStage(sym); after loading the Edge Commons. Right now only a horizontal centering is possible. In future versions even vertical centering will be possible.

Composition Loader

This feature enables the integration of separate Animate composition into a container within your composition. Entire websites can be built this way and several persons can work independently on one project.

With Composition Loader you can create nested compositions like these:

getSymbolName

With this little helper you can get the name of any symbol in your composition. This is necessary for referencing and to store the name for other purposes.

Parallax

This feature enables the integration of separate Animate composition into a container of another composition. Entire websites can be built this way and several persons could work independently on one project.

Parallax: Simple example

The following listing shows how to enable the Parallax scrolling effect:

EC.Parallax.setup( sym );

This script requires the Edge Commons library to be loaded. This can be achieved by placing the following script to the creationComplete handler of the stage:

yepnope({
    load: "http://cdn.edgecommons.org/an/1.0.0/js/min/EdgeCommons.js",
	callback: function() {
		EC.centerStage(sym);
		EC.Parallax.setup(sym);
	}
});

[TODO: Link to live demo]

Spotlight

The Spotlight features can display different media types in nice looking and animated overlays (similar to popular lightbox/colorbox component). Currently Spotlight supports three media types: images, Animate compositions and YouTube videos. The Edge Commons library has to be loaded before using the Spotlight feature (see section "Using Edge Commons" for more details).

Spotlight: Simple image overlay

The following code shows how to use Spotlight to show an overlay with an image:

// Open Spotlight Overlay with Image
var config = {
    width: 700,
    height: 500,
    type: "image",
    source: "images/PATH_TO_IMAGE.png"
};		

EC.Spotlight.open( config );

You can also use Spotlight to display Edge Animate compositions or YouTube videos (see other examples)

Spotlight: Overlay with Edge Animate composition

The following snippet shows how to use Edge Animate compositions in overlay:

// Open Spotlight Overlay with Animation 
var config = {
    width: 500,
    height: 500,
    type: "animate",
    source: "composition/index.html"
};		

EC.Spotlight.open( config );

Spotlight: Overlay with YouTube video

It's even possible to use a YouTube video within an overlay. In this case you have an additional flag to control the auto play behavior of the video:

// Open Spotlight Overlay with Youtube Video 
var config = {
    width: 800,
    height: 600,
    type: "youtube",
    source: "1woru3cyFiw",
    param: {
        autoPlay: true
    }
};		

EC.Spotlight.open( config );

Spotlight: Configuration details

// Spotlight configuration
var config = {
    width: WIDTH_OF_OVERLAY_CONTENT,    // eg 600
    height: HEIGHT_OF_OVERLAY_CONTENT,  // eg 400
    borderWidth: BORDER_WIDTH,          // eg 15
    borderColor: BORDER_COLOR,          // eg "#222"
    type: CONTENT_TYPE,                 // eg "image", "animate" or "youtube"
    source: CONTENT_SOURCE,             // eg "images/image.png" or "Animation.html" or "1woru3cyFiw" (YouTube ID)
    param: {
        autoPlay: AUTO_PLAY             // true or false (only for YouTube)
    }
};		

EC.Spotlight.open( config );

Live Demo

With Spotlight you can create overlays like these:

Adaptive Layouts (independent layouts for specific sizes)

Edge Animate let's you create flexible layouts with percentage values. In most of the cases it is not enough to just use this technique, because many compositions do not scale well from narrow smartphone width to high definition desktop screens. So if you want to create independent layouts for different resolutions, this is the right feature for you. Since Edge Animate does not support real media queries in the current version, this approach is not really responsive design. But it's the perfect interim solution.

Setup

First of all you need a rectangle (div container) on the stage (width=100%) with the name "adaptiveContainer". After loading EdgeCommons you can define different layouts by simply calling EC.setAdaptiveLayouts( ) and passing in an array of sizes. The second argument is a reference to the stage symbol (simply "sym") and the third argument is the name of the target container (e.g. "adaptiveContainer"). The sizes will automatically be mapped to the corresponding symbols with the prefix "layout" (e.g. layout600 or layout1200) in the library.

yepnope({
    load: "http://cdn.edgecommons.org/an/1.0.0/js/min/EdgeCommons.js",
	callback: function() {
		EC.setAdaptiveLayouts( [400, 600, 1200], sym, "adaptiveContainer" );
	}
});

You find a detailed video tutorial about this feature at Adobe TV: Open Episode at Adobe TV

Sound

EC.Sound is a simple wrapper for SoundJS that enables Edge to play all kind of sounds easily. You first have to setup the sound system by creating a simple manifest (Array with all sound references) and pass it to the setup() method. Then you can use the play() method to play the sounds. So let there be sound!

Prepare sounds

Since the sounds have to be HTML5 compatible you should convert your sound files to MP3 and OGG. Adobe Audition is our tool of choice. But you can of course use all sound tools that can export these formats.

Load sounds

Use EC.Sound.setup() function to setup a sound manifest and start loading the sound files.

// Load sound manifest (e.g. in creationComplete)
var assetsPath = "media/";
EC.Sound.setup(
    [
        {src: assetsPath + "bassdrum.mp3|" + assetsPath + "bassdrum.ogg", id: "bassdrum"},
        {src: assetsPath + "snaredrum.mp3|" + assetsPath + "snaredrum.ogg", id: 'snaredrum'}
    ],
    function(){ EC.info("Sound setup finished", "DEMO"); }
);

Play sounds

Playing a sound file is pretty simple. You can use the play() function and pass in the id you defined in the manifest before:

// Play sound (e.g. on click)
EC.Sound.play("bassdrum");

Issues

For playing sound right after setting up the manifest you can the callback function which is the 2nd argument of the setup() method. This will be called when setup is finished and sound is ready to play.
The ability to play sounds depends on the browser. Older browsers may not support sound in HTML. Checkout docs of SoundJS for more information.
Due to a bug sounds only play once when you start the composition from Edge Animate (http://127.0.0.1:54321/PATH/...). If you use a Apache or publish your composition it works fine.

Live Demo

With Composition Loader you can create nested compositions like these:

Interactive SVG

Currently Edge Animate only supports SVG files within <img> tags or as background images in <div> containers. So you can neither listen for SVG events nor reach into the SVG structure to e.g. change the color of a shape. With the "interactive SVG" feature provided by Edge Commons you can enable on this. And the great thins is, that you still can place and animate the SVG as you always do.

Listen for custom event dispatched by the SVG

The following code snippet enabled the interactive SVG feature on a SVG asset named "character" that is placed on the stage. With the done function you are able to listen for the activation process to be completed and you get a reference to the actual SVG document passed in as a parameter (svgDocument). This reference can then be used to add event listener or change the SVG content (shapes, paths etc.) programmatically.

// Load Edge Commons
yepnope({
    load: "libs/EdgeCommons.js",
    complete: function() {
		// Enable SVG access
		EC.accessSVG(sym.$("character")).done(
			function(svgDocument){
				// add event listener
				svgDocument.addEventListener("select", function(event) {

					// Remember selected part
					sym.setVariable("selectedPart", event.target);

					// show the id of the selected part in the textfield
					sym.$("selectedPartTxt").html( event.target.id );
				});
		});
	}
});

Live Demo

With Interactive SVG you can something like this:

Advanced Logging

When your compositions get bigger and your scripts more complex you can't live without it: Logging. With EdgeCommons you get more advanced logging capabilities than console.log.

Using Logging with Edge Commons

Let's keep it simple

// Simple log to the console
EC.info( "Logging with EdgeCommons is easy" );

Different log levels

EC.info( "Message" );
EC.debug( "Message" );
EC.warn( "Message" );
EC.error( "Message" );

Logging groups (works with all levels)

EC.info( "Message", "GROUP NAME" );
EC.info( "Message", "Compostion Intro" );

Dumping complex data types to the console (works with all levels)

EC.info( "Message", "GROUP", complexObject );
EC.info( "Message", "GROUP", sym );

Setting the current log level (filter)

// No logging at all
EC.Log.level = EC.Log.LEVEL_NONE;
// Only log error
EC.Log.level = EC.Log.LEVEL_ERROR;
// Only log warn and error
EC.Log.level = EC.Log.LEVEL_WARN;
// Only log info, warn and error
EC.Log.level = EC.Log.LEVEL_INFO;
// Log everything
EC.Log.level = EC.Log.LEVEL_DEBUG;

Additional log targets (e.g. alert, server call to send email etc.)

// Add log target to also alert the logs
EC.Log.addLogTarget(function(msg){
  alert(msg);
});
EC.error("This is a error log in the console AND as alert dialog");

Configuration Management

Sometimes you want to have a global configuration that can be used all over your composition easily. With EdgeCommons you get the infrastructure to setup a configuration object using an external JSON file or set it up during initialization of the composition.

Setup during initialization (e.g. in compositionReady)

You can simply init the global configuration object by passing a object to the init() method:

EC.Config.init({
    url: "http://www.some-url.com",
	user: {
		firstname: "Simon",
		lastname: "Widjaja"
	}
});

Setup with external JSON file and ready callback:

You also can use an external JSON file and a callback function that will be called when the configuration is loaded. You can use this callback function to use the configuration directly or start playing the composition initially.

EC.Config.init("config.json", function() {
    EC.info( "External config is ready" );
    var testUrl = EC.Config.get( "testUrl" );
    sym.$("txtConfigTestUrl").html( testUrl );
});

The external JSON file could look like this:

{
    "testUrl": "http://localhost/cms",
    "url": "http://www.some-url.com/cms",
	"user": {
		"firstname": "Simon",
		"lastname": "Widjaja"
	}
}

Reading configuration values

EC.Config.get("CONFIG_PATH");

EC.Config.get("user.lastname");

Setting configuration values manually

EC.Config.set("CONFIG_PATH", value);

EC.Config.set("emailURL", "http://www.mydomain.com/email.php");