File-based icons

One of these things is custom icons. Whilst the supplied FamFam icon set is pretty good, often there's no icon that's "just right". The solution to this up until now has been to simply supply an alternative URL:

/**
 * My awesome snippet
 * @icon {user}assets/icons/awesome.png
 */

This is great when you're just using the snippet yourself, but not so convenient when you need to distribute scripts amongst your co-workers or such like.

Text-based icons

The next release of the Snippets panel supports encoding of icon data into the snippet DocComment itself, by way of a Base64-encoded string.

/**
 * This file demonstrates using a custom icon
 * @icon data:AAAAAAAAAAAAAAAAggAAAKoAAAAqAAAAAAAAAAAAAAAAAAAAAAAAACoAAACrAAAAggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAG4AAACAAAAAKgAAAAAAAAAAAAAAAAAAAAAAAAArAAAAgQAAAG4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAKwAAAKgAAAB8AAAAAAAAAAAAAAB9AAAAqQAAACsAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACsAAACpAAAAfQAAAAAAAAAAAAAAfQAAAKoAAAArAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIUAAACuAAAAqgAAAKgAAACmAAAApwAAAKgAAACrAAAArwAAAIYAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACGAAAAsAAAAKwAAACpAAAApwAAAKgAAACqAAAArQAAALAAAACHAAAAAAAAAAAAAAAAAAAAAAAAAHEAAAC5AAAAtQAAAFkAAAAAAAAAfwAAAKgAAACpAAAAgAAAAAAAAABaAAAAtgAAALkAAABxAAAAAAAAAAAAAAByAAAAuwAAALYAAABaAAAAAAAAAIEAAACqAAAAqwAAAIEAAAAAAAAAWgAAALcAAAC7AAAAcgAAAAAAAADDAAAAwAAAAL0AAAC4AAAAtAAAALAAAACtAAAAqwAAAKwAAACuAAAAsQAAALUAAAC5AAAAvQAAAMAAAADDAAAAxQAAAKoAAACOAAAAogAAALUAAACyAAAArwAAAK0AAACuAAAAsAAAALMAAAC2AAAAogAAAI4AAACqAAAAxQAAAMYAAABiAAAAAAAAAIwAAAC3AAAAswAAALAAAACuAAAArwAAALEAAAC0AAAAuAAAAI0AAAAAAAAAYgAAAMYAAADIAAAAYwAAAAAAAACNAAAAuAAAAC4AAAAAAAAAAAAAAAAAAAAAAAAALgAAALkAAACOAAAAAAAAAGMAAADIAAAAAAAAAAAAAAAAAAAAjgAAALoAAAAuAAAAAAAAAAAAAAAAAAAAAAAAAC4AAAC7AAAAjwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAvAAAAtwAAAIcAAAAAAAAAAAAAAIgAAAC4AAAALwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAUAAAAKAAAAOQAAALgAAACMAAAAGgAAABoAAACMAAAAuQAAADkAAAAKAAAABQAAAAEAAAAAAAAAAAAAAAEAAAAFAAAACgAAABAAAAAVAAAAGQAAABoAAAAaAAAAGQAAABUAAAAQAAAACgAAAAUAAAABAAAAAAAAAA==
 */

The result of this 1.3K string is a completely custom icon in the Snippets panel, which will go wherever the snippet goes:

The new Snippets panel will also finally have an icon chooser, as well as a conversion tool to convert any image you pick from your hard drive into the Base64-encoded string.

• Execute before publish
• Execute after publish

This would allow the user to do some pre-publish cleanup, or some post-publish action, such a uploading a file.

The thing is, however, we can do this right now inside of Flash with Events!

It took me about 10 minutes to whip up some proof-of-concept code, another 5 to add an interface, then another 5 or so to ensure the UI saved and loaded settings, then about an hour or so to create a class out of this lot, add in some extra flexibility, some comments, and say "That'll do".

You can take a look at the source code as a gist on GitHub.

Here's the UI written in one line of code (including populating already-defined values) using xJSFL's XUL class:

Compare that to the amount of time it would take to request the feature, have it accepted, implement it in C++, along with any QA and the rest, plus the fact that once it's in, there's no flexibility - and I think you can see you have a pretty powerful argument for implementing some things in JSFL.

The final class does the following:

