Ignitables

Creating Ignitable Modules

Ignitables are regular node.js modules that are specially designed to export metadata to the Runtime.

The following example shows a fire.js program using a custom expression called Examples.HelloWorld, the expression was provided by a custom module inside node_modules called examplesHello:

{
	"name": "Examples.Hello.Main",
	"json": {
		"@Examples.HelloWorld": {
			"hello": "world"
		}
	}
}

Check examples/helloModuleProgram/ and execute to see the results:

$ firejs Examples.Hello.Main.fire.json
{"hello":"world"}

Don't forget that even when the fire.js module it's installed in your project, the Runtime will not load it automatically unless you explicitly specify them in the ignition manifest, take a look at examples/helloModuleProgram/ignition.manifest.json for an example:

{
	"modules": ["examplesHello"]
}

The module, examplesHello, that exported the expression @Examples.HelloWorld was declared as follows:

var fire = require('fire')
var Expression = fire.Expression
function ExamplesHelloWorld() {

}
ExamplesHelloWorld.prototype = new Expression()
ExamplesHelloWorld.prototype.execute = function() {
    this.runInput(function(res, self) {
        self.end(res)
 	});
}
fire.igniteModule(module, require).exportExpressions([
    {
        name: "Examples.HelloWorld",
        implementation: ExamplesHelloWorld
    }
])

All ignitable modules are required to call igniteModule with module and require values of the caller scope.

Note: Ignitable modules should export at least one expression.

There is a second flavor of exportExpressions called exportExpression that receives a single definition instead of an array.

Module Initializer

The runtime allows the module to completely configure the Runtime as needed. When you ignite your module, the returned object allows you to set the initializer function for your module, the Runtime will call the initializer function just after all the manifests have been merged and the runtime it's ready to execute the main expression of the application. The runtime instance and a callback are provided as arguments.

var ignitedModule = fire.igniteModule(module, require)
igniteModule.initializer = function(runtime, next) {
    //Here you can do do some initialization stuff...
    //... like checking some configuration using runtime.getModuleConfiguration(moduleName) or set some default using runtime.setModuleConfiguration
	next() // or call next(someError) if you want to report an Initialization error.
};

Note: Just like in any other callback, you should always call the 'next' function with no arguments if the initializer succeeded or with an argument to report an error found.

Expression Directories

Just like for the applications, the runtime will load all the expression definition files from the root of the module, that means that all the files with extension .fjs and .fjson in the root of the module will be exported as part of the ignitable module without needing to call exportExpressions or exportExpression.

Note: You still need to call igniteModule from the main file of your module.

Root of the Module

The root of the ignitable module is there the main javascript files resides. This is not necessarily where the package.json file resides.

Examples:

Structure A:

~/MyModules/CaseA
	+ index.js

Root of the Module is ~/MyModules/CaseA

Structure B:

~/MyModules/CaseB
	+ package.json
	+ index.js

Root of the Module is ~/MyModules/CaseB

Structure C: The package.json files declared "main": "./lib/index.js"

~/MyModules/CaseB
	+ package.json
	- lib
		+ index.js

Root of the Module is ~/MyModules/CaseB/lib

Additional Expressions Directories

If the ignitable module is too complex the developer might want to organize expressions in different directories by features, this can be achieve in two ways: By using the ignition manifests or by calling the exportScriptsDir function.

scriptDirectories directive in the ignition manifest

The ignition manifest of the module can specify sub-directories to export expressions for the runtime. The directory paths will be relatives to the root of the module.

Example:

{
	"scriptDirectories": [
		"subExpressionsDir",
		"subExpressionsDir/subSub"
	]
}

exportScriptsDir function

By calling the exportScriptsDir function you can declare a sub directory of expressions, you can even specify header attributes to be merged into the definition of those expressions.

var ignitedModule = fire.igniteModule(module, require)
igniteModule.exportScriptsDir('coolExpressions', {
	"coolExpressions": "Cool Expression Value"
})

Now all the expressions loaded from the coolExpressions sub-directory will contain an attribute called 'coolExpressions' additionally to the mandatory attributes name, json or implementation attributes.

Thanks for Reading. Please take your time to read other tutorials.

Contributors

• Johan(author) - [email protected]

If you find any error in this tutorial(misspelling errors, syntax errors, etc) please send me an email with your corrections, I'll be more than happy to add you in this list.