README.md

fastn

Create ultra-lightweight UI components

Homepage, Try it, Example app

Usage

The absolute minimum required to make a fastn component:

initialise fastn with default DOM components:

var fastn = require('fastn')(
    // Default components for rendering DOM.
    require('fastn/domComponents')(/* optional extra constructors */)
);

Or use your own selection of constructors:

// 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
});

Make components:

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

Put them on the screen:

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 known components, 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 necessary to use them, and you can replace them with your own, enabling you to render to anything you want to.

textComponent

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

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

genericComponent

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

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, e.g.:

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

Templated components 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.

Lazy templating

If you need to render a huge list of items, and you're noticing a UI hang, you can choose to enable lazy templating by setting a lists' insertionFrameTime to some value:

fastn('list', {
    insertionFrameTime: 32, // Only render items for 32 milliseconds at a time before awaiting idle time.
    items: [1,2,3],
    template: function(){
        return fastn.binding('item')
    }
})

templaterComponent

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

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

Note: The template function will run immediately upon component creation. This means that if your data is a binding, the first run of the template function will always receive undefined as it's item.

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

An optional property of attachTemplates can be provided. When set to true (default), the children rendered from the template will be attached to a new scope that contains the templater data, under the key of item.

When set to false, the children rendered from the template will inherit their attachment from the templator.

var appData = {
    foo: 'bar'
};

fastn('templater', {
    data: binding('foo'),
    attachTemplates: false,
    template: function(model, scope, currentComponent){
        // model.get('item') -> is appData
    }
}).attach(appData)

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 registered 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 renders 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 anything 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.

The path syntax is identical to that used in enti

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

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

// set it's value
someBinding(anything); // sets anything 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;
});

binding.from(value)

• if value is a binding: return value,
• else: return a binding who's value is value.

useful when you don't know what something is, but you need it in a binding:

var someBinding = fastn.binding('someKey', fastn.binding.from(couldBeAnything), function(someValue, valueOfAnything){

    });

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 don't 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.

Browser Support

Fastn works in all the latest evergreen browsers.

Fastn May work in other browsers, but will almost certainly need a few polyfills like WeakMap, Map, WeakSet, Set, etc...