• Runs pre and post publish hooks (any file on your hard drive, even other JSFL scripts)
• Has a simple XUL UI to browse for files
• Can load and save different profiles, say one for games, one for web
• Stores setting in an XML config file (but could just as easily store those settings per document using document data)
• Can be set as Active or Inactive should you decide you need to disable it

It's instantiated as simply as possible, like so:

// instantiate a "games" profile
    var hooks = new PublishHooks('games');

// bring up the ui
    hooks.edit();

The config for all profiles is managed by the Config class, and stored in a single file in the xJSFL/user/config folder:

<config>
    <default>
        <active>false</active>
        <pre>file:///F|/Users/Dave%20Stewart/Desktop/test.swf</pre>
        <post>file:///F|/Users/Dave%20Stewart/Desktop/somefile.exe</post>
    </default>
    <games>
        <active>true</active>
        <pre>file:///E|/Projects/xJSFL/user/jsfl/hooks/pre.jsfl</pre>
        <post>file:///E|PProjects/xJSFL/user/jsfl/hooks/post.jsfl</post>
    </games>
</config>

And here's a quick screenshot of a basic JSFL script being run right after publishing:

If you want to use the class, ensure you have the latest xJSFL from the repo (as the Event types have been updated) and download PublishHooks.zip.

The file contains both the class (save to your xJSFL/user/jsfl/libraries folder to run at startup) and a script to pop up the editing UI, which you can run as a Command from the Flash Commands folder or as a Snippet from the xJSFL Snippets folder.

If you want to load external files with xJFSL, it's as simple as providing a path or URI to the file:

load('c:/path/to/library.jsfl'); // absolute
load('library.jsfl'); // relative

If you want to load a library over the network, simply specify a UNC URI, like so:

load('file:////<servername>/<drivename>/path/to/library.jsfl');

The best place to load external libraries if you want to use them each time is in your user bootstrap, which can be found at:

xJSFL/user/jsfl/bootstrap.jsfl

You can do this just by including the load() line above, and specifying the file you want to load.

Loading external modules

Overview

xJSFL's folder structure is designed so you can keep all JSFL-related files in one place, but you can also load code from other folders, or even over the network. This is useful in larger teams where you need a central repository of code, or where you have projects saved in different locations.

Code

There are 2 main core methods that take care of loading or finding modules:

• xjsfl.modules.init() - initializes a specific module
• xjsfl.modules.find() - finds all modules on a path, then initializes them

Each of them accepts as its first argument an absolute URI.

Once you know the URI to your module, simply add some code in your user bootstrap and have the module load each time xJSFL loads:

xjsfl.output.trace('Loading Animation Tools...', true);
xjsfl.modules.init('file:///X|/repo/xJSFL/modules/Animation%20Tools/');

Upon restarting Flash you should see something like the following in the output panel:

> xjsfl: LOADING ANIMATION TOOLS MODULE...

> xjsfl: REGISTERING MODULE "ANIMATION TOOLS"
> xjsfl: added 14 search paths for "X:/repo/xJSFL/modules/Animation Tools/"
> xjsfl: assets are already up to date
> xjsfl: ready!

If you want to load files over a network, then simply use the network path with UNC notation (note the 4 slashes):

xjsfl.modules.init('file:////SERVER/Files/repo/xJSFL/modules/Animation%20Tools/');

Then, when flash starts, it simply looks in this network location to load the module! Flash doesn't really care – it's still just a URI at the end of the day.

If you have a repo with multiple xJSFL modules in, you can use the find method, and just point to the top-most folder. Note the trailing true, which instructs the modules to initialize (have its bootstrap file run) as well:

xjsfl.output.trace('Finding modules to load...', true);
xjsfl.modules.find('file:///X|/repo/xJSFL/modules/', true);

One of my main aims is to get Adobe to fix some of the show-stopping bugs in JSFL, so here’s my list, in order of importance:

1. Fix all empty JSFL error messages, especially inside of fl.runScript() (link)
2. Make sure Timeline and Frame events fire in the correct order (link)
3. Ensure library item selection updates properly for library.setSelected()(link)
4. Fix frame and timeline setSelection bug, which seems to toggle, not set, selections (link)
5. Fix matrix bug in setCustomFill()(link)
6. Have all XUL elements dispatch change events
7. Have all XUL element values be settable via JSFL
8. Ensure running scripts do not timeout after 20 seconds or so when getting values from a XUL dialog (link)
9. Fix E4X pre-declarate filtering, so you don’t need to do this to use E4X filters: var b =  a.*.(function::attribute("id") == ’b’); (link)
10. Would be great if relative file paths worked! Relative to the JSFL file, ideally. (link)

