We made a couple decisions up-front, and one of them was to import the latest release code drops from OSMF into an internal git repository; that way if we ever need to make any patches we have the code right there, and anyway as with any open source project it can be very useful to go through the source code to understand how best to use it.  So that decision brought on the next, which was: do we go ahead and setup to build the osmf.swc library ourselves.  After debating this, we decided that it would provide useful experience.  Alas the OSMF SVN lacks a decent build script, seeming to rely on FlashBuilder.  Luckily the Strobe Media Player does have a basic set of ANT build scripts.  Now, I’ve been using ANT for quite some time, and everytime I have to use it on a new project I ask myself: isn’t there anything better?  So far the answer has been “no”.  So, I started working through an attempt to modularize the SMP build script.  I believe I managed to get something that was workable, while being fairly ugly; however along the way I decided that the build for CFP 2.0 should be cleaner if at all possible and decided to go though another search.

Of course one of the obvious tools for any Java developer such as myself has got to be Maven, although up until now I have avoided it, having found it approach too constrictive for my comfort, and that making the transition seems to involve an awful lot of new things to learn, which are not super well documented (not that most other open source tools are really much better).  We also have a (so far) internal tool built using the Eclipse RCP framework, and had also started to look at the e4 projects as the next logical step there; but again, the Eclipse build tooling always has struck me as incredibly non-user friendly.  The big problem we run into is that, because a number of tools that we want access to are part of various plugins (such as XML editing), we end up shipping a whole bunch of the IDE functionality, and that creates a huge set of dependencies to manage.  Now, if you have all day, you can simply re-provision them each time you need to build, downloading the latest stable releases, but that is not going to work for incremental builds.  So we are left with the question of managing a “target platform” full of modules (features and related plugins) that we want to keep up-to-date, and we don’t have a separate build developer.  One of the developments that caught our attention was the Tycho project, which seemed to address some of the issues, and since Tycho is built on top of Maven3 that seemed to provide some added incentive to consider moving to Maven.

Starting out with maven was somewhat ugly, as the maven way of doing things seems to be mostly derived from the process that a Java project might need, but we kept learning.  There is a “flex mojo” to add the ability to call mxmlc and compc from within a maven build as a semi-standard part of their lifecycle; however we quickly ran into a problem.  We need to control the version(s) of flex we are compiling with/against.  Apparently this used to be possibly, however after getting a few too many complaints from users who’d shot themselves in the foot with a path issue, the one guy who maintains the flex mojo basically decided to do his best to make this “impossible” for new users (see his discussion board postings).  In addition to creating technical problems, the attitude also raised a number of questions in our minds about if we really wanted to go that route.  In the end we decided that since the Tycho tool chain was not yet ready for us (or we weren’t ready for it), there was not really a compelling reason to use Maven.  So it was back to the drawing board.

After looking at numerous tools, I finally rediscovered Gradle.  I say rediscover because I’d previously seen it, when it was in a much less mature state.  Anyway, a quick google showed that not only would it be possible, due to Gradle’s built in support for ANT tasks, to use the Adobe mxmlc and compc tasks, but that just recently work had started on a plugin for adding even better support for Flex development into Gradle as a plugin – GradleFx

So, I started working on a test of using gradle to compile the OSMF code and plugins.  At this point, as I’d anticipated, I managed to run into a number of beginner issues; however I have been able to work my way through them, with the kind help of input from the GradleFx developers.  One thing I’ll note here is that you can avoid having to “install” the GradleFx plugin into a local maven cache by simply putting it in a local folder and declaring that as a “flat repo” like:

1
2
3
4
5
6
7
8

buildscript {
     repositories {
        flatDir name: 'localToolsRepository', dirs: "${buildTools}/lib"
    }
    dependencies {
        classpath group: 'org.gradlefx', name: 'gradlefx', version: '0.2.1.ipov', ext: 'jar'
    }
}

Note that the buildscript closure is evaluated right away, before the rest of the build, so if you want to use any variables, such as ${buildTools} in the example above, then you have to define them in a gradle.properties file.

I found that cloning the GradleFx repo enabled me to look over the code and get a better feel for what its doing, as the documentation is still a little light; however I soon found that I had a couple of ideas for some changes to the GradleFx code.  Since this is on GitHub, I decided to try my first ever GitHub hosted fork.  The process seems to have gone well, and so far I’ve been able to contribute a small change in the path handling.  I am currently working on code to add explicit includeSources and includeClasses properties to at least the compc code, as currently the compc implementation is using all the declared source-paths as include-sources too, which is going to work most of the time, but not all.  This should then mean you can reuse .flexLibProperties – something that the SMP build does, but much more simply.  I have the following as a part of a multi-project build (OSMF comes as several different components that I’m building separately):

