Module basics

As described on the Extending xJSFL page, a Module is a collection of folders and files that are packaged together to provide related functionality.

This page will expand on that to give you a clear idea of the various components that go to make up a module, physically and conceptually, and where necessary, illustrating points with the the Snippets module that comes with xJSFL.

For a short tutorial on creating a module from scratch, see Writing an xJSFL Module.

Anatomy of a module

Folder structure

The folder structure of a module mirrors the core or user folders, as it is a self-contained entity with its own relationships and inter-dependencies. However, rather than going over the layout and structure again, take a look at Komodo Development or Folder structure for more info.

In the case of Snippets, we have:

• assets - icon files used in the SWF panel
• settings - settings, such as icon locations and Snippets folders
• data - information about all the files and folders Snippets has scanned
• jsfl - the core Snippets code
• ui - the SWF Panel that you see in the Flash interface

Module base class

The core of every module is its JSFL class, which always extends the Module class.

The Module class is fairly lightweight, but handles basic operations like defining a base URI, automatically registering itself with the xJSFL core, and setting up default settings and data Config instances.

The constructor for a module is:

new Module('Module Name');

The module's subfolders would reside under the following folder:

xJSFL/modules/Module Name/

And the module instance itself is stored as a property on the xjsfl.modules Object, as the lower-case module name with any non-word characters omitted, like so:

xjsfl.modules.modulename

Public methods

For a module to actually do something it will need some public methods that encapsulate JSFL functionality. The method names and functionality the contain will be dependant entirely on the purpose of your module, but in the case of Snippets they fall into a few main categories:

• functions to open, run, or browse to files in the main SWF panel
• functions to read JSFL folders and create the actual XML data
• a function to display an additional XUL interface
• additional functions to manage  multiple data files

The public functions are called from the SWF Panel using the AS3 Module framework directly on xjsfl.modules.snippets.

Config

Often you will want to read and write some kind of module configuration data, be it settings or physical data. This is handled using the xJSFL Config class, which is essentially a wrapper for native XML, with functionality to save, load and update the data.

By default, modules create two default instances of Config, one for settings and one for data. You then access settings or data within your module like so:

this.settings;
this.data;

The XML files for these settings / data properties are read and written by default to:

• xJSFL/modules/Module Name/config/data/modulename.xml
• xJSFL/modules/Module Name/config/settings/modulename.xml

If your module doesn't use settings or data, these files won't be created.

UI (XUL & SWF)

The user interface of a module (if it has one) is typically a Flash panel (although it could just as easily be a XUL panel).

If the UI is a Flash panel, the user will need to open the panel from the Windows > Other Panels menu in Flash. If the UI is a XUL dialog, it will need to be shown programatically via the module's API. This is left up to the individual developer to decide how best to implement.

Typically AS3/JSFL communication is done using MMExecute(), passing strings of JSFL to the JavaScript environment from an ActionScript SWF Panel. In traditional JSFL this can get fairly complicated fairly quickly, however, by targeting only the module's public API, and not writing any JSFL in the ActionScript environment, you can simplify your code greatly:

// AS3 class code
call('someMethod', [1, 2, 3])

// executed JSFL
xjsfl.modules.modulename.someMethod(1, 2, 3);

The xJSFL AS3 Module Framework simplifies AS3/JSFL communication considerably by providing an API for full JSFL communication, as well as providing a core framework on which to build SWF Panels.

This additional framework will be documented shortly.

Next Steps

• Writing an xJSFL script
• Module basics