- CommonJS Module Specification implementation
- Resources - The Resources directory of a Titanium application, where the user's source code lives before any processing by our build system. Note: For Alloy, CommonJS modules are placed in
exports- a free variable within a module, to which multiple properties may be added to create a public interface
module.exports- an object within a module, which may be REPLACED by an object representing the public interface to the module
CommonJS Module Specification implementation
Our specific implementation of the CommonJS Module Specification is based on (and the early implementation on Android taken directly from) that of node.js. While we should not consider our implementation a direct clone of node, we should favor node conventions where possible to foster reuse of modules across both environments.
In order to use a module within Titanium, you must use the
The string passed to
sayHello, which would print a name and a welcome message to the console, it would be accessed in this way:
Native/compiled modules are identified by a single string, specified within the global app configuration in tiapp.xml. Given the following configuration for a native/compiled module in tiapp.xml:
and the following code within a Titanium Mobile application:
Titanium will load the
ti.paypal native module, and will NOT attempt to look for or load a module from Resources. If a native module is not found for the string passed to
../, or similar, it is assumed that the module is being referenced relative to the Resources directory. In a Titanium project with a CommonJS module file located in
Resources/app/lib/myModule.js, that module could be loaded as such:
var myModule = require('app/lib/myModule');.
Similarly, if the path is prefixed with a
/, the module path is also resolved relative to the Resources directory. For the module above, another valid loading syntax would be
var myModule = require('/app/lib/myModule');.
Relative paths may be specified as well. Assume we have modules located in the following locations:
Now assume we are writing code inside the
SomeCustomView.js module file. The following are valid
exports to which properties may be added for the public interface of the module.
As many properties as desired can be added to the exports object.
Alternately, if the module author wishes to make the exported value from the module an object of their own design and choosing, there is a non-standard (but common, as with node.js) extension to the Module specification which allows for this. The
module.exports object is available within the module file, and may be assigned any value which the developer would like to return from the
require function for their module. This is most commonly used for functions which act as object constructors. The following would be a typical use case for this:
Antipatterns and unsupported behavior
No direct assignments may be made to the exports object:
Similarly, you should not mix and match usage of
Also, it is recommended that you not mix and match assignments to
exports - use one or the other:
Security and sandboxing
As in the CommonJS Module specification, all modules have their own private scope. Variables declared within the module file are private - anything that needs to be made public should be added to the exports object. For more information on sandboxing, refer to the CommonJS module spec.
All modules in Titanium are created once, and then passed by reference on subsequent occasions when the module is required. Because of this, modules themselves may have state variables, which are properties of the "singleton" object represented by the module.
There shall not be ANY global variables in a Titanium application shared across all modules. Any data a module or any objects exposed by a module require should be passed in during construction or initialization.
Here are some examples of modules we expect developers to implement:
Packages of related functionality
Titanium supports node.js modules and structures the
require() handling based on the node.js require-specification. Read more about this topic in the dedicated Node.js guide.