Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/leonidas/transparency
Transparency is a semantic template engine for the browser. It maps JSON objects to DOM elements by id, class and data-bind attributes.
https://github.com/leonidas/transparency
Last synced: 18 days ago
JSON representation
Transparency is a semantic template engine for the browser. It maps JSON objects to DOM elements by id, class and data-bind attributes.
- Host: GitHub
- URL: https://github.com/leonidas/transparency
- Owner: leonidas
- License: mit
- Created: 2012-01-13T15:25:01.000Z (almost 13 years ago)
- Default Branch: master
- Last Pushed: 2020-04-29T22:42:40.000Z (over 4 years ago)
- Last Synced: 2024-04-15T13:57:00.826Z (7 months ago)
- Language: JavaScript
- Homepage: http://leonidas.github.com/transparency/
- Size: 2.43 MB
- Stars: 972
- Watchers: 46
- Forks: 112
- Open Issues: 48
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Synopsis
Transparency is a client-side template engine which binds data to DOM. Just call `.render(data)`.
```html
```
```js
var hello = {
greeting: 'Hello',
name: 'world!'
};
$('#template').render(hello);
```
```html
Hello
world!
```
[](http://travis-ci.org/leonidas/transparency)
## Features
* **Semantic data binding** - No need for `<%=foo%>` or `{{foo}}` assignments
* **Collection rendering** - No need for hand-written loops
* **Valid HTML templates** - Write templates as a part of the HTML, in plain HTML
* **View logic in JavaScript** - No crippled micro-template language, just plain JavaScript functions
Transparency is compatible with IE9+, Chrome, Firefox, iOS, Android and other mobile browsers. Support for IE8 requires jQuery.
## Community
* IRC: [freenode/#transparency.js](http://webchat.freenode.net/)
* Google Groups: [email protected]
**We are looking for new maintainers**. Anyone with an accepted pull request will get commit rights. Current maintainers are
* [pyykkis](https://github.com/pyykkis)
* [rikukissa](https://github.com/rikukissa)
## Fiddle
[Try Transparency](http://leonidas.github.com/transparency/) with interactive examples.
## Install
```
curl https://raw.github.com/leonidas/transparency/master/dist/transparency.min.js
# Or with Bower
npm install -g bower
bower install transparency
```
#### Require with script tags
```html
```
#### or with AMD
```javascript
require(['jquery', 'transparency'], function($, Transparency) {
// Without jQuery
Transparency.render(document.getElementById('template'), data);
// With jQuery
jQuery.fn.render = Transparency.jQueryPlugin;
$('#template').render(data);
});
```
#### Node.js
`npm install transparency`
For server-side use, see
[examples/hello-server](https://github.com/leonidas/transparency/tree/master/examples/hello-server).
## API documentation
Here are short and detailed examples how to use Transparency. For more elaborate examples, see
[User manual](https://github.com/leonidas/transparency/wiki/User-Manual) and
[FAQ](https://github.com/leonidas/transparency/wiki/Frequently-Asked-Questions).
Feel free to add your own examples in the wiki, too!
Implementation details are explained in the
[annotated source code](http://leonidas.github.com/transparency/docs/transparency.html).
### Binding values
Transparency binds values in-place. That means, you don't need to write separate template sections on your page.
Instead, compose just a normal, static html page and start binding some dynamic values on it!
By default, Transparency binds JavaScript objects to a DOM element by `id`, `class`,`name` attribute and
`data-bind` attribute. Default behavior can be changed by providing a custom matcher function, as explained in section
[Configuration](https://github.com/leonidas/transparency#configuration). Values are escaped before rendering.
Template:
```html
```
Javascript:
```js
var hello = {
hello: 'Hello',
goodbye: 'Goodbye!',
greeting: 'Howdy!',
'hi-label': 'Terve!' // Finnish i18n
};
// with jQuery
$('#container').render(hello);
// ..or without
Transparency.render(document.getElementById('container'), hello);
```
Result:
```html
Hello
lt;i>Goodbye!</i>
Terve!
```
### Rendering a list of models
Template:
```html
```
Javascript:
```js
var activities = [
{activity: 'Jogging'},
{activity: 'Gym'},
{activity: 'Sky Diving'},
];
$('#activities').render(activities);
// or
Transparency.render(document.getElementById('activities'), activities);
```
Result:
```html
- Jogging
- Gym
- Sky Diving
```
#### Rendering a list of plain values
With plain values, Transparency can't guess how you would like to bind the data to DOM, so a bit of
help is needed. Directives are just for that.
Access to the plain values within the directives is provided through `this.value`. There's a whole
lot more to say about the directives, but that's all we need for now. For the details, see
section [Directives](https://github.com/leonidas/transparency#directives).
Template:
```html
```
Javascript:
```js
var comments, directives;
comments = ["That rules", "Great post!"];
// See section 'Directives' for the details
directives = {
comment: {
text: function() {
return this.value;
}
}
};
$('.comments').render(comments, directives);
```
Result:
```html
CommentsThat rules
CommentsGreat post!
```
### Nested lists
Template:
```html
```
Javascript:
```js
var post = {
title: 'Hello World',
post: 'Hi there it is me',
comments: [ {
name: 'John',
text: 'That rules'
}, {
name: 'Arnold',
text: 'Great post!'
}
]
};
$('.container').render(post);
```
Result:
```html
Hello World
Hi there it is me
John
That rules
Arnold
Great post!
```
### Nested objects
Template:
```html
```
Javascript:
```js
var person = {
firstname: 'John',
lastname: 'Wayne',
address: {
street: '4th Street',
city: 'San Francisco',
zip: '94199'
}
};
$('.person').render(person);
```
Result:
```html
```
### Directives
Directives are actions Transparency performs while rendering the templates. They can be used for setting element
`text` or `html` content and attribute values, e.g., `class`, `src` or `href`.
Directives are plain javascript functions defined in a two-dimensional object literal, i.e.,
`directives[element][attribute] = function(params) {...}`
where `element` is value of `id`, `class`, `name` attribute or `data-bind` attribute of the target element. Similarly,
`attribute` is the name of the target attribute.
When a directive function is executed, `this` is bound to the current model object. In addition, the directive function
receives current element as `params.element`, current index as `params.index` and current value as `params.value`.
The return value of a directive function is assigned to the matching element attribute. The return value should be
string, number or date.
Template:
```html
```
Javascript:
```js
var person, directives;
person = {
firstname: 'Jasmine',
lastname: 'Taylor',
email: '[email protected]'
};
directives = {
name: {
text: function(params) {
return params.value + this.firstname + " " + this.lastname;
}
},
email: {
href: function(params) {
return "mailto:" + this.email;
}
}
};
$('.person').render(person, directives);
```
Result:
```html
```
### Nested directives
Template:
```html
```
Javascript:
```js
person = {
firstname: 'Jasmine',
lastname: 'Taylor',
email: '[email protected]',
friends: [ {
firstname: 'John',
lastname: 'Mayer',
email: '[email protected]'
}, {
firstname: 'Damien',
lastname: 'Rice',
email: '[email protected]'
}
]
};
nameDecorator = function() { "" + this.firstname + " " + this.lastname + ""; };
directives = {
name: { html: nameDecorator },
friends: {
name: { html: nameDecorator }
}
};
$('.person').render(person, directives);
```
Result:
```html
```
## Configuration
Transparency can be configured to use custom matcher for binding the values to DOM elements.
For example, one might want to bind only with `data-bind` attribute, but not with `class` or `id` attributes.
Custom matcher function should take `key` and `element` as parameters and return `true` if the
corresponding value should be bind to the given DOM element.
```javascript
// The custom matcher gets Transparency `Element` wrapper with following properties
// element.el: Raw DOM element
// element.name: Lower-cased name of the DOM element, e.g., 'input'
// element.classNames: List of class names of the DOM element, e.g., ['person', 'selected']
Transparency.matcher = function(element, key) {
return element.el.getAttribute('data-bind') == key;
};
// Values are bind only with 'data-bind' attribute
template.render({name: "Will Smith"});
```
## Debugging templates, data and Transparency
http://leonidas.github.com/transparency/ is great place to fiddle around with your data and templates.
To enable debug mode, call `.render` with a `{debug: true}` config and open the javascript console.
```javascript
$('container').render(data, {}, {debug: true});
```
## Development environment
Install node.js 0.8.x and npm. Then, in the project folder
$ npm install grunt -g # command-line build tool to enable TDD, auto-complation and minification
$ npm install # Install the development dependencies
$ grunt # Compile, run tests, minify and start watching for modifications
The [annotated source code](http://leonidas.github.com/transparency/docs/transparency.html) should
give a decent introduction.
## Contributing
All the following are appreciated, in an asceding order of preference
1. A feature request or a bug report
2. Pull request with a failing unit test
3. Pull request with unit tests and corresponding implementation
In case the contribution is changing Transparency API, please create a ticket first in order to discuss and
agree on design.
Comments: