Subversion & Eclipse – Branching a linked resource inside a Subversion-managed Eclipse project
We use Subversion to manage all our Flash projects. We also have a separate project for our class libraries, and we usually add this project (or a subdirectory of it) as a linked resource to our Flash projects. For most projects this is a great way to share and maintain the class library.
A combination of factors has recently made this less workable than we’d like. A new coder (based on the other side of the country in Perth, WA) has created the need to branch our class library. When all the developers sit in the same room it’s much easier to be lazy and manage the refactoring process in an ad-hoc fashion, but distance means extra discipline is required.
Branching the code library is easy, just follow the Subclipse/Tortoise/Subversion documentation. To integrate the branch in the (separate) Flash project repo I created a new ‘src_branch’ folder and checked out the branch I wanted from our class library.
So now we have one checked-out repo (the class library) inside another different checked-out repo (the Flash project). Updates and commits work like this:
- The class library repo updates and commits normally (right-click, choose Team/Commit), but has the Subversion ‘question mark’ icon because the Flash Project repo doesn’t know about it.
- The Project repo will update normally, but we can’t commit the project files by choosing the root directory and committing (Subversion gives an error and says we need to update first, even when we have the latest revision). Instead we need to CTRL-click to select the items inside the Project folder (except for the class library repo) and then we commit those items.
It’s a little convoluted at first, but is working well and preventing the breakages that were becoming too common. It also means we’re free to build major updates and replacements to our architecture, something that’s really only become possible with the additional developer.
Enterprise Architect for Actionscript
Good habits – http://imanit.com/blog/?p=43
How To – Create a class model from an AS project – http://fasanya.blogspot.com/2010/04/using-enterprise-architect-to-create.html
How To – Configuring EA, creating a diagram, generating stub code – http://dgrigg.com/blog/2006/09/14/uml-stub-code-and-asdocs/
Alternatives to Enterprise Architect for Actionscript:
UML4AS – http://www.uml4as.com/flower-platform/home-uml4as.html
ArgoUML – http://argouml.tigris.org/tours/
StarUML – http://www.senocular.com/flash/tutorials/starumltoas3/
CrocusUML – http://crocusmodeller.com/
http://crocusmodeller.com/
Automatic Actionscript API documentation – JavaDoc comments, ANT, NaturalDocs
I needed a JavaDoc documentation solution for our ActionScript 3 API. We’ll soon be engaging offshore contractors to build content using our in-house AS3 framework and up-to-the-minute documentation is a must-have.
Our development environment is Eclipse, FDT, ANT, Windows, and the solution needs to be as automatic as possible.
Previously I’d used DoxyGen but after some quick Googling I found a tool – NaturalDocs - with specific ActionScript support.
Generating NaturalDocs as part of an ANT build in Eclipse requires:
- Python to be installed on your computer
- the NaturalDocs installation
- an ANT script (here’s my example)
I do minimal command-line work, and less Python, but the process worked almost immediately for me. If you run into problems check the troubleshooting page on the NaturalDocs site.
<property file=”../../_properties/workspace.properties”/>
<property file=”../../_properties/app.properties”/>
<target name=”naturaldocs”>
<!– naturaldocs generates HTML documentation from AS3 JavaDoc comments –>
<echo>${project.name} Building HTML documentation</echo>
<property name=”perl.path” value=”perl”/>
<property name=”nd.path” value=”C:\NaturalDocs-1.51\NaturalDocs”/>
<property name=”nd.format” value= “FramedHTML” />
<property name=”nd.doc_dir” value= “${src.dir}/documentation” />
<property name=”nd.code_dir” value= “${src.dir}” />
<property name=”library.gaia.dir” value=”C:\_workspace/CLASS_LIBRARY_AS3/as3_lib_catalyst/src/com/gaia” />
<property name=”nd.work_dir” value= “${src.dir}/documentation/project” />
<property name=”exepath” value=”${nd.path}NaturalDocs -i ${src.dir} -o FramedHTML ${nd.doc_dir} -p ${nd.work_dir}”/>
<!– The ‘exepath’ below can be copied and pasted for command-line testing outsied Eclipse –>
<echo>${exepath}</echo>
<mkdir dir=”${nd.doc_dir}”/>
<mkdir dir=”${nd.work_dir}”/>
<echo>Producing NaturalDocs documentation files now (this may take a few minutes)…</echo>
<exec executable=”${perl.path}”>
<arg line=”${nd.path}”/>
<arg line=”-o ${nd.format} ${nd.doc_dir}”/>
<arg line=”-i ${nd.code_dir}”/>
<arg line=”-i ${library.gaia.dir}”/>
<arg line=”-p ${nd.work_dir}”/>
</exec>
<echo>NaturalDocs production complete.</echo>
<delete dir=”${nd.work_dir}”></delete>
<echo>NaturalDocs cleanup complete.</echo>
</target>
</project>
Flash debugging and diagnostic tools
Over the years I’ve tried a lot of different Flash debugging and testing tools. Whether I’m on my development workstation or at a client site I keep a stash of installers for these handy at all times.
Here’s a list of the ones worth keeping – there’s no problem that these tools can’t discover. And (with the exception of Charles) they’re all FREE!
- Charles HTTP proxy – see exactly what’s being requested and returned (great for revealing server errors)
- Firefox – Allows me to run the Flash Switcher and Flash Tracer plugins
- Flash Switcher – easily test in multiple versions of the Flash Player
- Flashtracer – View the log output of the Debug Player, includes pattern matching and text colouring
- A text document with an example of a valid path to flashlog.txt (to make up for having a bad memory!)
- Installers for Debug Flash Player 9 and 10, ActiveX/plugin/standalone
- A copy of my own ‘mm.cfg’ file (to copy onto a client machine if required)
Assuming that I need to visit a client site to test an issue (a rare occurence, but that makes it even more important that I get in, do the business and get out as quickly and reliably as possible!) I can start with a ‘virgin’ machine and have it loaded with my test suite in under 20 minutes.
Additionally, when I’m testing and debugging on my development machine, I always install:
- dnGREP – Easy, fast, multi-line search and replace
- Launchy – Indispensible shortcut tool
- WAMPServer – Reliable testing of local content in a webserver environment
Other useful compilations of Flash and Flex debugging and diagnostic tools are:
the list of helpful Flex or Flash debug tools
*drawlogic’s Helpful Flash Debugging Tools
John Lindquist’s Non-coding development tools
What about you? Are there any tools you can’t live without?
Better memory management in AS3 with Temple Library
After seeing some memory issues with a large Gaia Flash Framework project I was directed to the Temple Memory Management library.
By extending the Gaia AbstractPage from the Temple ‘CoreMovielip’ class instead of the Flash MovieClip class I gained a bunch of useful cleanup functions that operate pretty much on ‘auto pilot’ and instantly reduced my memory overhead with no additional work.
In addition to memory management there are a bunch of other useful ‘toolkit’ classes. Like the Gaia framework, this is a well-thought-out structure that you can use as much (or as little) as you like. Just the memory management alone makes it worthwhile, the rest is up to you.
Defining interactivity
Quantifying the complexity and quantity of interactions in a project can be difficult. Finding a single point of reference that clients and developers can use for a shared understanding of how many interactions should be developed, and what exactly those interactions are is critical to matching expectations with results.
eLearning projects encounter this issue repeatedly. My employer makes use of something called the ‘MIL’ spec for levels of learning interactivity. This document expresses the specification in plain English (the levels are specified on pp45), but here are some more detailed concrete examples.
Level 1 Interactivity – Passive
This is the lowest (baseline) level of interactive courseware development. It is normally a knowledge or familiarisation lesson, provided in a linear format (one idea after another). Level 1 is primarily used for introducing an idea or concept. The user has little or no control over the sequence and timed events of the lesson material. Minimal interactivity is often provided by selective screen icons and inserted into the lesson through the sparing use basic explore interactions. This level may include simple developed graphics and/or clip art, customer provided video and audio clips.
Usage
Baseline interactivity (lowest level)
Occasional interactivity using recognised icons
Linear knowledge development
Minimal user control
Substitute PowerPoint
No (minimal) production resources required
Low maintenance requirements/implications
Lends itself to:
- eBooks
- Online processes / procedures / manuals
- Compliance (access/read acknowledgment)
- Low/no cognitive demand on users
- Unstable content
- Text dominate resources/learning requirements
Lends itself to behaviourist, instructivist and process based theories
Level 2 Interactivity – Limited Participation
This level involves the recall of more information than a Level 1 and allows the student more control over their learning. Standard use of interactions such as explore interactions and check boxes. Typically Level 2 is used for non-complex information and procedures. Simple simulations may be presented to the user. This level also may include simple to standard stock graphics, and some generic customer provided video and audio clips.
Usage
User has limited control
Possible use of basic watch-me simulations
Basic (one or two step) Flash interactions
Basic/limited production resources
Substitute a high level PowerPoint
Unstable content
Some prod resources required
Small dev cost
Small maintenance cost
Lends itself to content that is:
- Primarily text based
- Processed ‘training’
- Simple simulations
- Behaviourist, instructivist and process based
Low cognitive demand on users
Level 3 Interactivity – Complex Participation
This level involves the recall of more complex information (compared to Categories 1 and 2) and allows the user an increased level of control over the lesson. Video, graphics, or a combination of both are presented simulating the operation of a system or equipment to the user. Simulated scenarios and maintenance procedures are often practised with Level 3. Multiple software branches (two to three levels) and rapid response are provided to support remediation. Emulations and simulations are an integral part of this presentation. This level may also include complex developed graphics, and/or clip art, and customer provided video and audio clips.
Usage
Complex information
Medium – high level of control
Possible use of watch, guide and test me simulations
Video, graphics, audio, animation to replicate an operation/action
Demand on design and development resources
Engaging scenarios
Multiple pathways
Meaningful feedback to actions/responses
Perhaps support certification / qualification
Ideally relatively stable content
Reliance of production resources
Complex simulations/operations
Replicating real life environment
Lends itself to content that is:
- Cognitive demanding
- Behavioural, instructivist and situational learning
Replicable within an online/CBT environment
Level 4 Interactivity – Real Time Participation
This interactive courseware level involves more in-depth recall of a larger amount of information (compared to Levels 1, 2, and 3) and allows the user an increased level of control over the lesson. Every possible task is analysed and presented with full, on-screen interaction, similar to the approach used in aircraft simulator technology. The lesson material is extremely complex and involves more frequent use of peripherals, such as bulletin boards and workplace resources, to affect the transfer of learning. Synthesis, analysis and complicated operation and maintenance procedures are normally practised within Level 4.
Usage
Highest level of interactivity
Extensive branching (four or more levels)
Levels of sophistication – close to an artificial intelligence
In-depth and complex concepts and information
High level of control
Complex animation and simulation
Replication of real life operations/tasks
High demand on design and development resources
Peripheral resources/doc
Perhaps support certification / qualification
Rich resources – animations, video, audio
More suitable for CBT environment
Sophisticated – artificial intelligence
Lends itself to content that is:
- Cognitive demanding
- Constructivist, behavioural and situational in nature
Replicable within an online/CBT environment
OMG! Specific Flash accessibility techniques, code samples and tests for WCAG 2.0
Historically it’s been difficult to find meaningful help when trying to make Flash content comply with the old W3C, and more recently WCAG2.0, accessibility requirements. This W3C draft list of Flash Techniques for WCAG2.0 is (a draft version) of the final word.
It includes detailed instructions for the Flash IDE Accessibility panel, example AS2 and AS3 implementations, and tests to ensure compliance for 35 different Flash scenarios. I love this list because it makes it easier for me to explain the amount of work in ‘making it accessible’ to colleagues who don;t really ‘get’ accessibility.
More than that, it gives testable code examples of specific implementations and explains them in multiple contexts. Thankyou W3C! 
Because it’s currently a draft document you won’t find these techniques in the ‘How To Meet WCAG 2.0 Checklist‘. Comments close on August 9.
Combining the Timeline with OOP AS3 in Flash – InsideRIA
My team currently has 3 graphic designers (only one of whom can code, and that’s currently restricted to timeline code) and 2 Actionscript coders. Our workflow relies on designers laying out screen content and coders ‘connecting it up’.
As a result we use a lot of OOP classes, but also make use of a lot of timeline code. It lets everyone work together in relative harmony, allows team members to work relatively independently and lets us get the job done quicker.
Our standard practice is to declare stage instances on frame 1, no matter what, and ensure they exist across the entire timeline, hiding and showing when necessary. It works, but it ain’t elegant. This is the next level…
Making Flash Accessible – A pragmatic approach
My first serious exposure to Flash and accessibility was in 2004. One of my problems then was my understanding of accessibility. That’s improved a little, but the landscape changes (along with Flash and Actionscript) and since then I still haven’t found a solution that lets me produce ‘accessible’ content with the same effort as my usually inaccessible work.
While I don’t have anything I’d call a ‘complete solution’ I’ve used a number of partial solutions along the way:
- providing an onscreen link to an HTML-only version of the interactive content. This is never a straight copy of the text content. It’s a re-write of the interactive content as though it were an article, delivering the intended message without any audio, video, animation, images or colour. It’s the quickest way I’ve found to give a version of the content that’s accessible to the maximum number of assistive technologies with the minimum of production effort (and cost to the client);
- providing Flash content that is visible to MSAA enabled assistive technologies (like the JAWS screen reader) and also ‘wired up’ for keyboard navigation; and
- customised captioning combined with keyboard navigation, like this example (from 2004) to provide content accessible to hearing-impaired users and keyboard-only users.
AFAIK, obstacles that still stand in the way of convenient production of accessible content in Flash include:
- Flash still isn’t happy talking to Apple’s assistive technology. We can still only rely on MSAA as a technology bridge between the Flash Player and the real world (in this case, Microsoft’s real world);
- The vast number of impairments and their relevant assistive technologies. As well as additional development time it presents a massive overhead in testing. I’ve never yet been able to successfully justify the additional cost of purchasing the most basic assistive technologies (JAWS, a workstation to test on) to any employer.
So where to from here? I need to assume that there won’t usually be the budget or resources for producing multiple versions of the content, so I think the majority of my clients (Australian, so our legislative requirements aren’t yet as stringent as the US) would be happy with keyboard and screenreader accessibility.
For static content that’s fine, but interactions (beyond standard component-based radio-button and checkbox interactions) will need to be designed and coded quite differently, or ignored altogether.
If you’ve read this far you might already have pragmatic solutions to these problems – what are you doing about them?
SCORM 1.2 Cheatsheet
A colleague of mine recently produced these neat SCORM 1.2 and SCORM 2004 cheatsheets. I like being able to see all the options in one place, instead of trolling through the manual like I usually do.
Get it here SCORM Cheatsheets.
Thanks to Mike Richards for this.
