A jQuery plugin for templating static HTML
JavaScript CoffeeScript
Permalink
Failed to load latest commit information.
development
log
.gitignore
.jshintrc
.travis.yml
Gruntfile.coffee
README.md
bower.json
jquery.tempura.js
jquery.tempura.min.js
package.json
tempura.jquery.json
testem.json

README.md

jQuery Tempura Build Status

A jQuery plugin for templating static HTML.
It thinks important the templating that is utilizing the characteristic of the HTML material.

In the same way you would make a delicious 🍤 Tempura 🍤

Features

  • Can use with keeping original HTML
    • It also means to be able to use something together with other templating engines.
  • Can overwrite only a necessary part of the whole
    • Not destroy event handlers.
    • It's high speed compared with to overwrite template wholly in many cases.
  • Easy to use
    • Can write easily processing that is used commonly.
    • .. but, I am giving up it in complex case. In this case, you must write by using raw jQuery.

Download

Or, if you can use bower:

$ bower install jquery.tempura

Supported browsers

  • IE10, IE9, IE8, IE7
  • Chrome
  • Firefox
  • Safari
  • Mobile Safari
  • PhantomJS

Supported jQuery versions

  • 1.10.2
  • 1.9.1
  • 1.8.3
  • 2.0.3

License

MIT License

Installation

<script src="path/to/jquery.js"></script>
<script src="path/to/jquery.tempura.js"></script>

Examples

1. Basic rendering

Before:

<div class="welcome-page">
  <h1 data-bind="title">Title</h1>
  <p data-bind="contents">Contents</p>
  <p data-bind="footer">Footer</p>
</div>

<script>
$(".welcome-page").tempura({
  title: "Changed Title",
  contents: "Changed contents"
});
</script>

After:

<div class="welcome-page">
  <h1 data-bind="title">Changed Title</h1>
  <p data-bind="contents">Changed contents</p>
  <p data-bind="footer">Footer</p>
</div>
  • The setting data-bind="dataKey" node is rendered by $(selector).tempura({ dataKey:".." }).
  • string or number values changes node by $node.text(value).
  • If you don't assign data to binded node, then the node is not effected.

2. Change visiblity

Before:

<div class="welcome-page">
  <h1 data-bind="title">Title</h1>
  <p data-bind="contents">Contents</p>
</div>

<script>
$(".welcome-page").tempura({
  contents: false
});
</script>

After:

<div class="welcome-page">
  <h1 data-bind="title">Title</h1>
  <p data-bind="contents" style="display:none;">Contents</p>
</div>
  • true means $node.show(), false means $node.hide().

3. Change binded node as a jQuery object

Before:

<div class="login-page">
  <a data-bind="loginLink" href="#">Logged in</a>
</div>

<script>
$(".login-page").tempura({
  loginLink: {
    css: { fontSize:12, textAlign:"center" },
    attr: ["href", "/login"],
    addClass: "link-style",
    text: "Logged in, hurry!"
  }
});
</script>

After:

<div class="login-page">
  <a data-bind="login-link" href="/login"
    style="font-size:12px; text-align:center;"
    class="link-style">Logged in, hurry!</a>
</div>
  • A {}(Plain Object) changes the node as a jQeury object.
  • The format is { methodName: args, methodName2: args2, .. }.
    • The args besides Array is passed to method as a single arg.
    • If args is Array, then they are passed to method as plural args.

4. Render HTML

Before:

<div class="some-page">
  <div data-bind="parent"><p>Child</p></div>
</div>

<script>
$(".some-page").tempura({
  parent: $('<p>').text("New child")
});
</script>

After:

<div class="some-page">
  <div data-bind="parent"><p>New child</p></div>
</div>
  • $jQueryObject replaces child nodes.
    • It works to equal $node.empty().append($jQueryObject).
  • To be exact, there is no way to write the HTML.

5. Append nodes

Before:

<div class="some-page">
  <div data-bind="byJQuery"></div>
  <div data-bind="byArray"></div>
