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:

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.

You can either download the library or use the live version from our public server (CDN): http://cdn.edgecommons.org

Since the last update to Animte CC (3.0) in january 2014 you can use the library panel in Animate to add the Edge Commons library easily:

Video:

 

Step by step:

 

(1) Go to http://cdn.edgecommons.org and choose your package (if you are not sure which suits your needs, choose "All-in-One")

 

(2) In Edge Animate click on the "+" icon in the scripts panel of your library. Select "from URL" for the CDN version of Edge Commons. Otherwise choose "from Disk" if you have downloaded the library.

(3) Now Animate asks for the location/URL of the external library. Paste the URL from the CDN server

 

(4) The Edge Commons library should appear in the scripts panel. Now you can start using all the cool Edge Commons features in your composition. You can e.g. activate the Parallax feature in "creationComplete" of your stage like this: 

EC.Parallax.setup(sym);

 



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:

The usage of the loadComposition() function is pretty straight forward. The first argument is the path to the Animate composition and the second argument is a reference to the target symbol. Here's a basic example:

// Load external Composition into symbol named "content"
EC.loadComposition("external_composition/index.html", sym.getSymbol("content"));

You also can inject data into the composition and listen for events that are dispatched by the external composition. Here's a more complex example:

// Load Third Composition and inject data
var promise = EC.loadComposition("composition3/index.html", sym.getSymbol("content"));
promise.done(function(comp) {
    var stage = comp.getStage();
	// Set text fields in external composition
	stage.$("title").html("EdgeDocks.com");
	stage.$("body").html("Everything Edge: News, Tutorials, Components and much more...");
	// Listen for events dispatched by the external composition
	stage.$("btn").click(function() {
		sym.play();
	});
});

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.2/js/min/EdgeCommons.js",
	callback: function() {
		EC.centerStage(sym);
		EC.Parallax.setup(sym);
	}
});

If you want to create a horizontal Parallax Scrolling you have to pass "horizontal" as second parameter:

EC.Parallax.setup(sym, "horizontal");


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.2/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.SVG.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)

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");