View

Views are the most powerful addition in Rendr. They are capable of rendering HTML on both the client and the server. This boosts the performance of your initial content load, and improves SEO by enabling web crawlers to easily crawl the contents of the rendered HTML, which has traditionally been a challenge with AJAX-loaded content in client-side Backbone applications.

Rendr.View also hides a lot of the inner workings. Simply invoke the render method of a view and it will re-render the template with the current state of the data. You can also write code in the preRender and postRender hooks provided.

Another performance boost comes with 'lazy-loading' views (see fetchLazy). When you lazy-load a view, it will wait to fetch its data from the API until the page has finished loading on the client. After fetching the data, it will automatically render that component. The views that don't affect SEO or are secondary to data are prime views to lazy-load.

attach View.attach()

This is invoked when the HTML has already been rendered by the server, and it invokes the preRender and postRender functions to set up accessors and any additional bindings for the view. Finally, it triggers the attach event.

attachChildViews View.attachChildViews()

Removes all of the view's current child views, then finds all instances of child views in the generated view HTML and calls attach on each child view.

attachOrRender View.attachOrRender(element, parentView)

This is invoked when View is hydrating the childViews. This inspects the element to see if the view is lazy loaded or already attached. If neither of those are true, then it will check if the data-render attribute is set on the element. If so, then it will invoke the render function. Otherwise it will call the attach function on the element.

childViews View.childViews

An array of subviews of the view.

constructor new View([options])

Creates a new instance of the View object. A required option is app which is used in many helper functions throughout the view.

The constructor will also intelligently retrieve model and collection information. If you pass a JSON object with an id and give it the collection_name or model_name options, it will retrieve that data from the corresponding store and set the populated model / collection as an attribute on the view. For more information on parsing the model and collection attributes see parseOptions.

You can set additional initialization information in the view constructor by adding an initialize function, just as in Backbone's initialization.

Another special option is template_name, where you can set a different template for the view. By default this is undefined.

decorateTemplateData View.decorateTemplateData(data)

This function takes the result from getTemplateData and applies special properties to the data for the view. The special properties are _app, _view, _model, and/or _collection: the instance variables for each of the options set on the view.

These are generally used in view helper functions, and for passing the instances to sub-views.

fetchLazy View.fetchLazy()

Client-side only Set the lazy option to true to lazy-load a view.

var view = new View({
  'lazy': true,
  'fetch_params': { id: 1 },
  'model_name': 'TestModel'
});

View options for enabling lazy loading:

• lazy - Set this to true to stop the server from trying to render the HTML server-side
• fetch_params - An object of parameters to send to the API for the model or collection. In practice, you'll want to JSON.stringify() the parameters because of client / server differences. This will automatically be parsed to JSON in the fetch request.
• model_name - This is used to make the fetch request for a model with the given parameters
• collection_name - If you're requesting a collection, this is the name of the collection for the view

When the request begins, the loading class is added to the view, the loading event is triggered, and preRender is invoked before the fetch request to the server. Once the data is retrieved from the server, if the view is still attached to the DOM, it will parse the results and render the view.

getAttributes View.getAttributes()

Get the HTML attributes to be added to the element. This will set the id, attributes, and class information; then adds data- to the keys for all options not included in nonAttributeOptions.

This returns an object with all the attribute names and values.

var view = new View({ 'view-option': 'test' });
view.name = 'viewName';
view.className = 'text-muted';
var attrs = view.getAttributes();

// attrs
{
  'class': 'text-muted',
  'data-view': 'viewName',
  'data-view-option': 'test'
}

getChildViewsByName View.getChildViewsByName(name)

This searches the childViews attribute to return any children views that have a matching name. The function takes a string for the name, and returns an array of matches.

Note: The argument must be the exact name of the view, including a path or namespace if those are present.

getHtml View.getHtml()

Returns the HTML for a View, including the wrapper defined in the view. This invokes getInnerHtml then builds a wrapper element using the attributes from getAttributes.

