swfJavascript for Flash/Flex

I would love to see this in action!

We have created a simple project for you to evaluate. This project consists of a color picker that will enable the user to change the (HTML) background- and/or text color. The color change has a tween effect. Note that the top of the page (the colorpicker) is SWF and the rest is regular HTML.

The tween effect requires some custom written javascript functions (to be called from Flash). The Scriptaculous- and Prototype libraries are also required. 3 Separate javascript files need to be referenced in the HTML document.

The project shows two windows with the exact same content. The window on the left has some external javascript files attached. The window on the right our method is used and no external javascripts are required. We encourage you to download the demo and see for yourself.

SHOW EXAMPLE

Great! So, how does this actually work?

To embed javascript just two simple steps are required which can be performed when a project is ready for 'packaging'. Meaning it can be done at the end of the development cycle when you are confident the javascript - SWF interaction does what it's supposed to.

First step is to generate a 'payload' class from the javascript source file. A payload class is nothing more than a javascript file (or multiple files) embedded into a static actionscript class so it can be compiled into the final SWF file.

Once a payload class has been generated the developer can deliver its javascript contents to the browser with just one statement.

• PAYLOADER APPLICATION
• INJECTOR COMPONENT
• API

Javascript Payloader application

The Javascript Payloader is a desktop application written in Adobe's AIR. It can package javascript into an actionscript class. This actionscript payload can then be used in your actionscript 3 projects (Flash or Flex) in conjunction with the injector component.

Main Features

• Simple drag and drop interface.
• Generates an actionscript payload class from one or multiple javascript source files.
• Maintains the order in which you select multiple javascript files.

Usage

Javascript Payloader is a simple application to use. Select one or more javascript files by dragging and dropping them. Then enter an actionscript class name plus an optional package name. After processing the file(s) the application will ask for a location to save the generated payload class. swfJavascript honors the order in which files are selected so if the used javascript files have any interdependencies, make sure you select them in the correct order. They will be injected in that same order.

Note on compression

Javascript Payloader does not change or modify any javascript it processes. Compression is not achieved by any minification process (not even comments are removed). Therefore it can and probably will be an advantage if javascript files are preprocessed beforehand. Since minification is subject to personal preference, this is an optional step and any preferred javascript minifier can be used. We like YUI Compressor.

Injector component

Once a payload class has been generated from your javascript file(s) the payload can be delivered by adding the component to your project (see installation) and calling the static inject method that the generated payload class contains. At this point the javascript is available for usage as normal.

Usage

With just one statement to inject the javascript payload and deliver its contents to the browser usage couldn't be simpler. Check out the following code examples.

• ACTIONSCRIPT
• MXML

package {
  import myPackage.myPayload;

  public class myClass
  {
    public function myClass()
    {
        myPayload.inject();
    }
  }
}

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
  <mx:Script>
    <![CDATA[
      import mx.events.FlexEvent;
      import myPackage.myPayload;

      private function onCreationComplete(e:FlexEvent):void {
        myPayload.inject();
      }
    ]]>
  </mx:Script>
</mx:Application>

Advanced Usage

Some example code showing the force parameter, using the Injector.call() method and an more elaborate example were we use the External API.

• FORCE
• INJECTOR.CALL
• ADDCALLBACK

/**
 * Whether forcing injection of scripts that already have been injected is useful depends
 * on the contents of the payload 
 */        
package {
  import flash.display.Sprite;
  import myPackage.myPayload;

  public class myClass extends Sprite
  {
    public function myClass()
    {
        myPayload.inject();

        // inject even when previously injected
        myPayload.inject(true);
    }
  }
}

/**
 * Call javascript directly (after injection) with the Injector.call() method.
 * Note that import the Injector class but not External API
 */        
package {
  import flash.display.Sprite;
  import myPackage.myPayload;
  import com.zillizi.Injector;
            
  public class myClass extends Sprite
  {
    public function myClass()
    {
      var injected:Boolean = myPayload.inject();
      if (injected) Injector.call('someMethod', 'any', 'number', 'of', 'arguments')
    }
  }
}
            

/**
 * Example showing usage with callback (calling actionscript from javascript).
 * 
 * This is the javascript contained in the payload
 * 
 * function init() {
 * 	alert('inited');
 * 
 * 	// calls registered function in flash in 1 second
 * 	setTimeout(callFlashInASec, 1000);
 * }
 * 
 * function callFlashInASec() {
 * 	test.callFlash();
 * }
 * 
 * function finallyFromFlash() {
 * 	alert('finally, the last method called from flash.');	
 * }
 * 
 */        
package {
  import com.zillizi.Injector;
  
  import flash.display.Sprite;
  import myPackage.myPayload;
  import flash.external.ExternalInterface;

  public class myClass extends Sprite
  {
    public function myClass():void
    {
      var injected:Boolean = myPayload.inject();
      if (injected) {
        ExternalInterface.addCallback('callFlash', calledFromJavascript);
        ExternalInterface.call('init');
      }
    }
    public function calledFromJavascript():void
    {
      // we call our last method in javascript
      ExternalInterface.call('finallyFromFlash');
    }
  }
}
            

API

The following table describes all the public methods & properties available in the generated payload class as in the Injector class.