fill

NOT READY FOR PRODUCTION

This project is under heavy development, and the API has not solidfied yet. Don't use this for anything important...yet.

Synopsis

Bind data to DOM with zero configuration. Just call .fill(data).

<div id="template">
  <h2 class="project"></h2>
  <div data-bind="details">
    <a name="githubLink"></a>
    <ul class="features">
      <li></li>
    </ul>
  </div>
</div>

$('#template').fill({
  project: 'Fill',
  details: {
    githubLink: { _text: 'Fill', _href: 'https://github.com/profit-strategies/fill' },
    features: {
      _style: 'color:green'
      li: [
        'Uses plain HTML with no extra templating markup',
        'Runs on the client or server (with jsdom)',
        'Render arrays without loops or partials',
        'Nested objects and collections',
        'Compatible (tested on IE6+, Chrome and Firefox)',
      ]
  }
});

<div id="template">
  <h2 class="project">Fill</h2>
  <div data-bind="details">
    <a name="githubLink" href="https://github.com/profit-strategies/fill">Fill</a>
    <ul class="features" style="color:green">
      <li>Uses plain HTML with no extra templating markup</li>
      <li>Runs on the client or server (with jsdom)</li>
      <li>Render arrays without loops or partials</li>
      <li>Nested objects and collections</li>
      <li>Compatible (tested on IE6+, Chrome and Firefox)</li>
    </ul>
  </div>
</div>

Use it

Install with npm install fill or get the compiled and minified version and include it to your application. jQuery is optional, but if you happen to use it, fill registers itself as a plugin.

<script src="js/jquery-1.7.1.min.js"></script>
<script src="js/fill.min.js"></script>

For server-side use, see spec folder and the awesome jsdom for the details.

Examples

Assigning values

fill binds JavaScript objects to DOM a element by id, class,element name, name attribute and data-bind attribute. Values are escaped before rendering. Any keys that are prefixed with an underscore are treated as attributes (with the exception of _text and _html).

Template:

<div id="container">
  <div id="hello"></div>
  <div class="goodbye"></div>
  <span></span>
  <input type="text" name="greeting" />
  <button class="hi-button" data-bind="hi-label"></button>
</div>

Javascript:

var hello = {
  _class:     'message',
  hello:      'Hello',
  goodbye:    'Goodbye!',
  span:       '<i>See Ya!</i>',
  greeting:   'Howdy!',
  'hi-label': 'Terve!' // Finnish i18n
};

// with jQuery
$('#container').fill(hello);

// ..or without
fill(document.getElementById('container'), hello);

Result:

<div id="container" class="message">
  <div id="hello">Hello</div>
  <div class="goodbye">Goodbye!</div>
  <span><i>See Ya!</i></span>
  <input type="text" name="greeting" value="Howdy!" />
  <button class="hi-button" data-bind="hi-label">Terve!</button>
</div>

Iterating over a list

Template:

<ul id="activities">
  <li class="activity"></li>
</ul>

Javascript:

var activities = {
  activity: [
    'Jogging',
    'Gym',
    'Sky Diving'
  ]
};

$('#activities').fill(activities);

// or
fill(document.getElementById('activities'), activities);

Result:

<ul id="activities">
  <li class="activity">Jogging</li>
  <li class="activity">Gym</li>
  <li class="activity">Sky Diving</li>
</ul>

Iterating over a list, using a css class to select the target

Template:

<div>
  <div class="comments">
    <div class="comment">
      <label>comment</label><span class="body"></span>
    </div>
  </div>
</div>

Javascript:

var comments = [
  {body: "That rules"},
  {body: "Great post!"}
]

$('.comment').fill(comments);

Result:

<div>
  <div class="comments">
    <div class="comment">
      <label>comment</label><span class="body">That rules</span>
    </div>
    <div class="comment">
      <label>comment</label><span class="body">Great post!</span>
    </div>
  </div>
</div>

Nested lists

Template:

<div class="container">
  <h1 class="title"></h1>
  <p class="post"></p>
  <div class="comments">
    <div class="comment">
      <span class="name"></span>
      <span class="text"></span>
    </div>
  </div>
</div>

Javascript:

var post = {
  title:    'Hello World',
  post:     'Hi there it is me',
  comment: [ {
      name: 'John',
      text: 'That rules'
    }, {
      name: 'Arnold',
      text: 'Great post!'
    }
  ]
};

$('.container').fill(post);

Result:

<div class="container">
  <h1 class="title">Hello World</h1>
  <p class="post">Hi there it is me</p>
  <div class="comments">
    <div class="comment">
      <span class="name">John</span>
      <span class="text">That rules</span>
    </div>
    <div class="comment">
      <span class="name">Arnold</span>
      <span class="text">Great post!</span>
    </div>
  </div>
</div>

Nested objects

Template:

<div class="person">
  <div class="firstname"></div>
  <div class="lastname"></div>
  <div class="address">
    <div class="street"></div>
    <div class="zip"><span class="city"></span></div>
  </div>
</div>

Javascript:

var person = {
  firstname: 'John',
  lastname:  'Wayne',
  address: {
    street: '4th Street',
    city:   'San Francisco',
    zip:    '94199'
  }
};

$('.person').fill(person);

Result:

<div class="container">
  <div class="firstname">John</div>
  <div class="lastname">Wayne</div>
  <div class="address">
    <div class="street">4th Street</div>
    <div class="zip">94199<span class="city">San Francisco</span></div>
  </div>
</div>

Global Match (find all matches)

Template:

<div class="container">
  <div>
    <span class="hello"></span>
  </div>
  <div>
    <span class="hello"></span>
  </div>
  <span class="hello"></span>
</div>

Javascript:

// prefix with a dollar sign to find all matches
// otherwise it will only find the first one
var post = {
  $hello: 'hi'
};

$('.container').fill(post);

Result:

<div class="container">
  <div>
    <span class="hello">hi</span>
  </div>
  <div>
    <span class="hello">hi</span>
  </div>
  <span class="hello">hi</span>
</div>

Development environment

You need node.js 0.6.x and npm.

Install dependencies:

npm install
npm install -g uglify-js

Run tests

npm test

Run tests during development for more verbose assertion output

node_modules/jasmine-node/bin/jasmine-node --verbose spec

Generate Javascript libs

node build

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 going to change fill API, please create a ticket first in order to discuss and agree on design.

Origins and Alternatives

This project was forked from the very impressive Transparency project to attempt the following:

• allow the setting of attributes (without needing to use directives)
  • eventually phasing out directives completely
• add support for manipulating strings of HTML (without jsdom)
  • for superfast rendering of html on server (running node.js)

Similar projects:

• Transparency.js
  • from which this project was spawned
• Plates.js
  • successor of Weld.js