Client Side CommonJS

Your client-side JavaScript (client.js) will be modularized and concated into site.js by brick-asset, see: Static Resources.

Brick.JS implemented a basic CommonJS environment for the client-side JavaScripts. Thus gives power to write conflict-free client-side JavaScripts. This article explains:

How Brick.JS modularize your client.js,
How CommonJS loader load active modules,
How to export current module, and
How to require another module.

CommonJS Modules

Consider this brick:

- bricks/
  |- hello-world/
     |- view.html
     |- client.js

with client.js as:

console.log('am loaded');

brick-asset will generate site.js containing:

CommonJS.register('hello-world', function(require, exports, module){
    console.log('am loaded');
});

Your client.js is registered as a CommonJS module with the name "hello-world". This CommonJS module will be loaded on demand.

As you can see, your client.js is isolated by function wrapping.

DOM Based JS Loading

Brick.JS detects active bricks by traversing the DOM. Corresponding modules shall be called on DOM Ready.

For example, hellow-world/view.html:

<div>
  {% include 'nav-bar' %}
  <p>Main Content</p>
  {% include 'footer' %}
</div>

include Tag is provide by brick-liquid, see Template Engines.

The above template will be rendered as:

<div class="brk-hello-world">
  <div class="brk-nav-bar">...</div>
  <p>Main Content</p>
  <div class="brk-footer">...</div>
</div>

Brick.JS will detect these active (present in the DOM) bricks:

hello-world
nav-bar
footer

Corresponding modules will be loaded by CommonJS loader.

Each module will never be executed more than once, regardless how many times they appeared in the DOM.

Require and Exports

Brick.JS implemented CommonJS (Node.js compliant) require/exports mechanism.

module object contains properties like:

id(<String>, hello-world in this case)：The identifier for the module. Typically this is the param-cased module name.
children(<Array>): The module objects required by this one.
loaded(<Boolean>): Whether or not the module is done loading, or is in the process of loading.
parent(<Object>): The module that first required this one.
elements(<DOMCollection>): root DOM element collection for the current brick.
require(id)(Function): module.exports from the resolved module.
exports(<Object>): This will be returned when this one is "required".

require is aliased to module.require, and exports is aliased to module.exports.

Brick.JS CommonJS is compliant (almost) with Node.js, see:

Require Demo

Consider brick foo requires brick bar:

- bricks/
  |- foo/
     |- client.js
  |- bar/
     |- client.js

foo/client.js:

var bar = require('bar');
bar.log(bar.author);     // 'harttle'

bar/client.js:

exports.log = console.log.bind(console);
exports.author = 'harttle';

And foo/ is the active brick (present in the DOM), you'll get this output in the console:

harttle

Brick.JS CommonJS handle require cycles exactly like Node.js, see: https://nodejs.org/api/modules.html#modules_cycles

Client Folder

It's possible for one brick to contain multiple CommonJS Modules by creating a client/ folder instead of client.js.

client/index.js and client.js are called Entry Files, entry files will produce CommonJS modules named by "<Brick-ID>".
other files within client/ are called None Entry Files, each of them will also produce a CommonJS module named by "<Brick-ID/File-Name>".

For example:

loggin-demo/
   ├── view.html
   └── client/
       |─ index.js
       └─ logging.js

With file contents:

// file: client/index.js
var debug = require('logging-demo/logging');
debug('xxx', module.elements);

// file: client/logging.js
function logging(){
    console.log.apply(console, arguments);
}
module.exports = logging;