sebastiendaniel-views

Getting started

Views is essentially a minimalist view-controller wrapper, which enhances any template (Handlebars, mustache etc.) by wrapping it with generically useful methods allowing you to easily:

• render & re-render
• add & remove event listeners
• move the template around the DOM (views are entirely portable)
• self-destruct

Basic setup

Start by fetching the necessary files with NPM

npm install sebastiendaniel-views --save

Afterwards you can require one of two files: views or View. views is a mediator wrapper around the View class. It allows you to "name" your views, which will store them into the mediator's cache for future getting, so you won't pollute your environments as much.

window.views = require("sebastiendaniel-views");

Afterwards, make sure to properly configure your views module, see configuration below.

views (mediator) API

The required views module has a minimal, 3 method interface:

create()

creates a new view object, and possibly adding it to views cache.

/**
* @param {object} config - is a view creation object (see below)
* @param {string} [name] -  is an optional string name to later fetch your view with views.get(name)
* if no name is provided, the view won't be stored inside the mediator's cache.
*/
create(config, name);

kill()

triggers a view's "die()" method and, if registered, removes it from the registry

/**
 * @param {string|object} target - view name (if registered) or view object
 * @returns {boolean} - if successful returns true
 */
kill(target);

get()

returns a previously created (and named) view object.

/**
* @param {string} name - the name given to the view when it was created
*/
get(name);

Configuration

views.config allows the setting of 2 important configurations:

config.setRenderMethod()

This configuration is mandatory, the default render() method of the View.prototype makes no operation, it just returns "this" (the view object). When you provide a new render method, it will always be called with two arguments. The example below is a render method for Handlebars templates:

/**
* @param {*} template - the template object set when creating the view (see View below)
* @param {object|array} data - the data that you wish to parse with the template
*/
views.config.setRenderMethod(function(template, data) {
    this.container.innerHTML = template(data);
    return this; // I return the view object to allow method chaining
});

config.setContainerTag()

When a view is created, it is given a "container" element, by default that element is a "DIV". You can change the default with this configuration method. (when creating a view, you can always override the default container tag)

/**
* @param {string} tag - the new (HTML) tag name
*/
views.config.setContainerTag("span");

View

View are the core of this module, the mediator (views) is just a convenience. A new View is created every time you call views.create(). The create method expects a configuration object which contains the mandatory template property:

views.create({
    containerTag: "p" // override the default container tag (this is optional)
    template: {} // your template object, string, or whatever format is has
});

View instances have the following API:

• container: their HTML element container. All listeners are bound to this element. When rendering, you want to change the content of this element.
• render: a partial application of the View.prototype.render() method. It automatically provides the view's template object, so you only need to provide the data object to the render() method.
• addListener: wrapper around the element.addEventListener() DOM method, which also registers the listener into the view's cache, allowing the view to remove it in the future. (such as with die()). This method also returns a removeListener() method, which allows you to remove the listener you just created.
• removeListeners: removes all listeners that you have added with the method addListener()

View.prototype

The View prototype has a few additional methods that are available to all views.

• attach(target): appends the view.container to a target HTML element, such as: myView.attach(document.getElementById("myEl"));
• detach(): removes the view container from it's parent element (where it was attached).
• clear(): removes all current markup inside container. (essentially a convenience around myViewcontainer.innerHTML = "";)
• die(): removes all listeners bound to the view, and removes it from the DOM.

All View.prototype methods return "this", allowing you to chain methods, such as:

views.create({
   template: "<li>{{value}}</li>",
   containerTag: "ul"
}).attach(document.getElementById("someId")).render({value:"this is a line"});