Guide

Templates

Templates describe your UI in plain HTML. You can define them directly in the document, use template elements, custom elements or store and load them however you like. Just make sure you have a convenient way to reference your templates when you want to bind some data to them.

<section id="auction">
  <h3>{ auction.product.name }</h3>
  <p>Current bid: { auction.currentBid | money }</p>
  <rv-aside rv-if="auction.timeLeft | lt 120">
    Hurry up! There is { auction.timeLeft | time } left.
  </rv-aside>
</section>

The important parts to note here are the attributes prefixed with rv- and portions of text wrapped in { ... }. These are binding declarations and they are the sole way that riba ties data to your templates. The values of these declarations all follow the same minimal and expressive syntax.

(keypath | primitive) [formatters...]

Keypaths get observed and will recompute the binding when any intermediary key changes. A primitive can be a string, number, boolean, null or undefined.

Formatters can be piped to values using | and they follow a similarly minimal yet expressive syntax. Formatter arguments can be keypaths or primitives. Keypath arguments get observed and will recompute the binding when any intermediary key changes.

(formatter) [keypath | primitive...]

Binding

Simply call riba.bind on a template element with some data that you would like to bind.

import { Riba, coreModule } from '@ribajs/core';

const riba = new Riba();
const model = {};

// Register modules
riba.module.register(coreModule.init());

const view = riba.bind(document.getElementById("rv-app"), model);

Every call to riba.bind returns a fully data-bound view that you should hold on to for later. You'll need it in order to unbind it's listeners using view.unbind().

Configuring

Use riba.configure to set the following configuration options for your app. Note that all configuration options can be overridden locally to a particular view if needed.

riba.configure({

  // Attribute prefix in templates
  prefix: 'rv',

  // Preload templates with initial data on bind
  preloadData: true,

  // Root sightglass interface for keypaths
  rootInterface: '.',

  // Template delimiters for text bindings
  templateDelimiters: ['{', '}'],

  // Removes binder attribute after the binder was bound
  removeBinderAttributes: true,

  // Stop binding on this node names
  blockNodeNames: ['SCRIPT', 'STYLE', 'TEMPLATE', 'CODE'],

  // Augment the event handler of the on-* binder
  handler: function(target, event, binding) {
    this.call(target, event, binding.view.models)
  }

})

One-way Binders

One-way binders simply update the DOM when a model property changes (model-to-view only). Let's say we want a simple binder that updates an element's color when the model property changes. Here we can define a one-way color binder as a object with only a routine function. This function takes the element and the current value of the model property, which we will use to updates the element's color.

You can generate a new binder with the Riba CLI.

riba generate binder color

This will generate the binder (and a .spec.ts file) in your ./src/binders directory and updates your ./src/binders/index.ts file.

Than you can change the implementation like this:

import { Binder } from '@ribajs/core';

export class ColorBinder extends Binder<string, HTMLElement> {
  static key = 'color';
  routine(el: HTMLElement, value: string) {
    el.style.color = value;
  }
}

If you use Riba CLI to generate the binder, you usually do not need to register the binder yourself because the CLI updates the ./src/binders/index.ts for you.

Alternatively, you can register the binder by calling riba.module.binder.register with your new binder.

import { Riba } from '@ribajs/core';
import { ColorBinder } from './binders/color.binder';

const riba = new Riba();
riba.module.binder.register(ColorBinder);

With the above binder defined, you can now utilize the rv-color declaration in your views.

<button rv-color="label.color">Apply</button>

Two-way Binders

Two-way binders, like one-way binders, can update the DOM when a model property changes (model-to-view) but can also update the model when the user interacts with the DOM (view-to-model), such as updating a control input, clicking an element or interacting with a third-party widget.

In order to update the model when the user interacts with the DOM, you need to tell Riba.js how to bind and unbind to that DOM element to set the value on the model. Instead of defining the binder with a single routine function, two-way binders are defined as an object containing a few extra functions.

import { Binder } from '@ribajs/core';

export class ToggleBinder extends Binder<boolean, HTMLElement> {
  static key = 'toggle';
  private clickHandler?: () => void;

  bind(el: HTMLElement) {
    const adapter = this.config.adapters[this.key.interface];
    this.clickHandler = () => {
      const value = adapter.read(this.model, this.keypath);
      adapter.publish(this.model, this.keypath, !value);
    };
    el.addEventListener('click', this.clickHandler);
  }

  unbind(el: HTMLElement) {
    if (this.clickHandler) {
      el.removeEventListener('click', this.clickHandler);
    }
  }

  routine(el: HTMLElement, value: boolean) {
    el.classList.toggle('enabled', value);
  }
}

API

One-way formatters

This is by far the most common and practical way to use formatters — simple read-only mutations to a value. Taking the dates example from above, we can define a date formatter that returns a human-friendly version of a date value.

You can generate a new formatter with the Riba CLI.

riba generate formatter date

This will generate the formatter (and a .spec.ts file for tests) in your ./src/formatters directory and updates your ./src/formatters/index.ts file.