And while we're at it, some feature requests:

1. Access values in the middle of a tween
2. Unlimited workspace area
3. Add JSFL access to undo / redo or history states
4. Add "begin undo" and "end undo" commands, with support for try/catch
5. Make JSFL access on shapes less twitchy and crash-prone
6. Access to stage pan as well as zoom (so we could zoom to object)
7. Ability get the currently-edited-in-place timeline's path to top-most-parent timeline
8. JSFL "PropertyChanged" event
9. JSFL right-click menu item and registerable commands

What do you think?

I’m sure there’s some real gotchas I’ve forgotten, so please add to this list, along with the number in the list you think the fix should go at, and I'll see what I can do about raising them.

Cheers,
Dave

I'd like to add a Case Studies section to the site, and have some practical information that new studios or developers can look over to help them understand the benefits of using xJSFL as part of their production pipeline.

As such, I've put together some questions that you could answer, or you could just put down whatever thoughts you have. As long as you share your experiences, big or small, that's good enough for me.

If you'd like to help, please download the following Word document, answer the questions, then mail it back to me:

• xJSFL Developer Questionnaire

It goes without saying that I would be extremely grateful for the support, but more importantly it will really help the framework gain some much-needed industry kudos, ultimately supporting its ongoing survival :)

Thanks very much,

Dave Stewart

It shouldn't need a fresh install, but you may want to delete the xJSFL/core/assets/install/ folder afterwards, as it's moved one level up.

Changelist

New features

• Added Utils.bind()
• Added Utils.parseExpression()
• Added Utils.columnizeText()
• Added ActionScript.getClass() and refactored ActionScript.getBaseClass()
• Added :scriptable element selector
• Added :sound item selector
• Added JSFLConstants library
• Added support in File for opening XFL files
• Added xjsfl.settings.app.os.win and mac properties

New Content

• Added Declare Library Bitmaps snippet
• Rewrote Declare Stage Instances snippet to be pure xJSFL (went from 200 to 50 lines)
• Updated example files

Bug fixes

• Refactored URI.toURI() and URI.toPath() methods to properly handle absolute/relative Macintosh paths
• Fixed bugs in Config get() (it now passes back XML with attributes as XML, but simple content as Numbers, Strings, etc)
• Updated ItemCollection.attr() to update itself after attributes are changed
• Fixed bug with name selector expression eating following selectors
• Fixed various bugs in user Snippets files
• Snippets panel now remembers open/closed states on rebuild or refresh
• Added UTF8 BOM to all JSFL files (so Asian users, you should now be good to go!)

Updates

• Utils.glob() now lets you pass in a single wildcard path, rather than separate folder + path arguments
• glob paths now accepted in xjsfl.file.load() and URIList
• Refactored ItemCollection.library to ItemCollection.getLibrary()
• Refactored Selectors.parseCSS() and XUL.add() to use Utils.parseExpression()

Installer updates

• Moved installation files from core/assets/install to core/install/
• Shows full paths when copying/removing files
• Removes old commands when reinstalling
• Added xJSFL folder check
• Uses Utils.glob() to detect URIs

Documentation

• Rewrote File Handling section, and specifically the URI Juggling section
• Added new documentation for new methods

It lists:

• All files
• The total lines of JSFL / AS3 code found
• The minimum lines (no white space or comments) of JSFL / AS3 code found

These are the results:

+---------+-------------------------------+-------+-------------+-----------+
| name    | path                          | files | total lines | min lines |
+---------+-------------------------------+-------+-------------+-----------+
| base    | xJSFL/                        |   332 |       65312 |     42358 |
| core    | xJSFL/core/                   |   233 |       60110 |     38430 |
| jsfl    | xJSFL/core/jsfl/              |    60 |       25926 |     17278 |
| as3     | xJSFL/core/as3/lib/com/xjsfl/ |    67 |        9604 |      7348 |
| modules | xJSFL/modules/                |    61 |        3032 |      2226 |
| user    | xJSFL/user/jsfl/              |    26 |        2003 |      1569 |
+---------+-------------------------------+-------+-------------+-----------+

