I'd literally just that morning got off a 12 hour flight from New Zealand, which had left Auckland at 3pm on Thursday, but because we crossed the date line, landed in Los Angeles at 9:30am Thursday! I then had to book into my hotel, and spend the rest of the day getting the talk together. My Thursday was effectively 48 hours!

My plan for the presentation was to:

• present a short set of slides for the framework
• run through a 10 minute live-coding session of the framework's features
• demo some of the tools built for Pocket God, along with Dave Castelnuovo of Bolt

In the end, when our slot came up, most of the audience had been listening to about an hour and half's worth of other talks, and there was now only 5 minutes to fit everything in. With such tight constraints, I basically dumped all the live coding stuff, and Dave and I tag-teamed the preso in a much looser style.

It could have been a lot better, but still good to get it out there! You can see our ramblings here:

http://games.codame.com/post/16568732561/games-coding-event-recordings-jan-18-2012

It was very nice to meet a bunch of local devs as well, and I was amazed that I didn't crash too badly with the lack of sleep.

Thanks Bruno!

• https://twitter.com/#!/brunofonzi
• https://twitter.com/#!/GAMESatCODAME
• https://twitter.com/#!/davecazz

Overview

Currently, if you want to select items or elements based on properties that aren't covered by the built-in selectors i.e. name, :symbol, [x>50], you would need to over-select items, then use a callback to filter the collection.

The following example selects all symbol elements, then filters them using a callback:

function isBlurred(element)
{
    // code for determining whether element is blurred or not
    return state;
}
var collection = $(':symbol').filter(isBlurred);

While that's a perfectly valid way to select elements, rather than selecting then filtering, it would be inherently more flexible to simply define a new selector which itself could be referenced, combined and reused within CSS expressions, for example, choosing to select all blurred stage elements using an expression such as:

':blurred'

Well, it is now possible to register your own custom :pseudo and [attribute] selectors that determine whether an element should be included in a collection via an external callback which you supply.

:pseudo selectors

In the case of the above example, we would register a custom pseudo selector called :blurred to a function that determines if the element is blurred or not:

function blurred(element)
{
    function callback(filter)
    {
        return filter.name === 'blurFilter' && filter.enabled && filter.strength > 0;
    }
    return element.filters && element.filters.some(callback);
}
Selectors.element.register(':blurred', blurred);

Note the colon (:) starting the first parameter of register(). This indicates that the custom selector is a pseudo-selector. Callbacks for psuedo selectors are expected to return a true/false value, indicating the condition either is, or isn't.

You then simply use the selector as follows:

var collection = $(':blurred').select();

The result is, as below:

[attribute] selectors

Often, rather than a yes/no selection, you want the flexibility to select elements based on values at run time, such as an element's  layer name, or perhaps a Textfield's font (did you know that there is no top-level .font property?)

This is where custom attribute selectors come in, which are specified using square braces ([]) and allow us to supply values directly within the CSS expression itself.

The following example examines the element's first textRuns object, and returns the font name:

function font(element)
{
    return element.textRuns ? element.textRuns[0].textAttrs.face : null;
}
Selectors.element.register('[font]', font);

Note that in this case, because a comparison needs to be made, a value, not a Boolean, is returned so that the Selector engine can compare the value within the supplied expression.

Again, the selector is simply used within an expression:

var collection = $('[font=Arial]').select();

The results of which, are below:

In conclusion

As you can see, custom selectors provide a simple and flexible method to choose which elements to select on stage, and have an advantage over filters that they can be easily combined with other selectors simply by concatenating:

var collection = $('[font=Arial][x>30]:selected').select();

And don't forget, you can also write custom selectors for Library items too!

function isAsset(item)
{
    return item.name.indexOf('asset') != -1;
}
Selectors.item.register(':asset', isAsset);

$$(':asset:exported').select();

All this new functionality is available in the repo now.

I can hardly believe it myself, but in the final hours of 2011 I'm officially announcing xJSFL as a Beta release!

The framework has been in pre-beta since around June this year and those following on Twitter will know that the code has been available on GitHub for all that time.

