logo hoe.js

hoe.js

hoe.js is a lightweight javascript library designed to streamline the creation of user interface in HTML/javascript.

Why hoe.js ?

From one side you have toolkits like jQuery that simplifies DOM manipulation but lacks support for creating complex UI.

On the other side you have MVC frameworks that often impose a very heavy-weight mechanism to create applications.

hoe.js's goal is to let you write structured code for small components and let you scale up your application without "getting into your way". It relies on javascript prototypes and optionally CustomElements, just adding some missing pieces:

Installation

Install using bower

$ bower install hoe

Example

hoe.js does not enforce any kind of structure for your code, but it was specially designed to help you create custom UI components. Here is the code to create CustomElement that can be used on HTML and programmatically on javascript.

      

This could be used in HTML:

<hoe-counter initial-value="2"></hoe-counter>

DOM creation

hoe()
var row  = hoe('div', {'class':'row'}, 'foo');
//  <div class="row">foo</div>
      

The first argument is a string with tag name. The second argument is plain object with tag attributes It can take any number of extra arguments where:

  • strings are appended to the element content
  • DOM elements are appended to the element content
hoe.partial()
var row  = hoe.partial('div', {'class':'row'});
row(null, 'foo');
//  <div class="row">foo</div>
row(null, 'bar');
//  <div class="row">bar</div>
       

hoe.partial() is used to create helper functions to generate composed tags and/or include tag attributes. The first argument is tag attributes, remaining attributes are appended to the element.

hoe.init()

hoe.init() defines function helpers to create most commonly used tags.

The function's name is the tag it creates. In this example tr() and td() are used.

hoe.init();
var row = tr(null, td({'class':'my_class'}, 'col1'));
//<tr>
//  <td class="my_class">col1</td>
//</tr>
      

You can customize the namespace (first argument) and tags that will be created (second argument)

Other helper functions
  • hoe.append()
  • hoe.html()
  • hoe.remove()
  • hoe.fragment()

prototype helpers

hoe.inherit()

Create new types by "inheriting" from other types:

function Base(){
    this.x = 1;
}
Base.prototype.three = function(){
    return 3;
};

var Sub = hoe.inherit(Base, function(){
    this.x = 2;
});
var obj = new Sub();
obj.three();
      
  • the first argument is the function constructor to copy the prototype from
  • the second argument is optional. If present, defines the constructor otherwise the constructor from the base type is used
hoe.Type

hoe.Type is an abstract type that provides some convenience methods that keep the scope to the object when passing methods as callbacks. It also supports a basic event system to be used between objects.

When creating new type you should inherit from hoe.Type

var MyType = hoe.inherit(hoe.Type, function(){/*...*/});

// ... this shorthand has the same effect as above
var MyType = hoe.Type(function(){/*...*/});
      
hoe.Type.scope()
Similar to jQuery.proxy() to be used in the current object scope.
var MyStuff = hoe.Type(function(){
    this.x = 5;
});
var my = new MyStuff();
var get_on_scope = my.scope(function() {return this.x;});
get_on_scope(); // 5
hoe.Type.forArray()
Iterate through arrays keeping the context to the current object.
var MyType = hoe.Type(function(){
    this.class = 'my_class';
    this.$ele = div();
});
MyType.prototype.add_span = function(content){
   hoe.append(this.$ele, span({'class': this.class}, content));
}

var my = new MyType();
my.forArray(['ele1', 'ele2'], my.add_span);
my.$ele.outerHTML;
// <div>
//    <span class="my_class">ele1</span>
//    <span class="my_class">ele2</span>
// </div>
      
hoe.Type.mapArray()
Iterate through arrays keeping the context to the current object. Returned values in iteration are used to create an array.
var MyType = hoe.Type(function(){
    this.class = 'my_class';
});
MyType.prototype.create_span = function(content){
   return span({'class': this.class}, content);
}

var my = new MyType();
var span_array = my.mapArray(['ele1', 'ele2'], my.create_span);
div(null, hoe.fragment(span_array));
// <div>
//    <span class="my_class">ele1</span>
//    <span class="my_class">ele2</span>
// </div>
      
hoe.Type.forDict()

Similar to hoe.type.forArray() but used for plain objects, second callback argument is item key instead of index.

hoe.Type.mapDict()

Similar to hoe.type.mapArray() but used for plain objects, second callback argument is item key instead of index.

Event system

DOM events
hoe.Type.listen() can be used to bind DOM events keeping the object context.
my_obj.listen($ele, 'click', function(){alert(this.my_attr)});

// is the same as plain jQuery
$ele.bind('click', $.proxy(function(){alert(this.my_attr)}, my_obj));
      
object events
Objects can create their own events with hoe.Type.fire().
my.fire('my-custom-event-name', "argument1", {arg: 2});
      
  • the first argument is the event name
  • other arguments will be passed to any event callback

Other objects can register callbacks to handle events in a similar way it is done for DOM events, but the first argument is an object that generates events instead of a DOM element.

var my2 = new MyType();
my2.listen(my, 'my-custom-event-name', function(val){
     this.ele.append(val);
});
      

Custom Elements

Check the example on top.

hoe.Component()

First argument is a string with tag name.

Second argument is a method, initializer to be called when an element is created. The initializer has a single parameter, a plain object. with values passed when called with hoe.Component.New() or hoe.Component.from_html().

The return value is an Element prototype. This prototype extends hoe.Type()

hoe.Component.from_html()

Apart from the initializer passed on hoe.Component you typically need to implement the from_html() that is responsible from taking data from the original HTML and pass it to the initializer method.

hoe.Component.New()

This is a static factory method used to create new elements programmatically from javascript code. It takes a single parameter, a plain object to be passed to the initializer method.