A simple way to execute javascript functions and transform+display json data within HTML.
- You need an easy way to display json data in html.
- You would prefer inline document templates with simple syntax that can be parsed using standard HTML5 grammar (unlike mustache+handlebars, jade, etc.)
- You plan to write the bulk of your application in javascript. You simply want an obvious way to call that javascript code within the html.
- You loathe code sprawl and believe that embedding simple transformational display logic within html5 elements is the most maintainable code pattern for web applications.
- You might be a Single Page App developer with an SEO problem -- so you need to use the same templates on both server (for google SEO) and browser/app (for humans). Combine TLC with an isomorphic javascript framework (like IsoMagic) to use the recycle 100% of your display logic.
- You might be "The Programmer" in a tribe of non-coding web-monkeys -- so allowing co-workers to be able to easily preview+test HTML layout and style changes without needing to bother you, or needing any special server environment is really attractive.
- You'd like to be a more productive javascript developer with a minimal investment of time.
- Unlike most other template engines -- TLC is stored as INLINE HTML5 and will render+debug perfectly in any HTML5 editor. Designers create HTML syntax pre-populated with Lorem Ipsum that is hidden or replaced with real data when executed.
- TLC uses shell --script --syntax, core syntax is designed for readability/maintainability. It easily iterates over json data with loops and stuff too.
- Unlike javascript, TLC syntax fits nicely in HTML attributes- it avoids using quotes for clean legible code and fewer typos. Modules still run as trusted code, but are operate with less context.
- TLC is Lightweight + Extensible, you add your own functions (with javascript) and then call them with --parameters.
- TLC is packaged for use with ExpressJS, so TLC display logic can run server side or on the browser (great for SEO of single page apps)
- Friendly with modules like JQuery.
<h1 data-tlc="command --parameter; othercommand --with=$variable">Hello!</h1>
//Include the tlc.js file from this repo in your html file
var tlc = new TLC();
tlc.run($('#someElement'), {'message':'Hello World'});in your html:
<div id="someElement">
<h1 data-tlc="bind $var '.message'; apply --append;"></h1>
</div>Outputs
<div id="someElement">
<h1 data-tlc="bind $var '.message'; apply --append;">Hello World</h1>
</div>var express = require('express');
var app = express();
var http = require('http');
var fs = require('fs');
var TLC = require('tlc');
var tlc = new TLC();
var cheerio = require('cheerio); // jQuery-alike library for DOM parsing
app.get('/', function(req,res,next){
var $document = fs.readFileSync('index.html', 'utf-8);
tlc.run($document, { "message" : "Hello World" });
res.send($document.html());
});
http.createServer(app).listen(3000);the contents of index.html:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>test</title>
</head>
<body>
<!--
note here '.message' is the JSONPath string to
a member of the JSON object being translated
-->
<h1 data-tlc="bind $msg '.message'; apply --append=$msg;"></h1>
</body>
</html>When running the app, localhost:3000 will serve
The above example introduces 2 of the core commands in tlc, bind and apply. Commands are functions, executed with arguments, within a context.
Each tag creates a new context, and before any commands are executed, it consists solely of the JSON data object being translated.
bind is one of the most important commands in tlc- it creates+links a variable within the tlc's context to a component of a JSON data object. For example: bind $msg '.message'; from above create's the variable $msg, and writes "Hello World" to it from the JSON object.
This command takes 2 arguments- first, a variable reference to bind into, and second, a JSONPath formatted string to reference the binding.
Our second command, apply --append=$msg;, de-reference's our variable $msg. The apply command is used for applying
changes to the tag we are executing commands on, in this case, appending to it.
Note that we can shorten our tlc statement to bind $msg '.message'; apply --append; and it will still apply the contents of the msg variable.
This is because by binding it, msg has become the focus variable. All core commands will use the focus variable if none is provided. This
is both for syntactic convenience, and also to allow simple chaining on the focus variable, for example, if we were rendering a VERY
simple product page:
var productData = {
"name" : "pie"
"price" : "3.14"
}
<div class="price" data-tlc="
bind $cents '.price';
math --mult='100' --mod='100';
bind $dollars '.price';
math --precision='0';
format --prepend='$' --append='.';
focus $cents;
format --prepend='<span class=cents>' --append='</span>';
apply --append=$dollars;
apply --append=$cents;
"</div>
Holy new commands, batman! A few things to note here:
math --mult='100' --mod='100';- Themathcommand parses its arguments sequentially, meaning that you can daisy chain a bunch of arithmetic together for convenience. Note, a few lines down,formatdoes the same thing.format --prepend='$' --append='.';- Theformatcommand allows you to format the focus variable before you append it to the tag. Note a few lines down- you can use format to add HTML content.focus $cents;- Thefocuscommand shifts the current focus variable, just likebind(andset), however it doesn't change the contents of the variable likebind(andset).apply --append=$dollars; apply --append=$cents;- Theapplycommand only takes one 'verb' at a time, currently. This may change in future versions of the core API, but for now, we can't daisy chain like math.
The full list of core commands:
bind: bind (and create) a variable to the JSON data objectset: set (and create) a variable to a scalar value;apply: apply a change to the tagformat: format the focus variabletlc: recursively call tlc for the contents of the tag. This is useful for when you have added tlc from within your tlc commands (yo dawg)stringify: set the focus variable to a stringified version of its current value;focus: set the focus to a different variable.math: perform arithmetic on the focus variabledatetime: set the focus variable to the current date.--out='pretty'or--out='mdy'formats are supported.is: used in conditionals (see below).
Modules allow developers to extend the command set usable in tlc:
var tlc = require('tlc');
var moduleObject = require('./mymodule.js');
tlc.addModule('mymodule',moduleObject);
This module can be referenced in templates:
<div data-tlc="bind $var '.some.var'; mymodule# --arg=$var; apply --append;"></div>
One module that is not-quite-core but you might find awfully useful is template
For more information, please visit the Module API
<div data-tlc="
bind $new '.user.is_new';
if(is $new --eq='1';){{
bind $user '.user';
template#translate --templateid='newUserWelcomeMessage' --data=$user;
}};
"></div>
<ul data-tlc="
bind $arr '.path.to.array';
foreach $item in $arr {{
template#translate --templateid='listItemTemplate' --data=$item;
apply --append;
}};
"></ul>