Module (class)

Categories:Framework

Overview

Summary

The Module class is the base class for creating xJSFL Modules, which are collections of interrelated files grouped by folder, and managed by a central JSFL class - the actual Module itself.

Contents

Concept

Managing files in JSFL is traditionally done by placing them all in separate files within the main Flash config folder, but this is not a particularly convenient way to structure your projects. xJSFL lets you place code, settings, assets, and flash elements, such as SWF panels into a single folder that is managed by the framework and treated as a single, structured entity.

The xJSFL Module class acts as the JSFL entry point to your own functionality, and is usually accessed via AS3 from its own SWF panel, via the AS3 Module framework.

The Module class is essentially abstract, and it's up to the developer to add new functionality as required by the module in question.

Usage

Resources

See the following sections for detailed information on Module concepts and practical how-to code:

Also, see the Sample Module and Snippets module that ship with xJSFL in the modules folder for real, live code.

API

Module(namespace, properties, window)

Base module class used to create xJSFL modules,

Parameters:

  • namespace String The namespace of the module in the xjsfl.modules object, i.e. "Keyframer"
  • properties Object The properties and methods of the object. Supply a constructor with "init:function(){ ... }"
  • window Window The current window object

Note that creating a new module is a 4-part process. You will need:

  1. The module folder
  2. An XML manifest file
  3. The JSFL bootstrap file
  4. The JSFL module file

See the Anatomy of a module section in Combining multiple scripts into stand-alone Modules for full details.

Once, this is all in place, the process of creating a new module is as follows:

  1. Create a native Object, on which you define the properties that will later become the module's properties. You can add a constructor function here, by creating a property called init, and assigning it to a function.
  2. Create and register the new module via the the xjsfl.module.create() function, passing it the name, properties, and the current window object.

The system will then associate the module code with its manifest, then create, register and return the new module instance.

The following example creates a hypothetical Test module, which runs immediately on being created:

// set the properties for the module
var Test =
{
    init:function()
    {
        trace('Module "xjsfl.modules.' +this.name+ '" initialized...');
        this.megatrace();
    },

    megatrace:function()
    {
        trace('I am ' + this.name.toUpperCase() + '!');
    }
}

// create the module
Test = xjsfl.modules.create('Test', Test, this);
Module "xjsfl.modules.Test" initialized...
I am TEST!	

Properties

The following properties are defined

namespace

The JSFL namespace of the module

  • Type: String
  • Access: Read

This property is defined by the developer when creating the module

name

The given name of the module

  • Type: String
  • Access: Read

This property is defined by the developer when creating the module

uri

The URI to the module's root folder

  • Type: String
  • Access: Read
The URI is derived when the module is instantiated, by matching the manifest file to the namespace

panel

A reference to the panel, if it exists

  • Type: SWFPanel
  • Access: Read
The panel property is defined only if the manifest file declares a panel property

Methods

loadConfig(path)

Load a named module Config file object, either a default, or a specific object

Parameters:

  • pathOrURI String The absolute or relative path to the config file. Passing a relative file path will attempt to find the file in the cascading file structure, defaulting to //user/config/ModuleName.xml

Returns:

  •   Config A new Config instance

The loadConfig() method is provided as a convenience function to load configuration files into the module. By default, no config files are loaded, so it is up to the developer to add this code.

The following example creates a module named Test, and upon loading, immediately attempts to load its corresponding config file into a new Config instance:

// set the properties for the module
var Test =
{
    data:null,

    init:function()
    {
        // with no path parameter, the module loads the default config, named
        // after the module's namespace (in this case Test.xml)
        this.data = this.loadConfig();

        // once loaded, the data (a Config instance) can be interrogated
        this.showData();
    },

    showData:function()
    {
        trace(this.data.get('settings'));
    }
}

// create the module
Test = xjsfl.modules.create(Test', Test, this);
<settings>
    <setting name="one" value="1" />
    <setting name="two" value="2" />
    <setting name="three" value="3" />
</settings>

call()

Calls an externally-registered function in the module's panel. Note that the number of arguments MUST match the registered function

Returns:

  •   Object The result of the call, or undefined if there's no panel

Functions registered in an AS3 Flash panel as externally-accessible using ExternalInterface.addCallback() can be called from JSFL using swfPanel.call(). Module makes all the connections internally and provides a simple call() function so you can have 2-way feedback to your own Flash panels.

The following example calls a theoretical "doSomething" method inside the module's Flash panel, with the parameters 1, 2 and 3:

// called internally in the Sample Module
var result = this.call('externalFunction', 'Hello!');
this.log(result);
> Sample Module: result: "function called!"
See the Sample Module module in the modules folder for a working code example.

log(message, lineBefore)

Log a message to the listener, prefixed with the module's name

Parameters:

  • message String The message to log to the listener
  • lineBefore Boolean An optional Boolean to trace a blank line before the message

The following example :

var module = xjsfl.modules.getModule('Sample');
module.log('Doing something');
> Sample Module: Doing something

getWindow()

Gets the Window object of the module

Returns:

  •   Window The module's window object

Each SWF panel runs in its own window, with its own persistent scope, and sometimes its necessary to peek in to see what the variables are doing.

The following example gets the window of the Sample module, and inspects the:

var module = xjsfl.modules.getModule('Sample');
trace(window === module.getWindow());
false

toString()

Returns a string representation of the module

The following example :

var module = xjsfl.modules.getModule('Sample');
trace(module);	
[object Module name="Sample" path="E:/Projects/xJSFL/modules/Sample/"]	

Comments are closed.