The Dojo Toolkit and Deft August 3rd, 2008 at 12:09 am by Mike Wilcox
A new top-level package was recently added to the Dojo Toolkit called Deft — an acronym for Dojo Experimental Flex Technology. The Deft package was created and is maintained by SitePen’s Tom Trenka, taking advantage of Adobe’s new MPL licensing, and the corresponding APIs of the Flash Player. Most articles focus on Adobe’s Flex Builder, which isn’t open source or free. The majority of articles about Flex and the Flex Builder also put an emphasis on components developed using a combination of ActionScript and XML-based description files, known as MXML.
Instead of taking this approach, Deft focuses on ActionScript components created in support of the various projects within the Dojo Toolkit (mostly for DojoX). Deft source files are well organized based in part on the organization of other Dojo Toolkit projects, as well as the package structure required by the Flex compiler. Most Flex applications are based on the Flex AS3 Application class, which forces you to write at least one “controlling” MXML file in order compile your code. Instead of this, Deft components inherit primarily from the Sprite class — which allows you to write pure ActionScript code.
Compiling components within Deft
To compile code within Deft, we use the command line Flex compiler called “mxmlc” — which is available with the Flex Open Source SDK. You can use this command to compile both full Flex applications (i.e. with an MXML definition file) and Deft components.
First, grab the latest Dojo nightly build that contains Deft, or download it with Subversion.
Then download the Flex SDK. I recommend placing it in an easily accessible location, as we’ll be using some absolute paths. It doesn’t require installation, so it’s ready to go after it’s unpackaged.
Hello World
Now let’s start with some very minimalist AS3 code that we can compile:
package { public class HelloWorld { public function HelloWorld():void { } } }
This will be a top-level package (on the same level that our compiler will be) so we just use “package” without giving it a name (more about packages later). The next line is our class declaration, which is the same name as our file. And next is our constructor.
Of course, this will compile, but would be quite useless. Here’s a little bit of code that will add display capabilities, and add a text field to the stage:
package { import flash.display.*; import flash.text.*; public class HelloWorld extends Sprite { public function HelloWorld():void { dbgText(); } private function dbgText():void{ var myText:TextField = new TextField(); myText.text = "Hello World"; myText.background = true; this.addChild(myText); } } }
This will give you a basic text display object on the Stage. If you’re used to AS2, some of the new concepts can be tricky. In AS3, there’s no _root or _level0, and not a very obvious way to attach display items. Here we are importing the flash.display package, which includes the Sprite class that we’re extending. The Sprite class can be thought of as a stripped down version of MovieClip. Since a Sprite is a child of the Stage, it contains methods for adding display elements - in this case, our TextField, which gets added with addChild().
Now let’s open Terminal and compile the code. I’m going to be using Unix conventions here, but for Windows users, it’s not much different. The basic parameters for our compiler are: mxmlc, file-input, file-output.
Now it Gets Tricky
NOTE: The path to my dojotoolkit directory is /Users/mike/Sites/Tests/. I’m going to represent this path with a tilde (~) to help make things clear. But I recommend use all absolute paths initially.
Package names, the directory structure, and the current “location” of compiler must all be in sync, or you’ll get the inevitable error:
Error: A file found in a source-path must have the same package structure '(folder name)', as the definition's package, '(package name)'.
Our HelloWorld.as file is going here:
~/deft/trunk/deft/HelloWorld.as…and we will navigate our command line to the same location. Compiling from here should work. But in my case I got the dreaded error shown above. I fixed it by adding another parameter to the command:
-source-path= ~ /deft/trunk/deftThis clearly defines the root of the package. Finally we define the output file, which will also be in the same location:
-output= ~ /deft/trunk/deft/HelloWorld.swfThe following is my Terminal command for compiling. If you add the mxmlc to your system path, you can use mxmlc instead of the entire path. NOTE: This is formatted for readability. I used line breaks instead of spaces for clarity.
mike$ /Users/mike/Documents/FlexDocs/flex_sdk_3/bin/mxmlc -source-path= ~ /deft/trunk/ HelloWorld.as -output= ~ /deft/trunk/HelloWorld.swf
If successful, the last line will print HelloWorld.swf. If that’s not there, you’ll be shown an error. The most common error at this stage of setup is about the path conforming to the class name - but other common errors involve naming conventions and incorrect syntax.
Shell Script
That was a heck of a command to be typing. The simplest thing to do is put this in a shell script. This way, more complicated scripts can be written, but more importantly, this long command can be saved to disk. Here are the steps for anyone not familiar with shell scripts:
- Copy and paste the previous command into a text file.
- Save the text file in the same path location as the HelloWorld.as file, and name it HelloWorld.sh (in Windows it would be .BAT). Make sure it was saved with that extension, and not something like “HelloWorld.sh.txt”.
- You may have to change the permissions to make it executable. Go back to your Terminal (if it’s still open, we should still be in the right directory) and enter: chmod 777 HelloWorld.sh
Shell scripts are protected from external attacks by requiring you to use a period slash before your script name. So to execute the script, type:
./HelloWorld.shNow it’s easier to maintain that long command. You can of course add more options to it, or loop through and compile several files, or any other shell script wizardry you can dream up.
Hello Real World Example
Now let’s look at one of the latest projects in Deft, the Uploader. The fully qualified class name is deft.form.Uploader. Uploaderis the class name, and deft.form is the package to which it belongs. It’s very similar to Dojo’s package system - the compiler reads the import of a deft.form file, and expects to look in a deft folder, and then a form folder. In our HelloWorld example, there was no package name - so the compiler expected to find the file in the same folder where it resided.
deft.form.Uploader is the main file and imports two other custom files, deft.form.UploadList and deft.common.debugging.Tracer. Tracer is a multi-output debugging tool, which can parse and log objects and messages to the Output panel in the Flash IDE, the Flash Player Debugger, and/or the Firebug console.
You’ll find that the shell script, “uploader.sh” is located in the trunk, the same level as the deft directory. You’ll see how the source-path option points to the location of the shell script, and the path to Uploader.as is continued from there. Finally, the output points to a location where the SWF will be used in dojox.form, in the resources folder.
You won’t have to go through this build process to use dojox.form.FileInputFlash. All you have to do is get the latest Dojo nightly build or wait for the 1.2 release, and the SWF will be in the resources/ folder. The Deft files are there in the event that a developer needs to make custom modifications for a project, or permanent modifications, and optionally contribute them back to Dojo.
Those are the basics for SWF compilation. The Deft project is still in its infancy, but there are currently a few goodies in it including the multi-image uploader, pre-alpha quality support for dojox.gfx. Future plans include support for audio and video. Hopefully Adobe will continue its current path towards being open source friendly, helping Deft flourish.
Posted August 3rd, 2008 at 12:17 pm
I think this is an awesome addition! Great job you guys, it is great to see someone taking advantage of the new adobe open source efforts.
Posted August 3rd, 2008 at 2:48 pm
Mike,
Deft seems like an interesting project
But, I don’t think there’s anything Flex about it .. it doesn’t seem to use the Flex framework at all (unless I got it wrong) .. it does use flex’s compiler to compile but that doesn’t make it Flex in my opinion .. any AS3 code can be compiled using mxmlc.
Right now to me Deft seems like a lightweight (fairly immature) alternative for Flex that I may use if I don’t need all the goodies flex gives me.
Mrinal
Posted August 4th, 2008 at 4:38 am
[…] Trenka of SitePen has created a new top-level Dojo package called Deft which “focuses on ActionScript components created in support of the various projects within […]
Posted August 4th, 2008 at 5:41 am
mike, i have to agree with mrinal - i don’t see the “Flex” in your example. but maybe i also didn’t get it?
gerold
Posted August 4th, 2008 at 8:00 am
@Mrinal and gerold–
It uses the Flex compilers and for right now, mostly the Flash Player APIs. Does this make it just Flash or Flex? Considering that it requires the Flex compilers, I think I’d argue (as Mike stated at the beginning of the post) that it is Flex, regardless of whether or not we are using this (at the moment) to develop Flash-based user interfaces.
But unfortunately I think that’s what most people think of when they think of Flex. We’re trying to show you something a little different, that using the Flex OSS SDK does not necessarily mean using it to develop user interfaces–instead, we’re using it to deal with things that it can do that browsers can’t, such as decent vector graphics support in IE, audio, video, multi-file uploaders, and any other things you can think of.
Most people tend to think of this as “one or the other”. I prefer to think of it as “let the two work together”.
Posted August 4th, 2008 at 12:38 pm
Tom,
I absolutely love the thought “let the two work together”
Although, I do disagree that Deft is Flex since all it uses is the Flex compilers ability to compile AS3 to a SWF … if we assume that to be Flex then are all the other projects that use the same .. are they Flex? … for example is Papervision3d Flex? No it isn’t.
Mrinal
Posted August 4th, 2008 at 2:15 pm
Mrinal,
It’s a grey area. The reason I do consider it to be Flex is because the code we are releasing is designed to be incorporated/compiled using the Flex SDK and not Flash CS3 or with the Flex Builder. Plus, it’s only under Flex can we release this code as pure Open Source in a way that does not require you to buy any proprietary programs.
I do see what you are saying though. I think it’s really a matter of whether or not you consider Flex to be the actual framework you use to build UIs, or if you consider it to be the entire package. I’m guessing you see it as the former, whereas we see it as the latter.
In the end though, it just comes down to leveraging the Adobe APIs in a very Open Web-friendly way.
Posted August 4th, 2008 at 5:52 pm
I don’t think there’s any confusion at all that Flex is a framework (from Adobe: “Flex is a highly productive, free open source framework for building and maintaining expressive web applications that deploy consistently on all major browsers, desktops, and operating systems”) and that you’ve just taken the compiler that has been provided as part of the SDK that supports that framework and used it as a pure AS3 compiler.
Flex != AS3.
If, for example, I had a Spring SDK that came pre-packaged with the JDK and I used the compiler from that to compile my Java code without reference to any Spring classes, would I be using Spring? No.
More to the point, why can’t your code be incorporated into a Flash CS3 project if it inherets from Sprite?
Posted August 4th, 2008 at 6:55 pm
@Darren - I don’t follow your question about the Sprite inheritance. What I was saying in the blog was that we can’t use Flex components, nor inherit from the Application class at the “root” level, if we want to compile AS3 code without the MXML. We instead inherit from Sprite (or MovieClip).
It works in the Flash IDE if you assign the main class to the Document class in the Properties Panel. That’s why I have the Tracer class - it outputs to Firebug and the Flash Output panel. Sometimes I jump into the IDE to track down runtime errors.
About Flex!=AS3:
*sigh*, ok, I’ll jump in…
If you were using a Spring compiler, it would be just that. It wouldn’t necessarilly mean you were creating a Spring application - but you *could*. I was pretty clear that we are creating SWF components to use in DojoX. That said, we’re not creating Flex applications… but we *could* :)
The confusion seems to really comes down the acronym, which I actually thought up at blog time. I couldn’t name it after the compiler, because “DEMXMLCT” doesn’t make any sense.
And I couldn’t think of anything else involving Flash that started with an ‘F’ ;)
Posted August 4th, 2008 at 8:04 pm
I can’t figure out how much of Dojo I need to download. Should I grab the whole tarball and have it somewhere? I’ve done just a few things in Dojo before and they mostly just needed core, which I grabbed off the AOL cdn.
Posted August 5th, 2008 at 5:16 am
The easiest way is to download the Dojo Nightly and use the whole thing:
http://archive.dojotoolkit.org/nightly/
Posted August 5th, 2008 at 9:10 am
This is great - nice to see Flash / Flex (whatever!) being used within an Ajax project.
One problem - the link to the Flex SDK has a space at the front of it, which makes the link invalid.
For those of you trying to download the Flex SDK, go to:
http://www.adobe.com/products/flex/flexdownloads/index.html
Mike
Mike Potter
Adobe Developer Marketing
Posted August 5th, 2008 at 11:21 am
@Darren:
“Flex != AS3.
If, for example, I had a Spring SDK that came pre-packaged with the JDK and I used the compiler from that to compile my Java code without reference to any Spring classes, would I be using Spring? No.
More to the point, why can’t your code be incorporated into a Flash CS3 project if it inherets from Sprite?”
You *can*. We’re not limiting ourselves to any one particular option, and we are trying to design things so that if you wanted to use them for a pure Flex or Flash project, you can.
There are some licensing issues with some of the Flex components that we have yet to address. That doesn’t mean we won’t use anything from the Flex component set in the future. It means we’re not using it at the moment.
Jeez, the semantic hair-splitting is killing me here (;))…and it’s precisely one of the reasons why we started this project. “Working together” means having the ability to use/consume anything provided with Flex we feel makes good sense; right now, most of that effort is focused on pure AS3 but we are definitely reserving the right to use Flex components in the future.
Posted August 6th, 2008 at 5:52 am
The example above is a AS3 based SWF,but a compiled Flex app resolves to a SWF, but uses amongst other things the mx classes in the flex package libraries.
It is probably better form to only include the Classes you need rather than do a wildcard import of the whole package thus:
import flash.display.Sprite;
import flash.text.TextField;
This will keep the compiled SWF smaller.
Most of the Flex framework classes live in the mx namespace
depending on what you want to do the flex framework contains some real heavyweight elements
I am a Flex Dev who is just getting into Dojo so its nice to see the cross polonation of ideas, keep up the good work!
Posted August 6th, 2008 at 6:17 am
What I meant to say is I am not sure how smart the MXML or the Flash compiler is about partial compilation of Classes from Packages.
We were always taught that use of a wildcard was not good form whan you only need a single class.
Am I right in thinking that Dojo compiles only what it needs since the architecture was designed that way?
Also half the guys I work with are paranoid about keeping SWF size down to an absolute minimum.
The whole framework can easily top 500K, there is a technique which works with the latest Flash Player 9.0.115 known as persistant framework caching which can be used to keep file size down
see
http://livedocs.adobe.com/flex/3/html/help.html?content=Part2_DevApps_1.html
the section explains how to compile for signed RSL’s which is something you might find useful.
Posted August 6th, 2008 at 8:32 am
@Stephen:
You’re absolutely correct. It probably should have been used in the blog the way you wrote as a best practice.
I generally import packages wholesale as shown, and then after I get things working, I “back them out” to include only what’s necessary. This technique can be especially helpful with the event package.
Posted August 8th, 2008 at 5:03 pm
Please help with compc compile…. I have following code in my build.xml file.. it’s able to echo all the as classes and mxml files, but it also got this error “Error: could not find source for class src.classes:ArrowSeperatorSkin” (please see below)
swc:
[mkdir] Skipping C:\Documents and Settings\csun\workspace\NaviscentProject\swc because it alread
y exists.
[pathconvert] Set property flex.classes = src.classes.ArrowSeperatorSkin src.classes.CustomCell1 src
.classes.CustomData src.classes.DefNameThumbClass src.classes.NameThumbClass src.classes.NumThumbCla
ss src.classes.TriangleControl src.component.AddNewSiteForm src.component.ButtonSliderSkin src.compo
nent.ButtonTest src.component.CheckboxSiteItemRenderer src.component.DefinitionSliderBar src.compone
nt.EvaluateSlideBar src.component.Login src.component.NewUserForm src.component.NumSliderBar src.com
ponent.Survey1 src.component.Survey2 src.component.Survey3 src.component.Survey4 src.component.Surve
y5 src.component.SurveyPage src.component.UserAccount src.main
[echo] ********* ActionScript classes: [src.classes.ArrowSeperatorSkin src.classes.CustomCell1
src.classes.CustomData src.classes.DefNameThumbClass src.classes.NameThumbClass src.classes.NumThumb
Class src.classes.TriangleControl src.component.AddNewSiteForm src.component.ButtonSliderSkin src.co
mponent.ButtonTest src.component.CheckboxSiteItemRenderer src.component.DefinitionSliderBar src.comp
onent.EvaluateSlideBar src.component.Login src.component.NewUserForm src.component.NumSliderBar src.
component.Survey1 src.component.Survey2 src.component.Survey3 src.component.Survey4 src.component.Su
rvey5 src.component.SurveyPage src.component.UserAccount src.main] ***********
[compc] Loading configuration file C:\Program Files\Adobe\Flex Builder 3 Plug-in\sdks\3.0.0\fram
eworks\flex-config.xml
[compc] Error: could not find source for class src.classes:ArrowSeperatorSkin.
[compc]
–> build file as follow..
********* ActionScript classes: [${flex.classes}] ***********