nkzawa / hyperd

Virtual DOM based, template engine agnostic UI library

Hyperd

Virtual DOM based, template engine agnostic UI library.

var component = hyperd(document.getElementById('count'), function() {
  return '<div id="count">Counter: ' + this.data.count + '</div>';
});

component.data.count = 0;

setInterval(function() {
  component.data.count++;
}, 1000);

Differently from any other Virtual DOM based libraries, your UI is defined as just a html string on this library, which allows you to use along with your favorite template engines in a flexible manner.

Installation

$ npm install hyperd

<script src="node_modules/hyperd/hyperd.js"></script>

With Bower

$ bower install hyperd

Features

• Virtual DOM diffing
• Template engine agnostic
• Auto-redrawing
• Building reusable components
• Small API

Examples

• Counter (source)
• Counter Component (source)
• TodoMVC (source)

API Documentation

hyperd(node, render)

• node HTMLElement Node to attach
• render Function Called upon redrawing, must return a html string.
• Return: hyperd.Component

A short circuit to create a component instance.

Class: hyperd.Component

The base component class.

Class Method: hyperd.Component.extend(proto);

• proto Object protoype object
• Return: Function A new component constructor

Creates a new component class.

var MyComponent = hyperd.Component.extend({
  render: function() {
    return '<div>hi</div>';
  }
});

new hyperd.Component([props])

• props Object properties

In classes that extends hyperd.Component, make sure to call the super constructor so that the all settings can be initialized.

hyperd.Component.extend({
  constructor: function(props) {
    hyperd.Component.apply(this, arguments);
    ...
  }
});

component.props

The properties of the component.

var component = new MyComponent({ foo: "hi" });
console.log(component.props.foo); // "hi"

component.data

The state data of the component. Mutating data triggers UI updates.

component.node

The node element which the component is attached to.

component.components

Definitions of child components. You can use defined components like a custom element on render().

var Child = hyperd.Component.extend({
  render: function() {
    return '<div>' + this.props.foo + '</div>';
  }
});

hyperd.Component.extend({
  components: { child: Child },
  render: function() {
    return  '<div><child foo="hi"></div>'
  }
});

component.attachTo(node)

• node HTMLElement
• Return: this

Attaches the component to a DOM node.

new MyComponent().attachTo(document.getElementById('foo'));

component.render()

• Return: String A html string to render.

Note: implement this function, but do NOT call it directly.

Required to implement. This method is called automatically and asynchronously when you update component.data.

component.destroy()

Teardown and delete all properties and event bindings including descendant components.

component.emit(event[, args1][, args2][, ...])

• event String The event type to be triggered.
• Return: this

Trigger a DOM event for component.node with the supplied arguments.

component.emit('edit', arg);

component.on(event, listener)

• event String The event type.
• listener Function
• Return: this

Add a listener for the specified event.

component.on('render', function() { ... });

component.on(event, selector, listener)

• event String The event type.
• selector String CSS selector.
• listener Function The listener always take an event object as the first argument.
• Return: this

Add a listener for the delegated event. The listener is called only for descendants that match the selector. You can use this to listen an event of a child component too.

hyperd.Component.extend({
  constructor: function() {
    hyperd.Component.apply(this, arguments);
    this.on('click', 'button', function(event) {
      console.log('clicked!');
    });
  }
  render: function() {
    return  '<div><button type="button">Click me!</button></div>'
  }
});

component.removeListener(event, listener)

Remove a listener for the specified event.

component.removeListener(event, selector, listener)

Remove a listener for the delegated event.

component.removeAllListeners([event][, selector])

Remove all listeners, or those of the specified event or the delegated event.

component.onAttach()

Called upon after the component is attached to a node.

component.onRender()

Called upon after the component is rerendered.

component.onDestroy()

Called upon after the component is destroyed.

Event: 'attach'

The same as component.onAttach.

component.on('attach', function() { ... });

Event: 'render'

The same as component.onRender.

Event: 'destroy'

The same as component.onDestroy.

Attribute: data-hkey

The identifier used to differentiate a node for Virtual DOM diffing. Used to reconcile an element will be reordered or destroyed.

hyperd.Component.extend({
  render: function() {
    var items = ['foo', 'bar', 'baz'];
    return '<ul>' + items.map(function(item) {
      return '<li data-hkey="' + item + '">' + item + '</li>';
    }).join('') + '</ul>';
  }
});

Licence

MIT

hyperd's Issues

Setting state and listeners on children elements

Consider the following snippet taken from the tests:

    var Child = hyperd.Component.extend({
      constructor: function() {
        hyperd.Component.apply(this, arguments);
        this.data.count = 0;
      },
      render: function() {
        return '<div>' + this.data.count + '</div>';
      },
      onRender: function() {
        expect(this.node.innerHTML).to.be('' + this.data.count);
        this.data.count++;
        if (this.data.count > 5) {
          parent.destroy();
          done();
        }
      }
    });
    var Parent = hyperd.Component.extend({
      components: {
        child: Child
      },
      render: function() {
        return '<div><child/></div>';
      }
    });
    var parent = new Parent().attachTo(this.node);

I'd like to attach a listener to the Child like this:

child.on('click', 'div', console.log.bind(console));

is there any way to reference the instance child from within the Parent?

The same is valid if I want to reference the state within the child:

child.data.foo = 'bar';

At the moment, child is instantiated automatically by Parent and never exposed the outside world. That means that I'm not able to reference any of the methods on that instance (e.g. state, listeners, etc.). I was thinking perhaps component.components could hold a reference to a children already instantiated, rather than class? In this way we could manipulate the new instance like below:

let Child = hyperd.Component.extend({...})

let child = new Child();

let Parent = hyperd.Component.extend({
  components: {child: child},
  ...
})

[...]

child.data.foo = bar;
child.on('click', '*', console.log.bind(console));

Thoughts?