This tutorial will focus on a couple of basics for using JSFL (defined in the previous tutorial) to alter a Flash document. Everything that can be manipulated in JSFL is considered an object. The Document Object Model (DOM) is basically the hierarchy or structure (model) of objects within a particular document. If you’ve written JavaScript for a web browser, you’re probably somewhat familiar with accessing the DOM of an HTML document.

There’s an order to everything you do within a Flash document, whether you’ve realized before or not. The DOM makes this order explicit. Let’s start by looking at the most basic Stage object in Flash, known as an element. All Stage objects (e.g. bitmaps, groups, graphic symbols, and movieclip symbols) inherit the properties (things that describe the object) and methods (things that can be done to or by the object) of a basic element. The document object hierarchy for any element on Stage is as follows:

Flash > Document > Timeline > Layer > Frame > Element

Each element is on a single frame, that frame is stationed on a single layer, and so on, all the way up to the level of the document, then Flash itself at the very top. So, to access the 1st element, in the 1st frame, on the 1st layer, within the first Timeline (aka Scene), within the 1st open document in Flash, you could use the following JSFL code:

fl.documents[0].timelines[0].layers[0].frames[0].elements[0];

The 0s (i.e. documents[0]) access the first item in an Array (collection of objects). This is known as array notation. Take a look at the documentation for the Document object. It has a number of methods and properties. I frequently return to the documentation when writing new scripts. I recommend downloading the PDF of the entire section for quick reference.

Follow the steps below to utilize two of the Document properties to improve the script from the first tutorial:

1. Create a new Flash Document (AS2 or AS3), using File > New.
2. Create a new Flash JavaScript file (JSFL), using File > New.
3. Add the following code to your JSFL script and click the Run Script button:

var dom = fl.getDocumentDOM();
dom.addNewRectangle({left:0, top:0,right:dom.width, bottom:dom.height}, 0);

Switch back to the new document that you created. You should see a rectangle (with the fill and stroke colors from your Toolbar) that fills the Stage.

Let’s take a closer look at the code that you added to accomplish this. The first line creates a new variable with the name dom. This line also uses the Flash object (fl) to store a reference to the current document. That will save some typing in the next line and keep the script a little bit easier to read.

In the second line, you’ve replaced the top and left positions of the new rectangle to correspond with the x and y coordinates at the top-left corner of the Stage (0, 0). Additionally, you access the width and height properties from the dom variable to match the rectangle’s dimensions with those of the Stage.  This new rectangle is much more useful than the one created previously. For instance, this rectangle could now be used as a background, a mask, or (given a few more steps) to create a matte to hide the edges of the Stage. If you’re interested in learning more about creating mattes and masks with JSFL, check out Chapter 4 of Animation with Scripting.

Note from the structure listed above that you can also use the DOM to alter frames, layers, and timelines. For instance, the following code will create a new layer named artwork:

var dom = fl.getDocumentDOM();
dom.getTimeline().addNewLayer("artwork");

Try experimenting with methods and properties found in the documentation to make changes in Flash documents. I recommend using “test” documents, rather than actual work files, in case something unexpected happens.

A similar object structure exists in JSFL to manipulate Libary items. The next tutorial dives deeper into the Library object.

Also in This Series

• Creating Flash Extensions — Pt. 1: Introduction
• Creating Flash Extensions — Pt. 2: The DOM
• Creating Flash Extensions — Pt. 3: Manipulating the Library
• Creating Flash Extensions — Pt. 4: User Interaction
• Creating Flash Extensions — Pt. 5: SWF Panels
• Creating Flash Extensions — Pt. 6: Custom Tools
• Creating Flash Extensions — Pt. 7: Distributing to Others