However, it has been a mammoth task to get the framework code, documentation and support material to a level where I feel it's reasonable to release it without insulting people with broken code, or worse, constant changes and updates whilst they try to use it in their own projects.

The real stumbling block though, has been that the Komodo xJSFL extension ended up being a much bigger task than expected, with technical issue after technical issue holding things up.

But now, finally, everything is ready-enough for a Beta release!

So what's new for this release?

Komodo extension

This was the big one, the thing that would really make writing JSFL code easy and fun, and special thanks go to both Todd Whiteman at Active State and David Wagner for making this happen. I got things about 80% of the way there with workarounds, but Todd moved things on to Komodo version 7, and David ironed out the final bugs and omissions. Thank you Todd & David!

ActionScript 3 framework

Initially I wasn't going to release the AS3 code I've been using in the Snippets module and such like, but doing production work with xJSFL it just became too much of a headache maintaining separate code bases and reinventing the wheel, so all the AS3 module code is now going to be released open source with the core JSFL code.

Module framework

The module framework is something I'm really proud of. Proper separation of responsibilities between front and back end, fully-managed, bi-directional communication between AS3 and JSFL, intuitive config and asset management, proper namespacing, library management, and loading of framework code. In a nutshell, Flash panels made easy-peasy.

Library and class autoloading

Early versions of xJSFL had a manual bootstrap file, but I ditched that in favour of fully-automatic loading of libraries, along with bootstraps for core, user, and all module folders, providing a flexible mix between fully automatic and customised initialization and loading of user code.

A unified Selector Engine

Both Item and Element selectors work from a unified selector engine which makes it really easy to add new selector methods. For example, the :animated selector which allows you to select animated items in either the library or stage was implemented in one line of code.

28 core classes and libraries

At the time of writing there are 28 different classes or libraries that ship with xJSFL, covering Data, Elements, Flash, File, OOP, Text, UI and Utilities. These should cover a multitude of needs, and if they don't, just add your own classes to the user/jsfl/libraries folder and register the code with the framework using xjsfl.classes.register().

Documentation

About 75% of the documentation is complete. About 5-10% of that needs to be updated as things have changed since it was written. The remaining 25% still needs to be written (but most of it is Tutorial rather than core API documentation) which I will do over the coming months.

The main things that's not documented right now is the AS3 side of the module framework. See the Sample module for a concise example though.

Caveat Emptor

So, whilst the vast majority of the framework is stellar, what are the things that are not quite there yet?

• Selector code: function arguments need to be expanded from expressions only
• File loading: I may change the format so relative paths load relative to the calling file, rather than the xJSFL root, which will make it easier for Modules to access their own files. A leading slash would default to xJSFL root, and only a file:/// would access an absolute path.
• Context: a bit buggy at the moment, and I don't feel the creation functions are flexible-enough
• User folder and config cascade: was good in theory - still think it has to prove itself
• Documentation: perhaps there's too much?
• AS3 framework: this will probably never be documented. I don't have the time or inclination, so read the source
• JSON: not yet implemented
• Superdoc: good idea in theory, not completely implemented in practice
• CS5 and CS5.5 support: I'm not on CS5+ yet, so no idea about that

ToDos

xJSFL still has a lot of  ToDo items in its code, which I will methodically go through before I announce a 1.0 release. Here they are  in one place (in raw format) for convenience:

Core

xJSFL/core/install/Tools/xJSFL Loader.jsfl

• Add checks to make sure xjsfl.ui folder exists, and promt to reinstall if it doesn't

xJSFL/core/jsfl/libraries/xjsfl.jsfl

• Look to see if passing in an error message is good design or not
• Add option to sort alphabetically, including switches in partition
• change function name parsing to recognize function() {...}
• Connect this to user / framework settings, so messages are only logged if the setting allows it
• Decide whether to display this or not
• IMPORTANT! Throw error / passback false on empty string
• If an empty string is passed back, the system assumes the URI is the root. This could be dangerous (especialy if files are to be deleted!) so consider throwing an error, or passing back xJSFL core
• Add a check to see if we are loading, and if so, only load classes that are not yet defined. Can we do that? Do we need to cache load paths in that case?
• consider moving xjsfl out of libraries
• add a list of filesnames to load first
• Setup modules so that modules are only found, and only when called are they loaded
• Possibly add in an alert box which is controlled by debug level