A few things to notice here:

• There's around 18,000 lines of JSFL code in the xJSFL core. This compares to about 9000 lines of javaScript in jQuery, which arguably supplies much less functionality in the core package
• The code written appears to be about 2/3 code, and 1/3 white space or comments. Whilst this seems like a lot, I am quite particular about making sure that all methods and parameters are commented, and that files are broken up with white space and additional headings to make them easy to read and navigate
• The size has more of less doubled from about a year ago, which makes sense as there's a lot of new classes, and a lot of demo code included.

So there you go.

Note: as of June 28, there's also the 1.01 release :)

It's pretty much production ready; all the classes, features, changes and fixes that I've been wanting to put in over the last 9 months are pretty much there.

However, there have been some BIG changes since the Beta!

Changelist

The major changes are:

• A complete rewrite of URI creation and file handling
• A major restructuring of the internal file structure, file searching, and loading mechanisms
• Komodo > Flash integration has been updated (so you'll need to reinstall the latest xJSFL extension)
• Overhauled bootstrap:
• Moved xjsfl.output methods log() and trace() to bootstrap
• Implemented actual file logging (so you can debug startup errors more easily)
• Moved responsibility for loading user classes to user bootstrap
• xjsfl.utils moved to a new Utils class

New features are:

• Support for location-relative paths, i.e. load('some file.jsfl')
• Support for user-written custom selectors such as :blurred
• Support for deep-attribute notation in Selectors, such as [libraryItem.name=Symbol 5]
• Assets in <module>/flash/* are now automatically copied to Flash/Configuration/ on startup
• xjsfl.file.load() now detects errors in loaded jsfl files, and meaningfully warn the user (although disabled for v1.0, coming in v1.1)
• Profile-specific folder can now be added to flash/<lang>/Configuration/xJSFL/...
• XUL can now load and manage manually-written XUL definitions
• Improved installation routine and new uninstalltion routine

New classes and code are:

• New globals - list(), format(), load(), save(), include(), require()
• New classes - Utils, SimpleTemplate, PropertyResolver, URI, URIList, Source, Utils, Color, UI, ActionScript, Globals, JSON,
  
• New object extensions on String, Date, XML
• New utility methods - getDeepValue(), setDeepValue(), getURIs(), getSearchableURIs(), combine(), walk(), walkFolder(), makeTree() (and many more)
• New xJSFL Commands - Reload, Configuration, View Folder
  

Minor changes are:

• The Data.recurse() methods have been moved to Utils, and now support skipping and finding
• Folder now has cross-platform open() and copy() methods, and uris property
  
• Template placeholders now support deep properties, i.e. "The value is {object.value}"
• Logger class rewritten to support placeholder variables
• Table now supports captions and single-object printing
• Long URIs (>260 chars) now throw errors, rather than failing silently
• Library Item instances now have shortName property
• Timeline has selectedLayers getter that returns an Array of Layer instances
• $selection can now be set

Removals are:

• Removed $dir global variable
• Removed Base class
• Removed xjsfl.get (moved to UI)
  
• Removed xjsfl.utils (moved to Utils)
  

As well as:

• A whole bunch of minor fixes & improvements
• Updated example files in modules/Code Examples/

There are a bunch of changes and minor bugs / nice-to-haves that are also on the slate for later versions.

xJSFL 1.0 Framework Schematic

The following (updated) schematic shows the various components, classes and scripts that come with the 1.0 release of the framework:

Documentation

The documentation has been gone through with a fine-toothed comb, and the Guides and API section are now fully up to date, although the AS3 Module Framework is still lacking, as are the Tutorial sections.

Installation

See the installation notes at: www.xjsfl.com/support/setup/quick-start/installation

Beta users: the names of some installation files have changed, so before installation, you may want to manually delete any xJSFL files in Flash's user configuration folder:

• Commands/xJSFL (this should get cleaned up automatically)
• Tools (shouldn't be an issue, but doesn't hurt to remove xJSFL-related files)
• WindowSWF (some panels have new names, just be sure to delete the old Sample or Snippets panels)

So... that's it for now! Enjoy :)

Cheers,
Dave

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.