Core Themes Helpers

Helper Functions

Helper functions are typically curried functions that have taken the current req / res and returned a function that operates on them without having to pass req, res throughout the templates.

All helper functions are automatically passed into every template rendering process, so they will always be available. They are available directly via calipso.helpers from within any module routing function, and are exposed directly in any template file.

Where to find them

Core Helper functions are defined inside the lib/Helpers.js library in core. The list of available functions is:

Function	Type	Description
request	Synchronous	Exposes the request object as a shortcut.
flashMessages	Synchronous	Shortcut to messages added to session flash.
t	Synchronous	Translation function loaded by translation middleware.
user	Synchronous	Shortcut to current logged in user.
prettyDate	Synchronous	Formats date in to 'pretty' duration (e.g. 15 minutes ago).
hotDate	Synchronous	Formats date based on recency (e.g. applies colour class).
getBlock	Asynchronous	Retrieve a block by name or regex that has been rendered by a module.
getMenu	Synchronous	Retrieve a menu.
getModuleFn	Asynchronous	Execute an exposed module function directly (must be exported).
getPageClasses	Asynchronous	Create a class value that represents the current page.
getPageId	Asynchronous	Create an id value that represents the current page.

Module Defined Helper Functions

Modules can also register additional helper functions that can then be used in themes. Additional helper functions defined by core modules are

Content Module (modules/core/content)

getContent	Asynchronous	Retrieve content based on it's alias, this returns ONLY the content property (not the content object).
getContentList	Asynchronous	Retrieve a an object that contains a list of content, and a pager, based on a provided mongoose query.

Using Helper Functions

Helper functions can be used in 4 locations:

1. Inside a module router function.

Helpers can be used inside a module routing function, as they are correctly within the req/res scope. An example is shown below, providing a way to safely call a function exposed by another module (which may or may not be there) (this may not be a great example!):

calipso.helpers.getModuleFn(req,'template.templatePage',{template:'templateShow'},function(err,output) {
  // Do something
});

This allows you to call a function in any other module, and executes the function, failing silently if the module does not exist.

2. Inside a module template file.

All helpers are exposed directly within template files, but with one very important point:

^ You cannot use asynchronous helper functions from within a template file, they must be used prior and their output passed into the template function as an option.

The best example is from the user module, that demonstrates both the user and translate helpers in action:

<h2><%- t("{name} Profile",{name:user.username}) %></h2>

3. Inside a theme template backing js file.

Theme backing files are described in more detail in Theme Backing Files, but basically they are simple modules that export a single function, whose sole purpose in life is to enable themes to execute asynchronous functions during the template rendering process.

function(req,options,callback)

req = request object (will be refactored out - is available via options.request).
options = all helper functions and other data passed through to template
callback = function to call back with options to then pass through to template

A complete example (from sideBar.js in the cleanslate theme) is:

exports = module.exports = function(req, options, callback) {

  /**
   *  Get additional content for blocks in the template
   */
  calipso.lib.step(
    function getContent() {

      options.getContent(req, 'about-me', this.parallel());
      options.getBlock('tagcloud',this.parallel());
      options.getBlock(/^side.*/,this.parallel());

      // Demonstration of how to use getModuleFn
      options.getModuleFn(req,'template.templatePage',{template:'templateShow'},this.parallel());

    },
    function done(err, about,tagcloud,side,fn) {
      callback(err,{about:about,tagcloud:tagcloud, side:side, fn:fn});
    }
  );

};

You can see above the use of the helper functions directly from the options parameter (note: this probably makes more sense to call it something other than options perhaps?).

4. Inside a theme template file.

Finally, helpers are also then again exposed within theme template files, but again with the same restriction on asynchronous functions - they must all be executed in the corresponding backing file for the page.