Skip to content
Browse files

Added index.js, lots of documentation to the README.

  • Loading branch information...
1 parent fba9d51 commit 1d2bf8d75e3af99474d7979e19cd70c3415f05f4 @chrisjpowers chrisjpowers committed Jul 10, 2012
Showing with 139 additions and 18 deletions.
  1. +137 −18 README.md
  2. +2 −0 index.js
View
155 README.md
@@ -1,26 +1,145 @@
+# Facile
-Facile
-===
+Facile is a convention-based template engine that can be executed
+either in the browser (using jQuery or zepto) or on the server
+(using cheerio). While other template systems like Mustache give the
+developer syntax for explicit conditionals, enumerations and data
+bindings, Facile uses simple conventions to achieve the same goals
+with less code.
-[![Build Status](https://secure.travis-ci.org/lawlesst/bibjsontools.png?branch=master)](http://travis-ci.org/lawlesst/bibjsontools)
+## Installation
-Convention-based template engine that depends on jQuery or zepto.
+If you want to use Facile with Node.js, install it using `npm`:
-Features
-===
+```bash
+npm install facile
+```
-1. maps string values to ids (or class if id not found) that match keys
-1. maps array values to classes that match keys
-1. removes elements with null values that have ids (or classes) that match keys
-1. maps object values to allow attribute binding in addition to content binding
-1. maps arrays of object values to allow nested loop binding
+To use Facile in the browser, either copy the `facile.coffee` file
+or the compiled `test/public/javascripts/facile.js` file into your
+project.
-See tests for a more complete explanation.
+## Usage
-Running the tests
-===
-1. Install node, npm, coffee-script
-1. ./coffee # to watch/recompile coffee
-1. node test # run jasmine server
-1. visit http://localhost:5000
+The facile package is a single function that accepts a `template` string
+and a `data` object:
+
+```javascript
+var facile = require("facile"), // only needed in Node.js
+ template = "...",
+ data = {...},
+ output = facile(template, data);
+```
+
+### Data Binding by Ids and Classes
+
+Facile will look for DOM ids and classes that match the keys in your
+data object and set the DOM elements' text to the data values:
+
+```javascript
+var template = '<div id="dog"></div><div class="cat"></div>',
+ data = {dog: "woof", cat: "meow"};
+facile(template, data);
+// returns '<div id="dog">woof</div><div class="cat">meow</div>'
+```
+
+### Looping Over Collections
+
+When a value in the data object is an array, Facile will find the
+container DOM element that matches the data key and render its
+contents for each item in the array.
+
+```javascript
+var template = '<ul id="users"><li class="name"></li></ul>',
+ data = {users: [
+ {name: "Moe"},
+ {name: "Larry"},
+ {name: "Curly"}
+ ]};
+facile(template, data);
+// returns:
+// <ul id="users">
+// <li class="name">Moe</li>
+// <li class="name">Larry</li>
+// <li class="name">Curly</li>
+// </ul>
+```
+
+If you are binding an array of data to a `<table>` element, Facile will
+expect there to be a single `<tr>` inside the table's `<tbody>` and
+will repeat that `<tr>` for each item in the array.
+
+```javascript
+var template = '<table id="users">' +
+ ' <thead>' +
+ ' <tr><th>Name</th></tr>' +
+ ' </thead>' +
+ ' <tbody>' +
+ ' <tr><td class="name"></td></tr>' +
+ ' </tbody>' +
+ '</table>',
+ data = {users: [
+ {name: "Moe"},
+ {name: "Larry"},
+ {name: "Curly"}
+ ]};
+facile(template, data);
+// returns:
+// <table id="users">
+// <thead>
+// <tr><th>Name</th></tr>
+// </thead>
+// <tbody>
+// <tr><td class="name">Moe</td></tr>
+// <tr><td class="name">Larry</td></tr>
+// <tr><td class="name">Curly</td></tr>
+// </tbody>
+// </table>
+```
+
+### Removing Elements
+
+If the data object has a `null` value, the corresponding DOM element
+will be removed.
+
+```javascript
+var template = '<p>Hello!</p><p class="impolite">Take a hike, guy.</p>',
+ data = {impolite: null};
+facile(template, data);
+// returns "<p>Hello!</p>"
+
+
+### Setting DOM Attributes
+
+There are two ways to set DOM attributes on elements using Facile.
+First, if a value in the data object is an object, Facile will treat
+the keys as attribute names for the matching DOM element. *NOTE:*
+the `content` key is special in that it updates the content of the
+element rather than setting a `content` attribute.
+
+```javascript
+var template = '<div id="dog" />',
+ data = {dog: {content: 'woof', 'data-age': 3} };
+facile(template, data);
+// returns '<div id="dog" data-age="3">woof</div>'
+```
+
+The second way is to name a key in the data object using the convention
+`id-or-class@attribute`.
+
+```javascript
+var template = '<div id="dog" />',
+ data = {dog: 'woof', 'dog@data-age': 3};
+facile(template, data);
+// returns '<div id="dog" data-age="3">woof</div>'
+```
+
+## Running the Tests
+
+1. Install `node` and `npm`.
+2. Run `npm install` to the dependencies
+3. Run `npm test` to run the specs in Node.js
+4. Run `./coffee` to watch/compile the CoffeeScripts
+5. Run `node test` to run Jasmine test server
+6. Visit [http://localhost:5000](http://localhost:5000) to see the tests run in the browser.
View
2 index.js
@@ -0,0 +1,2 @@
+require("coffee-script");
+module.exports = require("./facile");

0 comments on commit 1d2bf8d

Please sign in to comment.
Something went wrong with that request. Please try again.