Skip to content

0.3.x Advanced Usage

Jump to bottom
Jakob Heuser edited this page Jul 20, 2012 · 1 revision

Advanced require.* Methods

These are the methods exposed under the require.* namespace. Many (but not all) are unique to inject. Compatibility is listed under the API's description and parameters.

require.setModuleRoot(String:root)

  • root a string that denotes the module's root

Inject Specific setModuleRoot dictates where all modules should be loaded from when using the require.* keywords. There is only one module root, and it should be the highest level directory that contains the all of the JavaScript you wish you include.

require.ensure(Array:dependencies, Function:callback)

  • dependencies an array of modules that are required in order for callback to run successfully
  • callback a function to run once all of the modules in dependencies are loaded

CommonJS: Async/A require.ensure enables the asynchronous loading of modules. It's highly important in a browser environment where it's not possible to create blocking downloads in a consistent manner. Like require, require.run, and define, this function will scan files for all of their synchronous dependencies and include them. Consider the following dependency tree

    root
  /  |  \
 A   B   C
 |  / \  | \
 C E  F  G  H

In the above tree, we must download and resolve all dependencies, and enable them starting at the lowest level module. This results in an execution context of G H C A E F B root (note the repeated dependency C which is both required by root and by A).

Per the CommonJS Specification, require.ensure is a non-blocking call. This means care should be taken when using require.ensure to modify the exports object. While other objects that depend on a module using require.ensure will load, there is no guarantee that the exports object is complete. As a result, it's common practice to use require.ensure as a top level directive only. require.ensure() is implicitly called by require.run().

require.setExpires(Integer:expires)

  • expires an integer that represents the number of minutes items should remain in cache

Inject specific To minimize delays in loading content, localStorage is used when available. In order to avoid extra HTTP requests, files are retained in localStorage for the specified amount (in minutes). By default, it's limited to a day.

require.setCrossDomain(String:local, String:remote)

  • local the location of relay.html on the same server as your current page
  • remote the location of relay.html on the same server as your module root from setModuleRoot

Inject Specific When loading content from an alternate domain, the use of relay.html is needed. You'll need the file to be available on both the domain of the current page and the domain of your remote content. This method tells inject where to find the relay.html file for the cross domain communication.

require.clearCache(Integer:version)

  • version the version to clear, defaults to current version

Inject Specific this can be used to clear the localStorage cache. If a new schema comes out for file storage, this can be used to clear previous schema versions.

require.addRule(String|RegExp:match, [Integer:weight], Object:rule)

  • match the match to test against
  • weight optional a weighting for this rule
  • rule an object containing information about the rule to apply when match evaluates to true

Inject Specific addRule is used for adding additional path handling and execution rules to module statements requested by all require.* methods. match refers to either a string or regular expression to test against. Strings are tested with a toLowerCase() comparison, while regexes are invoked via their test() method. If the match evaluates to true, the rules will be applied. Rules are formed like the following object (all attributes are optional):

{
  path: String|Function,
  pointcuts: {
    before: Function,
    after: Function
}
  • rule.path set either a string (immediate replacement) or a Function for handling path resolution. The function receives the moduleId as its only parameter, and returns the new path to replace the existing one.
  • rule.pointcuts an object that describes functions that run both before and after the included code. This can be used with non Common-JS compliant code to set up module.exports, clear the collisions in the namespace, or otherwise insulate the code and sandbox it.

Examples for both addrule items can be found in the addRule Example, which loads both jQuery and jQueryUI items using a mix of addRule matches and pointcuts.

require.run(String:module)

  • module the module to execute

Inject Specific run the specified module. This is the equivalent of calling require.ensure([module], function(){})

define([String:module], [Array:dependencies], Function:callback)

  • module optional the identifier of the module
  • dependencies optional an array of modules this callback depends on
  • callback the function to run once all dependencies have been satisifed

CommonJS: Transport/C, Asynchronous Module Definition this is the primary interface for the Asynchronous Module Definition specification. Full details on how define() work are better explained in the AMD Wiki

Clone this wiki locally