I have being doing a lot of Macromedia Flash development in recent months and I love it! The Action Script – core language of this environment – is essentially ECMA script or JavaScript! Many Flash developers that are on the creative side of things will use small bits of Action Script ambedded int o authoring environment (or IDE for those of you who are programmers). Others will mostly use scripting creating and animating objects primarily from Action Script.

The Problem
The problem of version control is quite common. Way too often Action Script code is buried inside Flash authoring environment among megabytes and megabytes of creative content. Since all scripts are inside one large binary FLA file in Macromedia proprietary format any changes to them are quite difficult to version control. Typical version control tools like CVS, SourceSafe, or Perforce do not work for large binary files. It is impossible to use visual diff to review changes from version to version.

How can one version control the action script code embedded into the Flash movies?

The Solution
We have tried to pull all Action Script out of the FLA files into plain text include files. This works, but cripples the experience and productivity of a Flash developer. Just recently I have learned that Macromedia Flash exposes Document Object Model (DOM) which represents the structure of a Flash document in the form of a hierarchical tree {1}. The DOM inspection is the best way to track changes in the Flash movie clips. This article shows how to write your own Flash 7 extensions using JavaScript Flash (JSFL) and how to use these extensions to document actions script code embedded in FLA files.

About oyFashDoc.jsfl Flash extension
The JSFL oyFlashDoc.jsfl file is freely distributed with this article. It provides fully functional Flash extension that creates XML report file from FLA movies. The XML report file contains list of all timelines and all action script code snippets embedded into these timelines. The XML file can now be checked in into your favorite source version control system. You can monitor changes from version to version using visual diff.

Install oyFlashDoc.jsfl file into Flash authoring environment
To add a oyFlashDoc custom action to Flash Command menu place the oyFlashDoc.jsfl file into the following folder:

C:\Documents and Settings\%YOUR_USER_NAME%\Local Settings
    \Application Data\Macromedia\Flash MX 2004\en\Configuration\Commands

Substitute %YOUR_USER_NAME% with the user name you login to Windows with. Restart Macromedia Flash. If you have installed oyFlashDoc.jsfl properly you should now see oyFlashDoc menu item under Commands menu.

Run oyFlashDoc command on your Flash project
Load your favorite project into to Flash authoring environment. Execute oyFlashDoc command. Now open Windows explorer and locate file c:\oyFlashDoc.xml. This is the file with the created report. You can open this file with Internet Explorer or other web browser by double clicking on it. Here is sample XML report file produced by oyFlashDoc JSFL script from /Samples/AdvancedVideo/AdvancedVideo.fla distributed with Flash MX 2004.

How did we do it?
The flash object is globally accessible in the JSFL context. Starting with flash object one can iterate over all timelines, layers, and frames to locate actions script snippets. Note that frames contains elements that can be of several different types, including embedded library symbols and other movie clips. Listing 1 shows code example that iterates most important Flash document DOM objects:

Listing 1. Sample JSFL code that iterates Flash movie.

	var the_doc = flash.getDocumentDOM()
	for(var t = 0; t < the_doc.timelines.length; t++)  {     
		var the_tl = the_doc.timelines[t];
		for(var l=0; l < the_tl.layers.length; l++) {
			var the_layer = the_tl.layers[l];
			for(var f=0; f < the_layer.frames.length; f++) {         
				var the_frame = the_layer.frames[f];				
				trace(the_frame.actionScript);
				...
				...
			}
		}
	} 		

Bugs
Please be aware of the bug in the source code. Current version does not account for ]]> within ActionScript, causing CDATA blocks to prematurely end. Will fix when I have a minute.

References

1. http://www.devx.com/webdev/Article/20822

Your oyFlashDocjsfl command came in very handy for a recent migration of customizations to an upgraded .fla file version. It helped me to pinpoint changes very quickly and saved me a lot of time. :)

I've only added a few lines to allow the user to choose an XML report file location because we don't all have our systems setup to use the c: drive as a default location…

 

function runCommand(){

            // Added to allow user to choose output location of XML report
            var xmlReportURI = flash.browseForFileURL("save","Save XML report to a file or cancel to view in Output panel only.");
            var flashDoc = new oyFlashDoc();
            var xml = flashDoc.generate(flash.getDocumentDOM()); 

            flash.outputPanel.clear(); 
            flash.trace(xml);
            

            // Expanded XML report file saving
            if (xmlReportURI == null){ // user cancelled save file dialog box
                        flash.trace("You have elected to NOT save the XML report to a file.");
            } else {
                        flash.trace("You have elected to save the XML report to: " + xmlReportURI);
                        flash.outputPanel.save(xmlReportURI,false);
            }
}

Thanks again,

Daniela

I found your oyFlashDoc.jsfl script and made a few changes that you or others may be interested in:

* I added tabbed formatting for nested xml elements in the output.

* One major drawback in the original was that movieclips in the library with linkage that are not used on stage would not have their timelines scraped. I added library scraping to the script as well, so some elements are repeated in both <timelines> and <library> nodes but I like to have a record of both. I also added in linkage identifier to library items, so you can see the linkage name for each library asset if it's set. It may be desirable to ONLY scrape timelines of movieclips in the library which have a linkage identifier, in order to avoid redundancy or even scraping code that doesn't compile into the final SWF... but for now I don't mind scraping timelines for every movieclip in the library.

* Another drawback was that AS code that's attached directly to instances wasn't recorded. Personally, I avoid instance-attached AS like the plague, so adding in tracking for that helps me identify and remove attached AS on FLA's that were maybe made by someone other than me ;) In conjunction with this change, I added a more unique id for each checked element that includes the symbol name, instance name, and attached AS.
Now the script scrapes for every non-matching instance of the same asset. That was you get a record of all instance names of the same symbols, and all attached AS code.

* I included the revision from Daniela allowing the user to select a save location, but I changed this slightly as well. The output panel (at least in CS3) has a 9,999 line limit, and I was getting outputs longer than that for (ridiculously) complex FLA's. I changed the output so it saves 9,000 lines at a time to avoid hitting the limit, and it appends the output to the saved file after the first 9,000 lines.

* My changes were significant enough that I felt it was OK to rename a bunch of functions and vars and change a lot of formatting, so it won't diff well with your version ;)

--
Alex Hart