Overview

When you first unzip xJSFL, you could be forgiven for being a bit overwhelmed with the sheer amount of folders and files. However, worry-not, as there's a repeating pattern to the folders & sub-folders and it's really not as complicated as it first seems.

This structure allows the framework to make simple decisions about loading files, whilst giving the developer scope to move things around within the constraints of the (fairly simple) folder logic.

Top-level folder structure

The very top level folders each have a distinct purpose; think of them as groups, if you will:

/core            - this is core framework; it's all the libraries, classes, and xJSFL goodness that you want
/modules         - this is a list of stand-alone modules; each one is designed to run stand-alone, like a mini-app
    /module A    - e.g. Painting Tools
    /module B    - e.g. Animation Tools
    /module C    - e.g. Snippets
/user            - this is your own personal folder; where you'll spend the majority of your development time

As you can see, the purpose of each folder is quite unique, with the modules folder offering unlimited opportunities to make all kinds of individual tools, packaged within their own self-contained folder structure.

Folder-level folder structure

So, although the purpose of the top-level folders is very different, the layout inside each one is actually very similar; think of each one having the same genetic blueprint, with minor variations as needed:

/assets          - where assets needed by your module are stored
/config          - config and settings files
/flash           - flash-specific assets that are copied to the flash folder on startup, such as command and panels
/jsfl            - where all the JSFL logic is stored
    /libraries   - JSFL libraries, auto-loaded on startup
/ui              - XUL panel files

This is pretty much the standard folder layout.

The tiered, repetitive folder structure serves three main purposes:

1. It provides a logical home for all elements of the framework
2. It provides a scalable way to segment unrelated families of files
3. It allows for preferential loading of settings, using a cascading search process, which is discussed next.

Cascading file structure

One of xJSFL features is that it allows you to override settings in core or module folders, without actually overwriting the files. It does this by using what's known as a cascading file structure, or more specifically, a cascading search process.

What that means in practice, is that when just a partial path to a file is specified, the framework searches for the file from a list of master folders it stores internally, and returns the first matching file it finds.

Let's illustrate this with a real-world example, that of the Snippets panel settings. It stores its settings in:

xJSFL/modules/Snippets/config/snippets.xml

Inside this file are settings for default file icons. If you wanted to change the default file icon, you could edit this master file, or alternatively create a copy of the file in your user folder for xJSFL use instead:

xJSFL/user/config/snippets.xml

Then, when the Snippets module calls...

xjfl.load.file('snippets.xml', 'config');

...the framework will look in the config sub-folder of the top-level folders in the following order, until it finds the snippets.xml file:

1. user
2. modules/Animation Tools
3. modules/Painting Tools
4. modules/Snippets
5. core

In this case, instead of having to get to the 4th folder, Snippets, before finding the file, it finds it in the 1st folder, and so the user's copy of the file is loaded in, leaving the original Snippets copy untouched. If ever the user wants to revert to the original version, he just has to delete the user version.

Libraries vs Modules

In the examples above, I have 2 fictional modules, Animation Tools and Painting Tools. They sound quite grandiose, each perhaps with their own SWF panels, libraries, settings and functions. However, they probably both started their days as simple JSFL libraries, run from the user folder, perhaps with a XUL interface, and perhaps some simple settings.

So when should you consider moving code into Modules? Well...

• If your library has more than 4 or 5 files that work together, locating them in a module could be easier
• If you want to share your tool with others, it's easier to copy and paste a single folder
• If your tool needs an SWF panel, modules have everything in their flash/ folder (panels, Commands, etc) to the main Flash folder automatically

Otherwise, it's fine to simply place your files in your user folder and see how you go.

Next steps

• File handling