Skip to content
This repository

Javascript DSL for html generation in the browser

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 bin
Octocat-spinner-32 examples
Octocat-spinner-32 lib
Octocat-spinner-32 test
Octocat-spinner-32 .gitignore
Octocat-spinner-32 .travis.yml
Octocat-spinner-32 LICENSE
Octocat-spinner-32 README.md
Octocat-spinner-32 package.json
README.md

htmlr TravisCI

  • Htmlr is a template language for Express.
  • Htmlr is an easy way to create DOM elements in the browser.
  • Htmlr is a Domain Specific Language (DSL) in javascript for generating HTML.

Htmlr can be used on the server or in the browser. In the browser it can generate HTML text for use with .innerHTML or it can generate document fragments for use with .appendChild. Template files use a .htmlr extension and can be a javascript expression or a function that returns an Htmlr object.

Installation

npm install htmlr

Browser Usage

For use in the browser, include the following script tag:

<script src="lib/htmlr.js"></script>

Then create your dynamic elements in the browser:

with (Htmlr) {
  var template = div({class: 'person'},
    'Name: ', span('{name}'), br,
    'Email: ', span('{email}')
  );
}

var data = {name: 'Scott', email: 'scott@example.com'};

// html text generation
document.getElementById('my_div').innerHTML = template.render(data);

// DOM object generation
document.getElementById('my_div').appendChild( template.renderDOM(data) );
<div class="person">
Name: <span>Scott</span><br />
Email: <span>scott@example.com</span>
</div>

Express Usage

Create the following 2 template files to mimic the default express jade templates and put them in the views directory:

  • layout.htmlr

    doctype()
    .html(
      head(
        title('{title}'),
        css('/stylesheets/style.css')
      ),
      body('{body}')
    )
    
  • index.htmlr

    h1('{title}')
    .p('Welcome to {title}')
    

Then modify the app.js file to change the default rendering engine to htmlr:

// Configuration

app.configure(function(){
  app.set('views', __dirname + '/views');
  app.set('view engine', 'htmlr');         // <=== put 'htmlr' right here
  app.use(express.bodyParser());
  app.use(express.methodOverride());
  app.use(app.router);
  app.use(express.static(__dirname + '/public'));
});

Command Line Usage

Htmlr can also be used on the command line to test templates without an express application running. Create a filed called template.htmlr and a file with json data called data.json:

  • template.htmlr

    doctype()
    .html(
      head({lang: 'en'},
        meta({charset: 'utf-8'}),
        title('{title}'),
        css('style.css'),
        javascript('script.js')
      ),
      body(
        h1("Hello World!"),
        comment("woot!"),
        div({id: 'content'}, '{content}')
      )
    )
    
  • data.json

    {"title": "My Title", "content": "My Content"}
    

Then run the following command:

htmlr template -d data.json -l
<!DOCTYPE html>
<html>
  <head lang="en">
    <meta charset="utf-8" />
    <title>My Title</title>
    <link rel="stylesheet" href="style.css" />
    <script src="script.js"></script>
  </head>
  <body>
    <h1>Hello World!</h1>
    <!--woot!-->
    <div id="content">
      My Content
    </div>
  </body>
</html>
  • Use the with statement to prevent pollution of the global namespace in the browser. ( with is forbidden in strict mode :( )

    with (Htmlr) {
      var template = div();
    }    
    var html = template.render();
    
    <div />
    

Features

  1. Use an object literal as the first parameter to set attributes

    with (Htmlr) {
      var template = div({id: 'mydiv', class: 'awesome'});
    }    
    var html = template.render();
    
    <div id="mydiv" class="awesome" />
    
  2. Use any other data type for the first parameter and all data types afterward for child nodes

    with (Htmlr) {
      var template = div('Literal String', br, 1337);
    }   
    var html = template.render();
    
    <div>Literal String<br>1337</div>
    
  3. Chain objects together to create siblings

    with (Htmlr) {
      var template = div().div();
    }
    var html = template.render();
    
    <div /><div />
    
  4. Create templates that can be reused. Pass data structures to templates to ease variable generation

    with (Htmlr) {
      var template = div({id: '{id}', class: '{class}'},
        '{content}'
      )
    }
    
    var data1 = {id: 'one', class: 'first second', content: 'Hello'};
    var data2 = {id: 'two', class: 'third', content: 'World!'};
    
    var html = template.render(data1) + template.render(data2);
    
    <div id="one" class="first second">Hello</div>
    <div id="two" class="third">World!</div>
    
  5. Use substitution syntax for creating templates that can be fed data, either objects or arrays

    with (Htmlr) {
      var template1 = div('{name}');
    }
    var data1 = {name: 'Scott'};
    var html1 = template1.render(data1);
    
    <div>Scott</div>
    
    with (Htmlr) {
      var template2 = div('{0}');
    }
    var data2 = ['Scott'];
    var html2 = template2.render(data2);
    
    <div>Scott</div>
    
  6. Loop through data structures, objects or arrays, using the each construct

    with (Htmlr) {
      var template1 = (
        ul(each()(
          li('{0}')
        ))
      );
    }
    var data1 = ['one', 'two', 'three'];
    var html1 = template1.render(data1);
    
    <ul>
      <li>one</li>
      <li>two</li>
      <li>three</li>
    </ul>
    
    with (Htmlr) {
      var template2 = (
        ul(each()(
          li('{key}: {value}')
        ))
      );
    }
    var data2 = {1: 'one', 2: 'two', 3: 'three'};
    var html2 = template2.render(data2);
    
    <ul>
      <li>1: one</li>
      <li>2: two</li>
      <li>3: three</li>
    </ul>
    

    each can also take a static list:

    with (Htmlr) {
      var template = (
        select(each(['North', 'South', 'East', 'West'])(
          option('{0}')
        )
      );
    }    
    var html = template.render();
    
    <select>
      <option>North</option>
      <option>South</option>
      <option>East</option>
      <option>West</option>
    </select>
    
  7. Includes the ability to extracts parts of the data object

    with (Htmlr) {
      var template1 = div(extract('error')(
        'Error',
        span('{number}'),
        ': ',
        span('{message}')
      ));
    }
    var data1 = {error: {number: 42, message: 'unknown question'}};
    var html1 = template1.render(data1);
    
    <div>Error <span>42</span>: <span>unknown question</span></div>
    

    extract can reach into multiple levels of data structure

    with (Htmlr) {
      var template2 = extract(1, 0)(div('{0}'));
    }
    var data2 = [[[0, 1], [2, 3]], [[4, 5], [6, 7]]];
    var html = template2.render(data2);
    
    <div>4</div>
    

Known Issues

None yet. We need more testers!

Something went wrong with that request. Please try again.