App

The App is a specialized Model. A lot of the choices between client / server happen in the app. Here are some of its major features:

• Defines the template adapter
• Defines the template engine
• Initializes the client / server router
• Initializes the fetcher
• Initializes modelUtils
• Initializes the app view, which in turn will initialize all views in use
• Starts the client-side router
• Bootstraps the data from the server into the client

bootstrapData App.bootstrapData(modelMap)

This is generally invoked in the layout file following the constructor call. This will simply call the Fetcher.bootstrapData function.

config

The options that can be passed into the Rendr App object.

• dataAdapterConfig Standard way of configuring the built-in RestAdapter, which is a simple REST pass through.
• dataAdapter optional Allows you to override the default dataAdapter. The default is a simple REST pass through. If the dataAdapter option is set, the dataAdapterConfig will be ignored.
• apiPath optional Root of the API proxy's virtual path. Anything after this root will be followed by a -. Example: /api/-/path/to/resource. Allows the proxy to intercept API routes. Can also be a full path to a remote API http://api.myserver. The default is set to: api
• appData optional Pass any data that needs to be accessible by the client. You can access this data from within your Handlebars context as app.attributes.myAttr, and from within your views and models as this.app.attributes.myAttr.
• defaultEngine optional Tell the ViewEngine to load different file types. For example: coffee. By default this is set to js.
• entryPath optional Root path for the app. Default: process.cwd() + '/' (the current working directory)
• errorHandler optional Callback for Express.js errors
• notFoundHandler optional Callback for Express.js not found errors
• viewEngine optional Set a custom Express.js ViewEngine
• viewsPath optional Override where the views are stored. This path is relative to entryPath. Default value is: app/views
• baseLayoutName optional Set a custom name for the base template file of the app. For example myLayout. The default value is set to __layout.

Example configuration:

var config = {
  dataAdapterConfig: {
    'default': {
      host: 'api.github.com',
      protocol: 'https'
    }
  },

  apiPath: '/api',
  appData: { myAttr: 'value'},
  dataAdapter: myDataAdapterInstance,
  defaultEngine: 'js',
  entryPath: process.cwd() + '/myapp',
  errorHandler: function (err, req, res, next){},
  notFoundHandler: function (req, res, next){},
  viewsPath: "/app/views"
};

rendr.createServer(config);

Template Adapters

Provides a way for Rendr to utilize custom html template engines (see also Template Engines section below). Rendr's ViewEngine will delegate to the Template Adapter. You can build your own to provide your template engine of choice (i.e. Jade, Underscore templates, etc).

Available Template Adapters

• rendr-handlebars - Handlebars.js support. This is the default adapter.

• rendr-emblem - Emblem.js with Handlebars.js fallback support.

Using Custom Adapters

You can tell Rendr which Template Adapter to use. This represents the node-module that contains the adapter.

// /app/app.js

module.exports = BaseApp.extend({
  defaults: {
    templateAdapter: 'rendr-emblem'
  }

});

Template Engines

While Template Adapters provide the layer of abstraction that allow you to use your favorite template engine in a Rendr app, the Template Engine option itself will tell the app which version to use exactly. The default is set to be Handlebars, which is currently supported by the Rendr-handlebars adapter until version 2.0.0. When setting up your Rendr app, you'll need to add your Template Engine of choice to package.json.

E.g.

// /package.json

"dependencies": {
  ...
  "express": "^4.12.0",
  "handlebars": "^2.0.0"
  "qs2": "~0.6.6",
  ...
},

Using Custom Template Engines

You can tell Rendr which Template Engine to use. This represents the node-module that contains the engine.

// /app/app.js

module.exports = BaseApp.extend({
  defaults: {
    templateEngine: 'handlebars'
  }

});

constructor new App([attributes], [options])

Creates an instance of the application, setting the modelUtils, fetcher, and router to the app object. Pass in the attributes you wish to set on the application. See the configuration object for more details about options that can be passed into the constructor.

fetch App.fetch(spec)

Curries the function call for Fetcher.fetch. The spec is an object containing the name of the result key and the fetch parameters.

Example spec:

var spec = {
  myModel: {
    model: 'ModelName',
    params: { id: 1 }
  },

  characters: {
    collection: 'Characters',
    params: { name: 'Han' }
  },

  // special model key for the view
  model: {
    model: 'User',
    params: { id: 5 }
  }

  // you can also set a collection to be the focus of the view instead of a model
}

spec declarations and App.fetch requests usually take place in the Controller, which will make the request for all the required data for a given page. These specs are also auto-generated when you lazy load a view.

start App.start()

Client-side only Starts the router, and triggers the start event.

Listen to the start event to add handling code when the app starts up. Activating experiments, loading translations, and setting up analytics are pretty common things to do here.