fastn

Create ultra-lightweight UI components

Homepage

Try it

Example app

Usage

The absolute minimum required to make a fastn component:

initialise fastn:

// Require and initialise fastn
var fastn = require('fastn')({
    // component constructors.. Add what you need to use

    text: require('fastn/textComponent'), // Renders text
    _generic: require('fastn/genericComponent') // Renders DOM nodes
});

var something = fastn('h1', 'Hello World');

something.render();

window.addEventListener('load', function(){
    document.body.appendChild(something.element);
});

^ try it

fastn is a function with the signature:

fastn(type[, settings, children...])

which can be used to create a UI:

// Create some component
var someComponent = fastn('section',
        fastn('h1', 'I\'m a component! :D'),
        fastn('a', {href: 'http://google.com'}, 'An anchor')
    );

someComponent.render();

// Append the components element to the DOM
document.body.appendChild(someComponent.element);

^ try it

You can assign bindings to properties:

var someComponent = fastn('section',
        fastn('h1', 'I\'m a component! :D'),
        fastn('a', {href: fastn.binding('url')},
            fastn('label', 'This link points to '),
            fastn('label', fastn.binding('url'))
        )
    );

someComponent.attach({
    url: 'http://google.com'
});

Which can be updated via a number of methods.

someComponent.scope().set('url', 'http://bing.com');

^ try it

Special component types

There are a few special component types that are used as shorthands for some situations:

text

if a string or binding is added as a child into a containerComponent, fastn will look for a text component, set it's text to the string or binding, and insert it. This is handy as you don't need to write: fastn('text', 'foo') all over the place. ^ try it

_generic

if the type passed to fastn does not exactly match any component it knows about, fastn will check for a _generic component, and pass all the settings and children through to it. ^ try it

Default components

fastn includes 4 extremely simple default components that render as DOM nodes. It is not neccisary to use them, and you can replace them with your own to render to anything you want to.

textComponent

A default handler for the text component type that renders a textNode. eg:

fastn('something', // render a thing
    'Some string passed as a child' // falls into the `text` component, renderes as a textNode
)

genericComponent

A default handler for the _generic component type that renders DOM nodes based on the type passed, eg:

fastn('div') // no component is assigned to 'div', fastn will search for _generic, and if this component is assigned to it, it will create a div element.

listComponent

takes a template and inserts children based on the result of its items property, eg:

fastn('list', {
    items: [1,2,3],
    template: function(){
        return fastn.binding('item')
    }
})

the templated componets will be attached to a model that contains key and item, where key is the key in the set that they correspond to, and item is the data of the item in the set.

templaterComponent

takes a tempalte and replaces itself with the component rendered by the template. Returning null from the template indicates that nothing should be inserted.

The template funciton will be passed the last component that was rendered by it as the third parameter.

fastn('templater', {
    data: 'foo',
    template: function(model, scope, currentComponent){
        if(model.get('item') === 'foo'){
            return fastn('img');
        }else{
            return null;
        }
    }
})

A little deeper..

A component can be created by calling fastn with a type, like so:

var myComponent = fastn('myComponent');

This will create a component regestered in components with the key 'myComponent'

if 'myComponent' is not found, fastn will check for a '_generic' constructor, and use that if defined. The generic component will create a DOM element of the given type passed in, and is likely the most common component you will create.

var divComponent = fastn('div', {'class':'myDiv'});

The above will create a component, that renderes as a div with a class of 'myDiv'

the default genericComponent will automatically convert all keys in the settings object to properties.

fastn.binding(key)

Creates a binding with the given key.

A binding can be attached to data using .attach(object).

The Bits..

There are very few parts to fastn, they are:

component, property, and binding

If you are just want to render some DOM, you will probably be able to just use the default ones.

component

A fastn component is an object that represents a chunk of UI.

var someComponent = fastn('componentType', settings (optional), children (optional)...)

property

A fastn property is a getterSetter function and EventEmitter.

var someProperty = fastn.property(defaultValue, changes (optional), updater (optional));

// get it's value
someProperty(); // returns it's value;

// set it's value
someProperty(anything); // sets anthing and returns the property.

// add a change handler
someProperty.on('change', function(value){
    // value is the properties new value.
});

properties can be added to components in a number of ways:

via the settings object:

var component = fastn('div', {
        property: someProperty
    });

at a later point via property.addTo(component, key);

someProperty.addTo(component, 'someProperty');

binding

A fastn binding is a getterSetter function and EventEmitter.

It is used as a mapping between an object and a key or path on that object.

var someBinding = fastn.binding('foo');

// get it's value
someBinding(); // returns it's value;

// set it's value
someBinding(anything); // sets anthing and returns the binding.

// add a change handler
someBinding.on('change', function(value){
    // value is the properties new value.
});

You can pass multiple paths or other bindings to a binding, along with a fuse function, to combine them into a single result:

var anotherBinding = fastn.binding('bar', 'baz', someBinding, function(bar, baz, foo){
    return bar + foo;
});

A note on the difference between properties and bindings

On the surface, properties and bindings look very similar. They can both be used like getter/setter functions, and they both emit change events.

They differ both in usage and implementation in that properties don't have any awareness of a model or paths, and bindings dont have any awareness of components.

This distinction shines when you design your application with 'services' or 'controllers' that encapsulate models and how to interact with them. Check out the example applications search service and search bar component. The service only deals with data, and the component only deals with UI.