Data

xJSFL/core/jsfl/libraries/config.jsfl

• decide if this is what we want. Should null configs be allowed?

xJSFL/core/jsfl/libraries/data.jsfl

• Assess feasibility of moving Output.inspect functions to Data as a generic recurse method
• review recursive function signatures & implementation, & provide default callbacks if appropriate. @see Data#recurseFolder
• Fix 260 character limit in File

xJSFL/core/jsfl/libraries/xml.jsfl

• Investigate function:: workaround more thoroughly

Elements

xJSFL/core/jsfl/libraries/context.jsfl

• consider modifying Context.create() to just take a single argument
• add layers and frames properties on timeline and layer changes
• Work out a decent workaround for already selected layers

xJSFL/core/jsfl/libraries/element-collection.jsfl

• Update to handle 3D properties
• modify width and height to update in object-space (rotate, resize, rotate back)
• Add screenwidth and screenheight properties

xJSFL/core/jsfl/libraries/element-selector.jsfl

• Review the use of context here

xJSFL/core/jsfl/libraries/item-collection.jsfl

• double check that expandFolder IS actually buggy

xJSFL/core/jsfl/libraries/item-selector.jsfl

• Review the use of context here
• Handle arrays, element collections, single items, etc

xJSFL/core/jsfl/libraries/selector.jsfl

• Decide where in the process toUniqueArray() should be called

xJSFL/core/jsfl/libraries/selectors.jsfl

• Complete RegExp comparison
• filter() functionality
• not() functionality
• contains() functionality - should this be custom per type, i.e. items, elements, frames?
• nth()
• Add video

Flash

xJSFL/core/jsfl/libraries/iterators.jsfl

• Create global find() method
• Should the DOM iterator swap the active window, or should the callback handle this?
• instead of callbacks, allow any valid context arguments to be sent through

xJSFL/user/jsfl/examples/context.jsfl

• check that frame selection isn't suffering the same toggle bug that layers are

File

xJSFL/core/jsfl/libraries/filesystem.jsfl

• implemement xcopy on windows or the equivilent on a mac
• check if pattern macthes an extension-only, then filter against extension only

xJSFL/core/jsfl/libraries/flfile.jsfl

• Check whether this 260 char limit is an FLfile issue, or a general filesystem issue. @see FileSystem
• need to add spport for network paths

xJSFL/user/jsfl/examples/filesystem.jsfl

• - implemement Data.recurse properly!

OOP

xJSFL/core/jsfl/libraries/events.jsfl

• Double-check pre-emptive events are needed now that we know that JSAPI events are fatally-flawed anyway

xJSFL/core/jsfl/libraries/module.jsfl

• replace name with panelName and add new prototype .panel property
• add call() function which serialises and passes type-safe parameters to the AS3 panel

Text

xJSFL/core/jsfl/libraries/output.jsfl

• Add option to skip underscore properties. If signature gets complex, use an {options} object
• Maybe just have an include object, which could be like {underscores:false, functions:false,strings:false}
• Refactor all iteration to the Data class
• For callback / debug, output to file in two separate passes - 1:key, 2:value, that way you get to see the actual key name who's value breaks the iteration
• Refactor {filter} argument to an {options} object so many parameters can be passed in
• Refactor illegal "keywords" to illegal "paths"
• Check if we need the compound recursion check, and if a stack.indexOf(value[key]) would suffice

xJSFL/core/jsfl/libraries/table.jsfl

• Add option to automatically skip functions, including constructors
• Add a setHeading() method to add a table heading row
• Update constructor to allow setting of heading

xJSFL/core/jsfl/libraries/template.jsfl