var View = RendrView.extend({
  tagName: 'a',
  className: 'text-primary'
});


var view = new View({
  'additional-option': 'test'
});

view.getHtml();

The Result: '<a class="text-primary" data-additional-option="test">/* template */</a>'

This function should only be used on the server.

getInnerHtml View.getInnerHtml()

Turns the view's template into a string of HTML, without the wrapper element defined in the view itself.

This function invokes the preRender hook, which ensures that preRender is invoked on client and server.

getTemplateData View.getTemplateData()

Returns a JSON object of the data available for the template. This data includes a JSON version of the model or collection attributes and all of the view's options.

Overriding this function allows us to introduce additional variables that need to be computed at run time.

View = RendrView.extend({
  getTemplateData: function () {
    var data = RendrView.prototype.getTemplateData.call(this);

    return _.extend({
      now: (new Date).getTime()
    }, data);
  }
});

// Our templates we have access to the `now` variable, which is set to epoch time.

getTemplateName View.getTemplateName()

Helper function that returns the name of the template. If there is a template_name option set, it will use that. Otherwise will use the view's name.

lazyCallback View.lazyCallback(results)

Client-side only Callback function which is invoked on the successful request for data from the server in a fetchLazy request. The function has a results parameter which is the object returned from the fetch request. By default this function will simply render the view, inserting the information for the view into the DOM.

lazyErrorCallback View.lazyErrorCallback(err)

Client-side only This is callback function is invoked once the fetchLazy has been completed in the case of an error. This function is meant to be overridden on a view where you want handle an error when the view is lazy loaded. The first parameter is the error that was received from the server allowing you to handle errors according to the status code or error text from the server.

module.exports = BaseView.extend({
  lazyErrorCallback: function(err) {
    if (err.statusCode === 404) { this.remove(); }
  }
});

The above code is an example of how you might want to handle an entity not found in a lazy-loaded view. To override the success handler see the lazyCallback function.

name View.name

Defines the lookup key for the template. By default it is set as the underscorized name of the view. E.g. FlightPathView.name is flight_path_view.

nonAttributeOptions View.nonAttributeOptions

These are options for the view that we don't want to create data-attributes for on the HTML element. By default it's set to ['id', 'className', 'tagName'], which are all attributes of the element itself. For more information about those specific elements check out Backbone's documentation.

parentView View.parentView

Stores a reference to the view in which this view exists. This will be undefined for the highest level view.

parseOptions View.parseOptions(options)

This function populates the this.options attribute, setting any required options on the view instance. It will also create an instance of a model or collection if the corresponding data is passed in.

var view = new View({
  app: myApp, // some Rendr app object
  model: {
    id: 1,
    name: 'Luke Skywalker'
  },
  model_name: 'Character'
});


/
/ view.model will be an instance of the 'Character' model
 * with the attributes: id = 1, and name = Luke Skywalker
 */

The same can be done with a collection, with the keys collection and collection_name.

If you pass in an instance of a model or collection in the model or collection attribute, it will simply set the view property to that instance.

postRender View.postRender

Client-side only This is only invoked after rendering or attaching the view. By default postRender is a no-op. If anything needs to happen after rendering a view, it should go in this overridden function. For instance, jQuery plugins should be initialized here.

preRender View.preRender

Defined in the View class as a no-op. The sub-class can override and hook in before the render function is called.

remove View.remove()

Removes references in a view – removes all the child views, cleans up references to other views, sets viewing to false, removes the view from the DOM, and removes event listeners bound using Backbone events or listenTo.

This is invoked automatically on all the child views when the parent is removed.

removeChildViews View.removechildViews()

Calls remove on each view in the childViews.

render View.render()

Client-side only Expects the DOM to be present.

This calls getInnerHtml to get the HTML for the view, then sets the attributes on the element, and finally invokes the postRender hooks.

In general, you should never need to override the render function – use postRender instead.