120
121
122
123
124
125

def flexLibProperties = new XmlParser().parse( project.file('.flexLibProperties') );
def incClasses = [];
flexLibProperties.includeClasses.classEntry.each {
    incClasses.add( it.'@path' );
}
project.tasks.compile.includeClasses = incClasses

I am considering pushing my OSMF repo to GitHub, but my big hang up is that right now I am unsure how much TLC I’m going to be able to give it, and I don’t want to create any false expectations from others.  For instance, if it becomes clear that we’re not going to need to have the ability to build OSMF ourselves, then it would be much simpler to just use the latest binary.  However, in the mean time I intend to try and post a few other tips and try to contribute any other ideas I have to the GradleFx project.

The following scenarios illustrate situations where video-embedded documents might be handy and you can review the options in a lot more detail in this extended whitepaper.

• Large company IT departments are pushing employees to store their business documents in secure document management systems like SharePoint or Lotus Notes. These systems enforce enhanced security and offer document control safeguards that are difficult to replicate on standard web servers. Documents with embedded video coexist very nicely with these systems.
• For security reasons, the same IT departments may resist the proliferation of intranet or extranet web server applications. Even if a document could be hosted on a web server, policy restrictions or resource costs may make that difficult for people in business units and non-IT departments. Those individuals can author video-enhanced PDF or DOC files without requiring any special IT support.
• Although this problem is diminishing, companies with highly mobile workforces may still have people operating in places where web connectivity is marginal or nonexistent. Field service crews, overseas offices in developing economies and personnel co-located behind strict client firewalls may not be able to reach key company websites. They can carry a library of video-enabled documents on a hard disk, thumb drive, or CD.
• Most employees in large organizations use Microsoft Word and it would be convenient if all forms of publishing could be done with that tool. However, to work with other programs, Word documents often must be exported to another format. If you add video into the mix, that gets very complicated. One iPOV client found that, by converting Word originals to PDFs and embedding video, the resulting documents became much more universal. A given PDF document with embedded video can be stored in SharePoint, loaded into the Learning Management System, linked and made viewable online at a website, or emailed to parties outside the company.  One file, many uses.
• A similar situation occurred in a global multinational. Divisions around the world each had their own Learning Management System, some of which were old and not standards-compliant. If they published eLearning in the customary SCORM or AICC packaging it would have taken a lot of effort to import it into all of the varied, regional servers. However, every LMS (even the old and non-standard ones) could import and display a PDF. By packaging the video inside the PDF, the courseware effectively became a universal commodity.

Examples

(click on the images and captions to view PDFs with embedded video at iPOV’s website)

You can view more examples at iPOV’s website: http://www.ipov.net/content/rich-media-pdf

Gotchas

A fast-moving technology always generates surprises that initially baffle newcomers. These are the surprising limitations and gotchas that dictate what is actually possible. Accordingly, we begin this guide with a list of the key constraints that we have learned to work around:

1. Can I put a video into a Word Document and have it viewable and playable on the Page?
   No. You can create that impression if you insert a Windows Media ‘object’ into your document, but the video won’t actually be inside the Word file. It will be an external file that the document is linked to, and you must manage this linkage yourself. You can put a movie inside the Word file, but it will appear as a small icon that you must click to open. It is theoretically possible that a skilled programmer can write a macro or plugin to make this possible, but iPOV has not seen any developer activity in this area.
