About
dot-view
is an easy to use Node.js view class wrapper around the fast doT templating engine.
Features
- Supports layouts, partials and custom view helper functions
- Implements memory caching of compiled template functions (enabled by default)
- Basic Express integration with
__express()
ordisplay()
Installation
npm install dot-view
Usage
Quick start
Here are some basic usage examples that connect with the public API. Error handling has been left out for demonstrational purposes.
Init
var View = View;
Go!
template.dot
Test {{=it.greet}} world!
var html = '/tpl/path' 'template.dot' greet: 'Hello';// Orvar html = '/tpl/path' 'template.dot';
Re-use the view object for rendering multiple templates in the same path:
var view = '/tpl/path';var html1 = view;var html2 = view;
Layout
Add a layout to the template and assign variables to the layout. In layout.dot
the content of template.dot
is included with {{#def._content}}
.
var view = '/tpl/path' 'template.dot' greet: 'Hello!';view;var html = view;
layout.dot
could look like:
{{=it.title}} {{#def._content}}
It's also possible to define the layout from a template file. The default syntax is {{##def._layout:path/to/layout.dot#}}
or simply {{##_layout:path/to/layout.dot#}}
when you don't want it to end up in your defines
. Paths can be absolute or relative to the template file the layout is defined in.
template.dot
{{##def._layout:../layouts/layout.dot#}}Say {{=it.greet}}!
You can assign variables to the layout like this:
var view = '/tpl/path' 'template.dot' greet: 'hello';// The layout will be picked up automatically from template.dot when definedifview view;var html = view;
Like all doT
tags, you can change the format of the layout definition by altering its regular expression. For example, setting view.settings.layout
to /\{\{\s+\/\*\s*layout:\s*(.+\S+)\s*\*\/\s*\}\}/
will allow for the layout to be defined as comments {{ /* layout:path/to/layout.dot */ }}
.
Partials
In doT partials are included with #def
. To add literal partials or partials from other template files simply:
var view = '/tpl/path' 'template.dot' greet: 'Hello!';view;var html = view;
Where template.dot
could look like:
<!-- Output the file partial -->{{#def.file_partial}}<!-- Output the literal string partial -->{{#def.string_partial}}
It's also possible to include a sub-template directly from a template file. Paths can be absolute or relative to the template file def.include()
is called in.
{{#def.include('path/to/sub-template.dot')}}
See the doT
advanced examples for more information on how to use partials in doT
directly.
Helpers
dot-view
comes with two default view helpers truncate()
(truncate a string) and currency()
(format currency). Take a look at View.prototype.helpers
for their parameters. View helpers are located in the helpers
variable inside a template.
<!-- Truncate a string (it.someString) to 60 characters -->{{!helpers.truncate(it.someString, 60)}}
You can add your own helper functions by simply adding them to the helpers
property of your View
instance.
var view = '/tpl/path' 'template.dot' greet: 'hello';viewhelpers{ return 'Well '+greet+' there!'; };var html = view;
In your template.dot
{{!helpers.sayGreeting(it.greet)}}
Will output:
Well hello there!
Express
You can easily integrate dot-view
in your Express app in two ways.
__express()
dot-view
exposes an __express()
function that can be registered as the template engine for Express.
// Tell Express to use the dot-view engine for .dot templatesapp; app;
Passing a layout, partial and helper
var options = layout: '/layouts' 'layout.dot' title: 'My title' defines: partial: '<div>{{=it.greet}} I\'m a partial.</div>' helpers: { return 'Well '+greet+' there!'; } greet: 'hello';res;
display()
You can also bypass Express's template facilities completely and simply pass Express's res
to view.display()
along with an optional template file and optional HTTP status code.
app;
Reserved template variable names
The following object keys have a special meaning in dot-view
and should not be used for passing normal values or partials to templates:
- Anything that is assigned to
def.include
and is not a function will be overwritten by a function to include a sub-template from a file path - A partial with the name
def._content
is used by the layout view to include the content of the template - When using
def._layout
in a template to define the layout, this will act like a normaldefine
indoT
When passing variables in the options
parameter of res.render()
when using __express()
:
layout
is reserved for passing the layout template orView
instancedefines
is reserved for passing partialshelpers
is reserved for passing additional view helperscache
is reserved for enabling/disabling the template function cache
Resources
License
MIT