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
Node
npm install viewful
Usage
Views can render strings
viewful.View
using a string of Jade
Here is a simple var viewful = ;var view =template: "p= user.name"input: "jade";view;
outputs:
bob
viewful.View
using a string of Swig
Here is a simple var viewful = ;var view =template: '<p>{{user.name}}</p>'input: "swig";view;
outputs:
bob
Views can be loaded from disk
like this
Assuming there a view on the hard-disk,- view
- creature
- create.jade
- inputs
- button.jade
- button.js
- creature
Viewful can automatically handle the process of loading template files through the View.load
method.
var 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
method after the View has been constructed
Templates are loaded using the view;
This same operation can also be performed asynchronously
viewful;
View.render
.
Once the view is loaded, it can be rendered using var html = viewcreaturecreate;
outputs:
Marak
var html = viewcreatureinputsbutton;
outputs:
cool
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.
Presenter Example: Click a Button to trigger Alert
Assuming there a view on the hard-disk, like this
- inputs
- button.html
- button.js
button.html
using swig for this example, but it could be any engine
{{label}}
var view = input: "swig" path: "./examples/jade/view/creature/inputs"; // load the viewview; // render the viewviewinputsbutton;
button.js
module { // Remark: We get a querySelectorAll poly-fill for free! var $ = this$; }
outputs:
Show Alert
// present the View, triggering event bindingsviewinputsbutton;
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
viewful.View
Class
View.template
Template for the view. In this case, p= user.name
View.render(data)
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.
View.load(/* callback */)
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(data)
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.
options
options.path
- String - Path to where your view is located
options.template
- String - Template for View
options.input
- String - Input templating engine. Defaults to
HTML
options.output
- String - Output templating engine. Defaults to
HTML
options.render
- Function - Override default rendering method for View
options.present
- 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().