Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kjirou/jquery.tempura

A jQuery plugin for templating static HTML
https://github.com/kjirou/jquery.tempura

Last synced: 12 days ago
JSON representation

A jQuery plugin for templating static HTML

Awesome Lists containing this project

README 

        
jQuery Tempura [![Build Status](https://travis-ci.org/kjirou/jquery.tempura.png)](https://travis-ci.org/kjirou/jquery.tempura)

==============



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 :fried_shrimp: Tempura :fried_shrimp:



## 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



- [Stable production version](https://raw.github.com/kjirou/jquery.tempura/master/jquery.tempura.min.js)

- [Stable development version](https://raw.github.com/kjirou/jquery.tempura/master/jquery.tempura.js)

- [Old releases](https://github.com/kjirou/jquery.tempura/releases)



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](http://opensource.org/licenses/mit-license.php)



## Installation



```



```



## Examples



### 1. Basic rendering



Before:

```



  
Title


  
Contents


  
Footer





$(".welcome-page").tempura({

  title: "Changed Title",

  contents: "Changed contents"

});



```



After:

```



  
Changed Title


  
Changed contents


  
Footer




```



- 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:

```



  
Title


  
Contents





$(".welcome-page").tempura({

  contents: false

});



```



After:

```



  
Title


  
Contents




```



- `true` means `$node.show()`, `false` means `$node.hide()`.



### 3. Change binded node as a jQuery object



Before:

```




$(".login-page").tempura({

  loginLink: {

    css: { fontSize:12, textAlign:"center" },

    attr: ["href", "/login"],

    addClass: "link-style",

    text: "Logged in, hurry!"

  }

});



```



After:

```



```



- 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:

```



  
Child





$(".some-page").tempura({

  parent: $('<p>').text("New child")

});



```



After:

```



  
New child




```



- `$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:

```



  


  





$(".some-page").tempura({

  byJQuery: $('<p>1</p><p>2</p>').filter('*'),

  byArray: [

    $('<p>').text("A"),

    $('<p>').text("B")

  ]

});



```



After:

```



  


1


2




  


A


B






```



- `$jQueryQuerySet` replaces child nodes the same as the rendering HTML.

  - The "QuerySet" is jQuery object to be return by `$el.find()`, `$el.filter()` and so on.

  - Ref) [jQuery API Documentation - Traversing](http://api.jquery.com/category/traversing/)

- Also `Array` is parsed like it.



### 6. Dynamic evaluation



Before:

```



  




$(".some-page").tempura({

  timer: function(){

    return new Date();

  }

});



```



After:

```



  Fri Aug 02 2013 21:55:40 GMT+0900 (JST)



```



- `Function` is evaluated every rendering.

- `this` in the function is binded to `$node`.



### 7. Not rendering



Before:

```



  Hello, guest!




$(".some-page").tempura({

  greeting: function(){

    if (!isLoggedIn) return;

    return "Hello, member!";

  }

});



```



- `undefined` or `null` are passing through the rendering.



### 8. Complex cases



Before:

```



  
    

    


    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);

          );

        });

      }

    });
    


    ```
    


    After:

    ```

    

      
      

          
    • Taro:1
      • 

          
    • Jiro:2
      • 

          
    • Saburo:3
      • 

        
    

    

    ```
    


    - Sorry, this is a weak case :persevere:

    - How the custom filter might help you.
    


    ### 9. `:ignored` built-in value
    


    ```

    

      1

      
    

        2

      
    

    


    $(".layout").tempura({

      foo: 11,  // Update

      bar: 22   // Not update

    });

    $(".partial").tempura({

      bar: 22 // Update

    });
    


    ```
    


    - `:ignored` protects childrens from unwanted update by outside.
    


    ### 10. Register a custom filter
    


    Before:

    ```
    


    $().tempura("filter", "lower", function(str){

      return str.toLowerCase();

    });
    


    

      
    TITLE
    

    


    $(".some-page").tempura({

      title: function(misc, filters){

        return filters.lower(this.text());

      }

    });
    


    ```
    


    After:

    ```

    

      
    title
    

    

    ```
    


    - 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 [email protected]: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](development/index.html)

    - Or, execute `npm run testem` and open [http://localhost:7357/](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
    


    - [The jQuery Plugin Registry - jQuery Tempura](http://plugins.jquery.com/tempura/)

    - [日本語紹介記事](http://blog.kjirou.net/p/3505)