</div>

<script>
$(".some-page").tempura({
  byJQuery: $('<p>1</p><p>2</p>').filter('*'),
  byArray: [
    $('<p>').text("A"),
    $('<p>').text("B")
  ]
});
</script>

After:

<div class="some-page">
  <div data-bind="byJQuery"><p>1</p><p>2</p></div>
  <div data-bind="byArray"><p>A</p><p>B</p></div>
</div>
  • $jQueryQuerySet replaces child nodes the same as the rendering HTML.
  • Also Array is parsed like it.

6. Dynamic evaluation

Before:

<div class="some-page">
  <span data-bind="timer"></span>
</div>

<script>
$(".some-page").tempura({
  timer: function(){
    return new Date();
  }
});
</script>

After:

<div class="some-page">
  <span data-bind="timer">Fri Aug 02 2013 21:55:40 GMT+0900 (JST)</span>
</div>
  • Function is evaluated every rendering.
  • this in the function is binded to $node.

7. Not rendering

Before:

<div class="some-page">
  <span data-bind="greeting">Hello, guest!</span>
</div>

<script>
$(".some-page").tempura({
  greeting: function(){
    if (!isLoggedIn) return;
    return "Hello, member!";
  }
});
</script>
  • undefined or null are passing through the rendering.

8. Complex cases

Before:

<div class="some-page">
  <ul data-bind="members"></ul>
</div>

<script>
var members = [
  { id: 1, name: "Taro" },
  { id: 2, name: "Jiro" },
  { id: 3, name: "Saburo" }
];
$(".some-page").tempura({
  members: function(){
    if (members.length === 0) return false;

    this.empty();
    $that = this;
    $.each(members, function(i, member){
      $that.append(
        $('<li>').text(member.name + ":" + member.id);
      );
    });
  }
});
</script>

After:

<div class="some-page">
  <ul data-bind="members">
    <li>Taro:1</li>
    <li>Jiro:2</li>
    <li>Saburo:3</li>
  </ul>
</div>
  • Sorry, this is a weak case 😣
  • How the custom filter might help you.

9. :ignored built-in value

<div class="layout">
  <span data-bind="foo">1</span>
  <div class="partial" data-bind=":ignored">
    <span data-bind="bar">2</span>
  </div>
</div>

<script>
$(".layout").tempura({
  foo: 11,  // Update
  bar: 22   // Not update
});
$(".partial").tempura({
  bar: 22 // Update
});
</script>
  • :ignored protects childrens from unwanted update by outside.

10. Register a custom filter

Before:

<script>
$().tempura("filter", "lower", function(str){
  return str.toLowerCase();
});
</script>

<div class="some-page">
  <h1 data-bind="title">TITLE</h1>
</div>

<script>
$(".some-page").tempura({
  title: function(misc, filters){
    return filters.lower(this.text());
  }
});
</script>

After:

<div class="some-page">
  <h1 data-bind="title">title</h1>
</div>
  • There are already some built-in filters.
  • By the way, the misc variable contains some informations too.

11. Change configrations

$().tempura("config", {
  bindingKey: "data-value",
  quiet: false
});
  • bindingKey (default="data-bind"): A HTML attribute name for data binding.
  • quiet (default=true): A on/off flag for throwing a error when you have a misuse probably.

Development

Dependencies

  • node.js >= 0.11.0, e.g. brew install node
  • PhantomJS, e.g. brew install phantomjs
$ npm install -g grunt-cli

Deploy

$ git clone git@github.com:kjirou/jquery.tempura.git
$ cd jquery.tempura
$ npm install

Util commands

  • grunt jshint validates codes by JSHint.
  • grunt release generates JavaScript files for release.

Testing

  • Open development/index.html
  • Or, execute npm run testem and open http://localhost:7357/
  • grunt test is CI test by PhantomJS only.
  • grunt testem:xb is CI test by PhantomJS, Chrome, Firefox and Safari.
  • grunt testall executes XB test for each all supported jQuery versions.

Related Links