Featherₜₛ

Getting started

Fri, 30 Sep 2016 21:07:13 +0100

Installing Featherₜₛ

Installing typescript and typings globally is recommended, if not yet present. Then run the following commands to add featherₜₛ as a local dependency.

npm install feather-ts --save

Create a tsconfig.json file in your project’s root containing the following settings. ES6 output is currently not supported and since decorators are the beef of it all make sure they are enabled. Feather.js embeds the typescript emitted helpers so you can disable them if you wish.

{
  "compilerOptions": {
    ...
	"target": "es5", 
	"experimentalDecorators": true, 
	...
  },
  "files": [
	<your-source-files>
  ],
  "exclude": [
    ...
	"node_modules",
	"typings"
	...
  ]
}

Then write your widgets and include the output together with feather.js (from node_modules) in your page. After the DOM and the scripts have been loaded make the following call; it will bootstrap the widgets and route listeners.

feather.start();

To get an impression of the code style you will be dealing with, here is a sample widget code. As you can see the code is very compact and flat.

module todomvc.feather {

    import Widget          = feather.core.Widget /* imports of referenced components */
    ...
    
    @Construct({selector: '.todoapp'}) /* the selector to bind this widget to */
    class TodoList extends Widget {    /* all widgets must extend Widget */

        @Bind() state = ListState.ALL  /* prefix members that auto update DOM with @Bind(), supported are booleans, strings and numbers */

        @Bind({templateName: 'default', changeOn: ['state']}) /* arrays are a special case, more about the params later */
        todos: Todo[] = []
        
        /* no constructor is required */

        init(element: HTMLElement) {   /* whenever a widget is fully initialized it calls init() */
            this.getData()
        }
        
        @Fetch('/api/todos')           /* fetch data from a REST api and render the widget */
        getData(data?: Todo[]) {
            this.todos.push.apply(this.todos, data)
            this.render('default')     /* if you're not loading data you can render() already in init() */
        }

        @Subscribe('create-todo')      /* listen to messages from parent or child widgets via @Subscribe */
        newTodo(todo: Todo) {
            this.todos.push(todo)
        }

        @Route('/:path')               /* listen to route changes with @Route */
        locationPath(params: SimpleMap) {
            if (params['path'] === 'active') {
                ...
            }
        }

        @On({event: 'click', selector: '.clear-completed', preventDefault: true}) /* attach DOM events via @On */
        clearCompleted() {
            ...
        }

        @Template('default') /* widgets can be rendered with different templates */
        toHtml() { /* use ES6 template strings to define HTML snippets */
            return (`
              ...
              <ul class="todo-list" {{todos:listFilter}}></ul>
              <button class="clear-completed" hidden="{{todos:noCompleted}}">Clear completed</button>
              ...
            `)
        }
    }
}

See the full todo app in action here. Take a peek at the typescript source maps, too.

Note

The bindings in the HTML code are very simple. The only extra syntax on top of regular HTML is {{variable:methodA:methodB}}. Methods are optional however they can convert values to other types, ie boolean to “yes” / “no” strings, or filter arrays before rendering.

The above code is stripped off large parts, so don’t expect it to compile or run.

API Documentation

Sat, 01 Oct 2016 21:07:13 +0100

Widgets

Your application will be a collection of classes that all extend feather’s Widget class. The widget class itself inherits other classes in the following order:

MyWidget -> Widget -> Observable -> RouteAware -> Subscribable -> EventAware -> Object

At its core a widget class is attached to a single DOM element. It holds a reference to that element, which you can access in your class via this.element. Furthermore it exposes a method render(templateName: string), which has to be called manually for the widget to render into its element. Feather doesn’t want to make assumption when to render the widget; it might be required to fetch data from a server or wait for other events first.

A widget usually comes with a @Construct({selector: string}) class annotation, which defines which HTML elements the component will be attached to. Once the Widget cas been created, you can override the init(element: HTMLElement) method in your class and call this.render(templateName) there. The templateName is defined via @Template(), which should decorate a method which returns a string it should render. Note the widgets don’t require a constructor, and most of the custom initialization should be done in the overwritten init method. An exception to this are array-widgets, but more on this later.

You can also have different templates in the same widget class and choose which way to render the widget’s data.

Putting it all together, a very simple widget might look like this:

 module demo {
 
     import Widget    = feather.core.Widget
     import Construct = feather.annotations.Construct
     import Template  = feather.annotations.Template
 
     @Construct({selector: 'body'})
     export class MyApplication extends Widget {
 
         who = 'world'   
 
         init(element: HTMLElement) {
             this.render('default')
         }
 
         @Template('default')
         protected getBaseTemplate() {
             return (`
                Hello ${this.who}!                                    
             `)
         }
     }
 }

Call then feather.start() and your application should render itself into <body>.

Observable

Primitives

The above example is quite rudimentary and if you wanted to change the variable who you would need to call render(...) again to see it. This is a little bit cumbersome and expensive, since the widget would then re-render the entire template with any sub widgets referenced within. To avoid this you can annotate primitive members (currently only booleans, strings and numbers) with @Bind() like this (note the use of double-curlies):

Now whenever the value of who changes, the text node will update automatically. You can bind variables in 4 different places within a dom tree and in combation with the variable type, only some of them make sense. The hooks can be inserted in these ways:

<div class="right {{variable}} large">...</div> As a new class in the class attribute (only strings)
<div class="red" style="{{variable}}">...</div> Within an arbitrary attribute (only strings and booleans)
<div class="red" {{variable}}>...</div> As a property hook (booleans and arrays)
<div class="red">Some {{variable}} text!</div> Within a text node (only strings)

Note that any binding can convert booleans, numbers or arrays into strings. This is done but declaring a “filter” function in the widget class. you can then bind it like this: <div class="{{variable:formatAsString}}">...</div>

Booleans

Arrays

Objects

… write the rest …

Image layout algorithm

Sun, 02 Oct 2016 21:07:13 +0100

Here we are going to use feather to write a small widget that layouts a set of images in an rectangle with fixed dimensions.

Introduction

Thu, 29 Sep 2016 21:07:13 +0100

Featherₜₛ is a small component framework written in TypeScript. Whether you are writing embeddable javascript widgets or a single page application this framework might be of use. With less than 8kb in size it is suited for mobile apps and desktop alike. It is especially well suited for the consumption of restful services.

The framework offers the following features:

Each component is holding logic, view and model in a single file
Components automatically build a hierarchical tree
Message hub between components
REST access
Routing via hash or history API
Very flat learning curve due
Logicless templates in pure HTML with very simple binding syntax
Event delegation out of the box
Written in TypeScript
No module loaders needed, embed directly via NPM
With aynchronous decorators no need for promises
Support for modern browsers including IE9

You can checkout a todomvc demo here.