2. Can I put a video into a Word document and then save it as a PDF?
   Not reliably or well. iPOV is not aware of any tool that will reliably export a video-embedded Word document to PDF and have the video play correctly. First, if the video is in a typical, common movie format (MP4, AVI, WMV, MOV, etc.), it should first be converted into a Flash movie – something PDF exporting software won’t do.[1] Second, if the movie embedded in the Word document is already a Flash movie, the resulting embedded movie will have very limited play control (see point #3).
3. Can I add a Flash video to a PDF using Acrobat Pro?
   You can add a FLV or H.264 video or SWF animation easily enough, but the Flash Player doesn’t supply any play controls (start, stop, pause, tracker bar, volume, etc.). This is a big drawback in business situations where the viewer may want to review a key point or adjust the sound volume. To get good play controls, it is necessary to package the video and play controls together into an SWF file (e.g., using an external editor such as Adobe Flash) and insert the unified SWF file into the PDF.[2]
4. Why haven’t I seen more PDFs with embedded video – it looks really cool?
   Acrobat has supported embedding videos since version 6. The problem for business documents comes down to workflow – see answer #2 above.  In general if you want to edit the text of a document you will do so in Word and then re-publish it to a PDF.  At this point someone must individually re-insert all the videos from the old PDF into the new PDF. iPOV has developed a set of processes and procedures to help us do this quickly and correctly and we are working on tools to automate the process even more.[3]^{,    [4]}
5. Why not put the videos on YouTube and link them to a document?
   YouTube (and most sites like it) caters to people who want wide public distribution for their files. It has a very basic security system and it may be often blocked by corporate firewalls. Sites like these also tend to display ads that may or may not fit with your corporate image.

[2] The latest version of Acrobat Pro has an alternative way to import linked files, but it is finicky and prone to error. It is also more difficult to debug any broken links once the files have been imported.

[3] When documents are designed for large numbers of end users, it is often easier link to a video on a web server rather than distribute a packaged document.

[4] Note also that recent security changes have made some old documents no longer playable.

• You want to do Flash work that is mostly development oriented. The environment described here will be useful for a programmer or small team using supplements from a designer as opposed to a designer working in the Flash IDE with supplements from a programmer.
• You want a command line interface and a tool chain that can work easily with existing continuous integration and web deployment tools.

The following steps will take you through the required set up for a sample project. There is a link to the full source at the end.

Step 1: Download the Flex SDK

Adobe’s open source Flex SDK provides, among other things, an Actionscript compiler binary: mxmlc. It’s not just useful for compiling mxml based Flex applications however; it can also be used to compile lightweight, pure Actionscript 3 projects. The download will consist of a single zip file which you may extract to a directory of your choice. On windows, I choose c:\flex, and on linux I choose /usr/local/share/adobe-flex/sdk. You’ll just need to remember the path when you set up your build environment. Note that for the compiler to work, you’ll need to have Java 1.6+ installed.

Step 2: Download the Flash debugger standalone player and plugins

Ok, so this part isn’t open source, but you can’t have Flash these days without Adobe’s Flash player. The debug flash player will conveniently display a stack trace whenever there’s an error. The trace will even include line numbers if you build your swfs with the debug flag, which you will see how to do below. The debug enabled browser plugins are installed in the same manner as the normal browser plugins. If you’re running Windows, installing the ActiveX control will result in having a debug enabled player in IE. On both Linux and Windows, installing the ‘Plugin content debugger’ will give you a debug enabled player in browsers like Firefox and Chrome. The standalone player can be placed anywhere. On Linux I’ve copied the flashplayer executable to /usr/local/bin, which is on my PATH.

Step 3: Install Ant and the Flex SDK Ant tasks

Since the Flex SDK internals are predominately written in Java, Ant is used as the build tool of choice for most Flex and Actionscript 3 projects. Accordingly, Adobe provides a set of Ant tasks for invoking various SDK related commands from within Ant. First install Ant (if you’re on a Linux system, you’re better off using your distribution’s package manager rather than Apache’s packages). Copy the file flexTasks.jar from <flex sdk path>/ant/lib to your Ant installation’s lib folder. On my Ubuntu Jaunty system for example, it was /usr/share/ant/lib. You will also copy from the flex Ant folder the file flexTasks.tasks to your project folder once it is created.

Step 4: Choosing an editor/IDE

Now that you can compile Actionscript files and view the results, you’ll need to select an Actionscript aware editor or IDE. If you are using Vim, there are a number of syntax files around the web. I’ve had luck with the ones found on Adbul Qabiz’s blog for example. On Emacs, you will find what you need on the Emacs Wiki, including some FlyMake code (build as you type). If you are running Windows, there is a tailored open source solution available: FlashDevelop. FlashDevelop provides IDE functionality for Actionscript 2 and 3, Flex, Air, and haXe. If you’re accustomed to Eclipse, Visual Studio, NetBeans, etc., you should feel right at home with FlashDevelop.

Step 5: Creating a project template

The main aim here is to build your project by issuing one command from the command line. You’ll start by creating a project folder, and inside the project folder you will create a file called build.xml for use with Ant. If you intend to collaborate with others on the project, it’s also a good idea to separate system specific variables into another file. At iPOV, we use a separate file called build-user.properties. Here are samples of both files:

<project name="miniplayer" default="build-all" basedir=".">
    <description>
           Builds iPOV Hello World
        To use, :
          1. Copy %flex_sdk_3%/ant/lib/flexTasks.jar  to %ANT_HOME%/lib
          2. Copy build-user.properties.default to build-user.properties
            (so it doesn't get commited to SVN) and
            edit the paths for your install.
          3. Invoke the build ">ant [build-target-name]" (either via commandline of GUI launcher)
    </description>

    <!-- Import the property definitions. -->
    <property file="build-user.properties" />
    <property name="PROJECT_NAME" value="ipov_hello-world"/>
    <property name="PROJECT_VERSION" value="1.0.0"/>
    <property name="DEPLOY_DIR" value="bin"/>
    <property name="MAIN_CLASS" value="src/net/ipov/hello_world/Main.as"/>

    <taskdef resource="flexTasks.tasks" classpath="${TASK_HOME}/flexTasks.jar" />

    <target name="build-all" depends="build-swf,build-debug-swf"/>

    <target name="build-swf" depends="init">
        <mxmlc file="${MAIN_CLASS}"
            output="${DEPLOY_DIR}/${PROJECT_NAME}-${PROJECT_VERSION}.swf"
            debug="false" optimize="true" fork="true"
            default-background-color="0xffffff" >
            <source-path path-element="src/" />
        </mxmlc>
    </target>

    <target name="build-debug-swf" depends="init">
        <mxmlc file="${MAIN_CLASS}"
            output="${DEPLOY_DIR}/${PROJECT_NAME}-${PROJECT_VERSION}.swf"
            debug="true" optimize="false" fork="true"
            default-background-color="0xffffff" >
            <source-path path-element="src/" />
        </mxmlc>
    </target>

    <target name="init">
        <mkdir dir="${DEPLOY_DIR}"/>
    </target>

</project> 

#
# Copy this file to .user.properties and then edit it to match your system
#
FLEX_HOME=c:/flex3/sdk
TASK_HOME=c:/bin/apache-ant-1.7.1/lib

Replace ipov_hello-world above with your project name, and replace the net/ipov path with the namespace you will use for your main source files.

If you are using FlashDevelop, you will now create a new AS3 project using Project -> New Project. For Location, browse to your project folder where you have placed the two files above. For Package, type your primary namespace (net.ipov.hello_world in this example). FlashDevelop will create the necessary files and folders for you. Outside of FlashDevelop, you can simply create a folder called src, and inside place folders corresponding to your primary namespace. Then create a file called Main.as inside your primary namespace folder to act as the entry point for your application. Here the content of Main.as in the Hello, World! sample:

package net.ipov.hello_world
{
    import flash.display.Sprite;
    import flash.events.Event;
    import flash.text.TextField;

    [SWF(height='300', width='400')]
    public class Main extends Sprite {

        private var _params:Object;

        public function Main():void {
            _params = root.loaderInfo.parameters ? root.loaderInfo.parameters : new Object();

            if (stage) init();
            else addEventListener(Event.ADDED_TO_STAGE, init);

        }

        private function init(e:Event = null):void {
            removeEventListener(Event.ADDED_TO_STAGE, init);
            // entry point
            var helloText:TextField = new TextField();
            helloText.text = "Hello, World!";
            stage.addChild(helloText);
        }

    }

}

Once you have set up your project folder, invoke the following commands from the root of the project to build and launch the application:

~/projects/as3-hello-world $ ant
Buildfile: build.xml

init:

build-swf:
    [mxmlc] Loading configuration file /usr/local/share/adobe-flex/sdk/frameworks/flex-config.xml
    [mxmlc] /home/joseph/projects/as3-hello-world/build/ipov_hello-world-1.0.0.swf (833 bytes)

build-debug-swf:
    [mxmlc] Loading configuration file /usr/local/share/adobe-flex/sdk/frameworks/flex-config.xml
    [mxmlc] /home/joseph/projects/as3-hello-world/build/ipov_hello-world-1.0.0.swf (1021 bytes)

build-all:

BUILD SUCCESSFUL
Total time: 9 seconds
~/projects/as3-hello-world $ flashplayer build/ipov_hello-world-1.0.0.swf

If you are using FlashDevelop, you can also use Project -> Test Movie (F5 on the keyboard). When prompted to configure the compiler, set your Flex SDK location under AS3Context, and set the standalone Flash player location under FlashViewer.

That should be enough to get started developing AS3 applications. Future articles will include information about unit testing, continuous integration, deployment, and Adobe Captivate Widget development.

as3-hello-world-source