Than you can change the implementation like this:

import { Formatter } from '@ribajs/core';

export const dateFormatter: Formatter = {
  name: 'date',
  read(value: Date) {
    return moment(value).format('MMM DD, YYYY')
  },
};

If you use Riba CLI to generate the formatter, you usually do not need to register the formatter yourself because the CLI updates the ./src/formatters/index.ts for you.

Alternatively, you can register the formatter by calling riba.module.formatter.register with your new formatter.

import { Riba } from '@ribajs/core';
import { dateFormatter } from './formatters/date.formatter';

const riba = new Riba();
riba.module.formatter.register(dateFormatter);

You can also register multiple formatters at once by calling riba.module.formatter.registerAll, this is useful when importing multiple formatters like import * as formatters from './formatters';

After you have registered your formatter, formatters are applied by piping them to binding declarations using | as a delimiter.

<span rv-text="event.startDate | date"></span>

Two-way formatters

Two-way formatters are useful when you want to store a value in a particular format, such as a unix epoch time or a cent value, but still let the user input the value in a different format.

Instead of defining the formatter with the single read function, you define it as an object containing read and publish functions. When a formatter is defined only with a read function, riba assumes it to be in the read direction only. When the read and publish functions are defined, riba uses it's read and publish functions to effectively serialize and de-serialize the value.

Using the cent value example from above, let's say we want to store a monetary value as cents but let the user input it in a dollar amount and automatically round to two decimal places when setting the value on the model. For this we can define a two-way currency formatter.

import { Formatter } from '@ribajs/core';

export const CurrencyFormatter: Formatter = {
  name: 'currency',
  read(value: number) {
    return (value / 100).toFixed(2)
  },
  publish(value: string) {
    return Math.round(parseFloat(value) * 100)
  }
};

You can then bind using this formatter with any one-way or two-way binder.

<input rv-value="item.price | currency">

Note that you can also chain bidirectional formatters with any other formatters, and in any order. They read from left to right, and publish from right to left, skipping any read-only formatters when publishing the value back to the model.

Formatter arguments

Formatters can accept any number of arguments in the form of keypaths or primitives. Keypath arguments get observed and will recompute the binding when any intermediary key changes. A primitive can be a string, number, boolean, null or undefined.

<span>{ alarm.time | time user.timezone 'hh:mm' }</span>

The value of each argument in the binding declaration will be evaluated and passed into the formatter function as an additional argument.

import { Formatter } from '@ribajs/core';

export const TimeFormatter: Formatter = {
  name: 'time',
  read(value: Date, timezone: string, format: string) {
    return moment(value).tz(timezone).format(format)
  }
};

Lifecycle callbacks

protected attributeChangedCallback(attributeName: string, oldValue: any, newValue: any, namespace: string | null) {
  super.attributeChangedCallback(attributeName, oldValue, newValue, namespace);
  // Do here what ever you want
}

The built-in adapter

Riba ships with a . adapter for subscribing to properties on plain JavaScript objects. The adapter is implemented with Object.defineProperty-based observation in the core runtime.

Object.observe is obsolete and not used by Riba.

Riba targets modern evergreen browsers. If you have additional compatibility requirements, provide app-level polyfills or a custom adapter strategy in your project.

Creating an adapter

Adapters are defined on riba.adapters with the interface as the property name and the adapter object as the value. An adapter is just an object that responds to observe, unobserve, get and set.

For most projects, the built-in . adapter is enough. Create a custom adapter only if your model API requires custom observe/get/set behavior.

The following : adapter is an example for event-driven model APIs (such as Backbone.js models / Stapes.js modules).

riba.adapters[':'] = {
  observe: function(obj, keypath, callback) {
    obj.on('change:' + keypath, callback)
  },
  unobserve: function(obj, keypath, callback) {
    obj.off('change:' + keypath, callback)
  },
  get: function(obj, keypath) {
    return obj.get(keypath)
  },
  set: function(obj, keypath, value) {
    obj.set(keypath, value)
  }
}

Iterate

Use the rv-each-[item] binder to have Riba.js automatically loop over items in an array and append bound instances of that element. Within that element you can bind to the iterated item as well as any contexts that are available in the parent view.

<ul>
  <li rv-each-todo="list.todos">
    <input type="checkbox" rv-checked="todo.done">
    <span>{ todo.summary }</span>
  </li>
<ul>

Iteration index

To access the index of the current iteration use the syntax %item%, Where item is the name of the model you provided in rv-each-[item]. You can also access the index of the iteration by using the key index but using this will access only the current iterations index. Note that when nesting rv-each's the parent index is still accessible within the scope via the model name.

<ul>
  <li rv-each-user="app.users">
    <span>User Index : { %user% }</span>

    <ul>
        <li rv-each-comment="user.comments">
            <span>Comment Index : { %comment% }</span>

            <span>User Index : { %user% }</span>
        </li>
    </ul>
  </li>
<ul>