viewful

Overview

viewful - tiny and consolidated view engine for JavaScript

Overview

  • Viewful establishes the minimal amount of convention needed to create JavaScript views.
  • Viewful makes no assumptions about your application or templating choices.

Features

  • Supports all templating engines available for JavaScript
  • Seamless loading and mapping of views from the file-system or remote webserver
  • Views can be infinitely nested, i.e. uber-partials / subviews
  • Views contain a very basic Presenter Pattern for assisting in building rich isomorprhic interfaces with graceful no-script fallbacks ( Presenters are more convention than code )

Installation

npm install viewful

Usage

Here is a simple viewful.View using a string of Jade

 
var viewful = require('viewful');
 
var view = new viewful.View({ 
  template: "p= user.name",
  input: "jade" 
});
 
view.render({ user: { name: "bob" }});
 

outputs:

<p>bob</p>

Here is a simple viewful.View using a string of Swig

 
var viewful = require('viewful');
 
var view = new viewful.View({ 
  template: '<p>{{user.name}}</p>',
  input: "swig"
});
 
view.render({ user: { name: "bob" }});

outputs:

<p>bob</p>

Assuming there a view on the hard-disk, like this

  • view
    • creature
      • create.jade
      • inputs
        • button.jade
        • button.js

Viewful can automatically handle the process of loading template files through the View.load method.

var view = new viewful.View({
  path: "./examples/jade/view",
  input: "jade",
  output: "html"
});

Important: By design, a View will not automatically attempt to load template assets on construction.

view.load();
viewful.load(function (errview) {
  console.log(view);
});
var html = view.creature.create.render({ user: { name: "Marak" }});

outputs:

<p>Marak</p>
var html = view.creature.inputs.button.render({ label: "cool" }});

outputs:

<div>
  <button id="thebutton">cool</button>
</div>

View Presenters

A Presenter can be considered a function which performs actions on a rendered template. In simple use-cases, you will not write a presenter.

In Level 1 DOM rendering ( such as generating server-side HTML to return to the client ), you will not use a Presenter. In more advanced use-cases, such as creating rich user-interfaces, you will want to create a Presenter to act upon your View.

Presenters are particularly important when implementing data-binding, browser events ( such as mouse and keyboard ), or graceful no-script compatible fallbacks for complex interfaces.

TL:DR; View Presenters are advantageous, but not mandatory.

Assuming there a view on the hard-disk, like this

  • inputs
  • button.html
  • button.js

using swig for this example, but it could be any engine

<div>
  <button id="thebutton">{{label}}</button>
</div>
var view = new viewful.View({
  input: "swig",
  path: "./examples/jade/view/creature/inputs",
});
 
// load the view 
view.load();
 
// render the view 
view.inputs.button.render({ label: "Show Alert" });
module.exports = function (optionscallback) {
  // Remark: We get a querySelectorAll poly-fill for free! 
  var $ = this.$;
  $('#thebutton').click(function(){
    alert('I am alert!');
  })
}

outputs:

<div>
  <button id="thebutton">Show Alert</button>
</div>
// present the View, triggering event bindings 
view.inputs.button.present();

If DOM Level 2 Events are available ( such as a browser ! ), the presenter will apply the click event to the button that triggers an alert when the button is clicked.

API

Template for the view. In this case, p= user.name

The render method for the view. Will use input and output templating engines.

Note: Based on the templating engine, there might be several other rendering API options available, such as callbacks or streaming.

A helper method for loading views from a file or a folder, synchronously or asynchronously, on the browser or the server. View.load is optional if a template string has already been specified in the View constructor.

View.present is intended to be called on the results of a template rendered with View.render(). In the presenter, you can bind Level 2 DOM Events (like a mouse click) to the rendered markup. In simple use-cases, you will not use this method.

  • String - Path to where your view is located
  • String - Template for View
  • String - Input templating engine. Defaults to HTML
  • String - Output templating engine. Defaults to HTML
  • Function - Override default rendering method for View
  • Function - Override default presenter method for View

TODO

  • Add isomorphic browser support
  • Improve documentation and examples
  • Create viewful Flatiron plugin
  • Add tests to verify that options are being passed into template engine render function correctly.
  • Add options as optional parameter of View.render(). Currently, template engine plugins can only be configured with options at app.attach().