Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

require

 

Used to include and evaluate other scripts. Anything exported by a required script is then made available using require.

When require is called, the app engine first checks for the required script in the current directory. If a script with the specified name is not found, it will check the shared lib directory (which contains most predefined modules such as app, util, screen, etc.).

The first time a script is required in an app, it is evaluated and then the exports are returned. If that script is required somewhere else in the same app, a reference to the object created from the first require is returned rather than evaluating the script again.

The following example code includes the util javascript module, which makes all exported util methods then available, including util.isDef, util.forceArray, etc.

Code Block
languagejs
var app = require('util');
 
var foo = util.isDef(bar);  //foo = false
exampleArray = util.forceArray('test');  //exampleArray = ['test']

Note: Required JavaScript files are referenced by their filename without the .js extension.

The same script can be required from multiple places in an application, and the file is evaluated the first time. For example, if your app is written in four JavaScript files, you can require a specific one of them in all of them. This allows different parts of an application to share data and methods.

As an example, see the following app, which is split into three scripts: example1.js, example2.js, and example3.js. The following is its app.json file:

Code Block
languagejs
{
    "name": "test",
    "jsFiles": ["example1.js"],
    "type": "foreground",
} 
  1. When the app is started, example1.js requires both example2.js and example3.js (and example3.js, in turn, also references example2.js). When example2.js is evaluated, its init() function assigns a value to the 'status' property of 'Status set by example2.init()'
  2. This value is saved to the variable 'foo' in example1.js
  3. example2.setStatus() is used to change the value of example2.status to 'Status reset by example1.js'
  4. When the 'bar' variable is set to the result of the example3.getStatus() function, you can see that the 'example2' object referenced in both example1.js and example3.js is actually the same object.
Code Block
languagejs
var example2 = require('example2');
var example3 = require('example3');
 
var foo = example2.getStatus();  //foo = 'Status set by example2.init()'
example2.setStatus('Status reset by example1.js');
var bar = example3.getStatus();  //bar = 'Status reset by example1.js'
Code Block
languagejs
var example2 = {};
example2.init = function () {
	this.status = 'Status set by example2.init()';
};
example2.getStatus = function () {
	return this.status;
};
example2.setStatus = function (param) {
	this.status = param;
};
 
example2.init();
exports.getStatus = example2.getStatus.bind(example2);
exports.setStatus = example2.setStatus.bind(example2);
Code Block
languagejs
var example2 = require('example2');
var example3 = {};
 
example3.getStatus = function () {
	return example2.getStatus();
};
exports.getStatus = example3.getStatus.bind(example3);

Parameters

 

NameRequiredTypeDefaultDescription
JavaScript module
Yes
  

JavaScript module to include.