https://github.com/geraintluff/jstl
JavaScript templating
https://github.com/geraintluff/jstl
Last synced: 9 months ago
JSON representation
JavaScript templating
- Host: GitHub
- URL: https://github.com/geraintluff/jstl
- Owner: geraintluff
- Created: 2013-04-23T11:56:34.000Z (about 13 years ago)
- Default Branch: master
- Last Pushed: 2013-04-28T21:39:58.000Z (about 13 years ago)
- Last Synced: 2024-11-20T11:49:28.703Z (over 1 year ago)
- Language: JavaScript
- Size: 127 KB
- Stars: 3
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# jstl - JavaScript as a Templating Language
`jstl` is a templating library for JavaScript, *using* JavaScript.
Rather than trying to design a new language, `jstl` allows you to write JavaScript code for the control logic of your templates, while also providing a customisable "short form" for variable substitution.
`jstl` takes in a template, and produces a function. This function **includes JavaScript code from the template**, so it is basically equivalent to `eval()` - **DO NOT RUN TEMPLATES YOU DO NOT TRUST**.
Example code:
```html
Encrypted
Unencrypted
```
Everywhere `` can be used in place of `?>`).
## *Another* templating library?
Yeah, I know there are already quite a few. But they generally suffer from the following problems:
* **New syntax** - the more complex ones define their own syntax for `if`/`foreach`/etc.
* **Not customisable** - they give you a set of pre-defined output filters (HTML entities, URI encoding, etc).
`jstl` tries to avoid these, by piggybacking on the JavaScript language while providing a simple base for extending behaviour.
## Writing templates
There are two different ways to use the special tags in a template.
### 1) Simple substitution:`` or `<%variable%>`
If there is no space following the `
<%name%> likes <%food%>.
```
Calling the function:
```javascript
var obj = {name: "Everybody", food: "chocolate"};
var html = myTemplate(obj);
```
Result:
```html
Everybody likes chocolate.
```
### 2) JavaScript code: `` or `<% ... %>`
If there is whitespace following the opening `
Current URI:
```
Result:
```html
Current URI: http://example.com/
```
## Loading templates
Templates can be loaded either as strings (`jstl.create(str)`) or they can be loaded from C-style comments in your JS file, assuming that file is accessible via AJAX.
The syntax for loading from comments is to start your comment `/* Template: ` followed by a newline. To load all templates in a file, call `jstl.loadTemplates()` from that file.
Example:
```javascript
template = jstl.create('
').compile();
/* Template: example-template
*/
template2 = jstl.getTemplate('example-template').compile();
```
## Customising
Behaviour can be modified either by passing arguments into `template.compile()`, or by changing properties in the `jstl` object.
### The "no spaces" behaviour
You can completely customise the behaviour of the "no spaces" form.
The way you do this is by passing in a function to `t.compile()` of the following form:
```javascript
t.compile(function (variableName) {
return function (arg0, arg1, ...) {
...
}
});
```
You might need to look at that twice - you supply a compile-time function which returns a function that is called at render time.
For example, a simple example might be:
```javascript
var t = jstl.create('Name: <%name%>');
var f = t.compile(function (variableName) {
return function (value) {
return value[variableName].toString();
}
});
var value = {name: "Mary"};
var result = f(value); // returns: "Name: Mary"
```
The default function (that `t.compile()` uses if you don't supply your own) is available at `jstl.defaultFunction`. It looks very much like the above, except it HTML entity-encodes the output.
You can change this default by altering `jstl.defaultFunction`.
### "Header code"
You can also provide some JavaScript code to sit at the top of the compiled template. It's completely equivalent to adding the same code to the top of the template.
```javascript
var f = t.compile(null, "var value = arguments[0];");
```
A good use for this might be to alias function arguments (as in the example) - that makes the `value` variable available for use within your templates, so you don't have to pepper your code with `arguments[N]`.
The default "header code" is actually the one from above example - however, you can change this by altering `jstl.defaultHeaderCode`.
## Wait - how does it get the templates from JavaScript comments?
### In-browser
The secret is that when `jstl.getTemplate()` is called, it calls through to `jstl.loadTemplates()`. This function figures out what source file is running (it should be the last `` in the document), fetches it via AJAX and inspects it for comments.
If for some reason you aren't calling `jstl.getTemplate()` when the script loads (I can't think why you would), then you should call `jstl.loadTemplates()` manually, optionally including the URI of the source file containing templates.
### Using Node
Since the above AJAX trick doesn't work when running server-side, every script containing templates should call `jstl.loadTemplates(__filename)`, so the library can read the file and parse all templates from it.