Core Formatters

Formatter authoring

When writing custom formatters, Riba now passes an optional formatter context as the last argument.

The context is useful for formatters that depend on external state (events, locale, media query, time):

invalidate() reruns the current binding (sync) without changing the observed keypath.
addCleanup(fn, key?) registers cleanup logic that runs automatically on unbind.
on(target, eventName, callback, key?) subscribes and auto-unsubscribes on unbind.

const clockFormatter = {
  name: "clock",
  read(value: string, context?: any) {
    if (context) {
      context.on(windowClockBus, "tick", () => context.invalidate(), "tick");
    }
    return `${value} @ ${new Date().toISOString()}`;
  },
};

Notes:

Existing formatters still work unchanged; the context argument is optional.
Prefer stable keys for long-lived subscriptions ("tick", "changed", ...).
Cleanup is binding-scoped, so subscriptions are disposed when the view unbinds.

Array formatters

contains

Returns true if an object, array or string contains an object, property or substring.

empty

Returns true if a string or array is empty

first

Array formatter to get the first element of an array

get

Get property of object or array by key or index

is-last

Returns true if value index is the last index of the array and returns false if it is not the last index

last

Array formatter to get the first element of an array

random

Formatter to get back a random value of an array

or random number

set

Sets property of object, array or value

size

Returns the size of a string (the number of characters) or an array (the number of elements)

Compare formatters

and

This formatter corresponds to the && operator: a && b.

between

Formatter to check if a value is between two values. This formatter corresponds to the expression: a >= b && a <= c.

egt

Formatter to check if value is equal or greater than another value. This formatter corresponds to the >= operator: a >= b.

elt

Formatter to check if value is equal or lower than another value. This formatter corresponds to the <= operator: a <= b.

eq

Formatter to check if value is equal than another value. This formatter corresponds to the === operator: a === b.

lt

Formatter to check if value is lower than another value. This formatter corresponds to the < operator: a < b.

ne

Formatter to check if value is not equal than another value. This formatter corresponds to the !== operator: a !== b.

not

Formatter to check if value is not true. This formatter corresponds to the ! expression: !a.

or

Formatter to check if the first value is true or the second value is true. This formatter corresponds to the || expression: a || b.

Math formatters

digits

Just get the digits of a string, useful to remove px from css value.

divided-by

Divides an output by a number. The output is rounded down to the nearest integer.

even / uneven

even returns true if the number is even. uneven returns true if the number is uneven.

gcd

Greatest common divisor (GCD) useful to calculate a ratio.

minus

Formatter to subtracts a number.

modulo

Divides an value by a number and returns the remainder.

number

Formatter to parse a string to number.

plus

Formatter to add a number to an value.

times

Formatter to multiplies an value by a number.

Special formatters

args

This special formatter sets his arguments to a function without call them directly

call

Calls a function with arguments

debug

Prints a value to web developer console

default

Sets a default value if the first value is not set

String formatters

append

Appends a string to an existing string

downcase

Converts a string into lowercase

filled

Check if value is a string and not empty

handleize

Formats a string into a handle, useful to use a title string as an id or class attribute

match

Checks if a string matchs regular expression

pluralize

Gets the singular or plural version of a string based on the value of a number. The first parameter is the singular string and the second parameter is the plural string

prepend

Prepends a string to an existing string

replace-first

Replaces the first occurrence of a string with a substring

replace

Replaces all occurrences of a string with a substring

slice

The slice formatter returns a substring, starting at the specified index. An optional second parameter can be passed to specify the length of the substring. If no second parameter is given, a substring until the end will be returned.

strip-html

Strips all HTML tags from a string

strip

Strips tabs, spaces, and newlines (all whitespace) from the left and right side of a string

upcase

Converts a string into uppercase

Type formatters

boolean

Strips tabs, spaces, and newlines (all whitespace) from the left and right side of a string

is-array

Checks if value is an array

is-boolean

Checks if value is a boolean

is-defined

Checks if value is defined

is-number

Checks if value is a number

is-object

Checks if value is a object

is-string

Checks if value is a string

is-undefined

Checks if value is undefined

json

Converts a string into a JSON string

parse

Parses a json string to object

to-string

Parses a value to string