• Make render() more obvious - offload to a protected method perhaps? Need to make stack better-protected
• Add option to auto-clean unused tags
• Look at re-constructing class to make variables private
• Look at renaming variables to _name, then updating Output class
• Add some kind of post-processing / callback, which is called after render
• See how lines that have all placeholders removed can be removed, without removing ALL blank lines

UI

xJSFL/core/jsfl/libraries/xul.jsfl

• Allow a file: uri to be passed into the constructor
• Consider making XUL driver-based, so basic controls are constructed using the core, but can be wrapped with additional markup using driver-based methods
• Alternatively, have an additional XULBuilder class, so code and presentation are kept separate
• Add functionality for basic arithmetic to be performed inside textboxes
• columns flex properly, and ensure appropriate elements flex to fill
• implement building from Object
• // TODO: possibly add in check to skip prototype values in for loop
• Add xml:functionality
• update this to work with xjsfl.utils.parseValue
• add functinality to save a string of variables to a hard-coded location, as you can't pass in query strings, which you then load in manually
• Can the SWF determine its location using ExternalInterface, or do we need to use a hardcoded URL? Does MMExecute work in a XUL dialog?
• check if we need to first set() the property to have it work
• Add support for checkbox groups
• Re-evaluate the logic behind using XMLUI.settings, and think about using XUL.values
• Implement proper validation using rules, and the Validation class

Utilities

xJSFL/core/jsfl/libraries/geom.jsfl

• Add

AS3 framework

xJSFL/core/as3/lib/com/xjsfl/jsfl/modules/AbstractModule.as

• add incoming call() function which deserialises and converts type-safe parameters from JSFL

xJSFL/core/as3/lib/com/xjsfl/jsfl/modules/Loader.as

• Get these from xjsfl.settings.uris

xJSFL/core/as3/lib/com/xjsfl/ui/containers/layout/FlowContainer.as

• Think about using dependency injection here, or an alternative Layout class
• Can this be moved to the display utils class, and packaged like identify?

xJSFL/core/as3/lib/com/xjsfl/ui/controls/rightclickmenu/RightClickMenu.as

• Swap init and select handlers

Modules

xJSFL/modules/Snippets/jsfl/snippets.jsfl

• use Source class instead
• also parse functions
• update to use Template class

xJSFL/modules/Snippets/ui/src/classes/display/panels/SnippetsPanel.as

• Add a favourites or browse popup treeMenu: load, add, remove, manage
• Get latest commits: http://github.com/api/v2/json/commits/list/davestewart/xjsfl/master

Final word

I have wondered how relevant xJSFL is now, especially with the wane of Flash and rise of HTML 5, along with the now de-facto code-only development workflow, where there's little or no reliance on the Flash IDE.

However, the framework is complete, it's good (in fact, I think it's great!) and perhaps with the rise of Flash games, especially on mobile devices, xJSFL will find its place as the framework of choice to manage the assets that will need to be produced, and build the in-house tools that animators and production houses will need to pump this content out. I hope as well that xJSFL will fuel a renaissance in Flash tools, especially those used by individual designers who could really benefit from the power of code in their life.

Time will tell.

Anyway. Get downloading then start working your way down the Support index - it's all hopefully in the most logical order.

Cheers for now,
Dave

Structure

Related lines of code should be grouped into blocks

Whatespace should be used to make it obvious what belongs together and what doesn't

All blocks should be clearly labelled with leading single-line comments

Comments

// comments should be outdented by a single tab, making it easy to scan the code

Explanatory comments should

Variables

Variables names and values should be lined up in columns using tabs when more than one variable is being set, with the = operator ranged right, with a single space separating it from the assignment.

If only one variable is being set, it is OK to use a single space either side of the = operator

Files

File naming

Casing

• Files should be lower case
• Module root folders should be Title Case
• SWF panels should be Title Case

English

• English-language filenames should be favoured over camelCased or hyphenated-file-naming

Summary

Copy

Contents

Contents

API

Properties

Property

Methods

Method

Summary

Copy

Contents

Contents

API

Properties

Property

Methods

Method