Contemplate
Light-weight, fast and flexible "object-oriented" template engine for PHP, Python, Node.js, Browser client-side and XPCOM JavaScript
Contemplate.js, Contemplate.min.js
Meaning of Yoga in Indian Philosophy (wikipedia) ("unifying through yoga, contemplate and attain mastery")
see also:
- HtmlWidget html widgets used as (template) plugins and/or standalone for PHP, Python, Node.js / Browser / XPCOM Javascript both client and server-side (can be used as plugins for Contemplate)
- Tao A simple, tiny, isomorphic, precise and fast template engine for handling both string and live dom based templates
- ModelView a light-weight and flexible MVVM framework for JavaScript/HTML5
- ModelView MVC jQueryUI Widgets plug-n-play, state-full, full-MVC widgets for jQueryUI using modelview.js (e.g calendars, datepickers, colorpickers, tables/grids, etc..) (in progress)
- Importer simple class & dependency manager and loader for PHP, Python, Node.js / Browser / XPCOM Javascript
- PublishSubscribe a simple and flexible publish-subscribe pattern implementation for PHP, Python, Node.js / Browser / XPCOM Javascript
- Dromeo a flexible, and powerfull agnostic router for PHP, Python, Node.js / Browser / XPCOM Javascript
- Dialect a simple cross-vendor & cross-platform SQL construction for PHP, Python, Node.js / Browser / XPCOM Javascript
- Xpresion a simple and flexible eXpression parser engine (with custom functions and variables support) for PHP, Python, Node.js / Browser / XPCOM Javascript
- GrammarTemplate versatile and intuitive grammar-based templating for PHP, Python, Node.js / Browser / XPCOM Javascript
- GrammarPattern versatile grammar-based pattern-matching for Node / XPCOM / JS (IN PROGRESS)
- Regex Analyzer/Composer Regular Expression Analyzer and Composer for PHP, Python, Node.js / Browser / XPCOM Javascript
- DateX eXtended & localised Date parsing, diffing, formatting and validation for PHP, Python, Node.js / Browser / XPCOM Javascript
- Abacus a fast combinatorics and computation library for PHP, Python, Node.js / Browser / XPCOM Javascript
- RT client-side real-time communication for Node/XPCOM/JS with support for Poll / BOSH / WebSockets
- Asynchronous a simple manager for async, linearised, parallelised, interleaved and sequential tasks for JavaScript
This started as a a proof-of-concept but developed into a full-blown and versatile template engine.
The original inspiration came from an old post by John Resig (http://ejohn.org/blog/javascript-micro-templating/)
Note
There are a couple of other frameworks named also contemplate
- http://www.arlomedia.com/software/contemplate/assembled/introduction.html
- There is an older and quite different template engine for
node
named also"contemplate"
here and here
This repository and project is completely unrelated to these frameworks.
Contents
- Online Playground Example
- Rationale
- Features
- API Reference
- Dependencies
- Changelog
- Todo
- Performance
- Tests
- Examples/Screenshots
If you use Contemplate
in your application and you want to share it, feel free to submit an example link
Rationale
There are many templating engines out there, which are elegant, fast, multipurpose and so on.. Most of the sophisticated engines use a custom parser (and usually a full-fledged framework) to build the engine.
This is highly versatile:
-
but can have performance issues sometimes
-
and / or requires to learn a (completely) new syntax for building a template.
These drawbacks can be compensated if one uses PHP
itself as templating engine. PHP
already IS a templating language and a very fast at it.
This can create very simple, intuitive and fast templates.
The drawbacks of this approach are:
-
It works only with
PHP
, and many times the same template needs to be used also byJavaScript
-
It can be cumbersome to combine or iterate over templates and parts.
Contemplate
seeks to find the best balance between these requirements.
The solution is inspired by John Resig's post (see above) and the fact that PHP
, Python
and JavaScript
share a common language subset.
Features:
-
Contemplate
does a minimum parsing (and caching) in order to create dynamic templates and trying to contain the needed functionality inside the common language subset(s). -
Most of the time this can be accomplished, the rest functionality is built with custom functions which mostly resemble the
PHP
syntax, yet work the same in all the engine's implementations. -
Uniform functionality, Engine Implementations for PHP , Python , Node.js , XPCOM and Browser client-side JavaScript (NOTE
javascript
engine supports both sync and async operations both callback-based and promise-based) -
Simple and light-weight ( only one relatively small class for each implementation, no other dependencies )
~50kB
minified,~16kB
zipped -
Fast , can cache templates dynamically (filesystem caching has 3 modes,
NONE
which uses only in-memory caching,NOUPDATE
which caches the templates only once andAUTOUPDATE
which re-creates the cached template if original template has changed, useful for debugging) -
Generated cached template code is formatted and annotated with comments, for easy debugging (note:
javascript
cached templates areUMD
modules which can be used in bothnode.js
/AMD
/XPCOM
/browser
/es6 module fallback
) -
Syntax close to
PHP
(there was an effort to keep the engine syntax as close toPHP
syntax as possible, to avoid learning another language syntax) -
Easily extensible , configurable
-
Object-oriented , templates implement inheritance and polymorphism in a full object-oriented manner (see below)
-
Supports multiple dynamic contexts , and contextual settings so that different modules of an application can use the engine independantly (see examples and manual)
-
Localization , Pluralisation , Date formatting built-in and configurable easily ( simple Data escaping is also supported)
-
X-GetText
/POEdit
translation-friendly localisation (keywords:locale
,xlocale:1,2c
,nlocale:2
,nlocale:3
,nxlocale:2,4c
,nxlocale:3,4c
) -
Date manipulation similar to
PHP
format (iedate
function). An extended, localized version ofphp
's date functionldate
is also implemented in the framework -
Loops can have optional
elsefor
statement when no data, or data is empty (see tests) -
Templates can
include
other templates (similar toPHP
include
directive), these includes wil be compiled into the the template that called them -
Templates can call another template using
tpl
function, these templates are called as templates subroutines and parsed by themselves -
Templates and template functions can also have inline templates as parameters via
inline
template function -
Template Inheritance , templates can extend/inherit other templates using
extends
directive and override blocks usingblock
,endblock
directives (see examples) -
Direct Super reference , templates can use the
super
template function to directly reference (and call) a super block if needed in OO manner (see examples) -
Nested Blocks , template
blocks
can be nested and repeated in multiple ways (see examples) -
Custom Plugins , can be used as template functions to enhance/extend the engine functionality (see examples)
-
custom plugins can be also inlined, i.e their code can be expanded at compile-time using
Contemplate::inline
templates in their definition, e.g saving unnecessary look-ups at render-time (see examples)
Dependencies
- Only 3 classes are used (
Contemplate.php
,Contemplate.js
,Contemplate.py
), no other dependencies PHP
5.2+
supportedNode
0.8+
supportedPython
2.x
or3.x
supported- all browsers
Contemplate
is also aXPCOM JavaScript Component
(Firefox) (e.g to be used in firefox browser addons/plugins for templating)
Todo
- add support for multiple
contexts
(which include separatetemplates
,cache
directories and related parameters) so that the engine can be used in same application by different modules independantly [DONE] - simplify template
directives
,functions
andplugins
notation by eliminating the%
prefix (compatibility mode to older versions also supported) [DONE] - support asynchronous template loading/parsing/rendering/writing for
node/browser
[DONE] - add
Contemplate
implementations forActionScript, Perl, Java, Scala
[TODO?] - transform
Contemplate
(forPHP
) into aPHP
C
-extension,Contemplate
(for node) into standalone executable (eg. https://github.com/crcn/nexe) [TODO?] - keep-up with
php
,node
,python
, browsers updates
Performance
(for php
see /tests/perf/perf.php
)
Note: The engines included in the (following) tests, have different philosophy and in general provide different features. These are only illustrative modulo all the other features.
Render Time
The following tests were made on a revision of a 2013 jsperf test for resig micro-templating
, handlebars
, contemplate
, mustache
, underscore
, doT
and kendoui
template engines. More tests should be done.
Contemplate
(0.6.5
) was 2nd place on Firefox and 3rd (or close) place on Opera, IE, while Contemplate
was average to slower on Chrome. The reason was mostly that Contemplate
was using a code to copy/isolate the input data every time inside the render function, which most of the time is redundant, else user can use the Contemplate.data
method to create a shallow copy suitable to be used as render data. So this was removed, plus some minor refactoring and minor loop optimisation.
This resulted in great performance increase as shown below. (see changelog)
Previous tests are here jsperf/0.6.5, jsperf/0.6.7, jsperf/0.7, jsperf/0.7.1, jsperf/0.8, jsperf/0.8.1, jsperf/1.0.0, jsperf/1.0.0 (1.0.0+ format)
Contemplate
(1.0.0
) is (consistently) near 1st place on all browsers.
Parse / Compilation Time
The following tests involve swig
, handlebars
, contemplate
and mustache
template engines. More tests should be done.
Previous tests are here jsperf/0.6.7, jsperf/0.7, jsperf/0.7.1, jsperf/0.8, jsperf/0.8.1, jsperf/1.0.0
Contemplate
(1.0.0
) is (consistently) 1st place on all browsers.
Tests
Use test.php
(for php
), test.js
(for node
), test.py
(for python
)
under /tests
folder, to test the basic functionality
Screenshots
Data to be used for the template
PHP
and JavaScript
rendering of the template on same page (see test.php
)