Shellfish

Namespace: declarative

declarative

Module ID: shellfish/declarative

This module provides a high-level API with tools for declarative programming in JavaScript.

It is used extensively by the code created by Feng Shui and is rarely used directly. So unless you are sure that you absolutely need to use this module, you may safely ignore it.

Example

Import by module ID

shRequire("shellfish/declarative", declarative =>
{
    ...
});

Classes

DynamicValue
Element

Methods

declarative.binding (deps, evaluator, annotation) static

declarative.js:1103

Creates and returns a dynamic value acting as a binding. This means that it is re-evaluated whenever one of its dependency dynamic values changes.

The evaluation function takes the watched dynamic values as parameters and acts as the value getter of the binding.

Name Type Default Description
deps Array.<declarative.DynamicValue>

The list of dependencies.
evaluator function

The evaluation function to invoke.
annotation string "" optional

A user-defined annotation string that may help for debugging.
Example
const b = declarative.binding([a, b], (aValue, bValue) =>
{
    return aValue.val * bValue.val;
});

declarative.chainRef (root, chain, resolver) static

declarative.js:1214

Creates and returns a dynamic value that references a property of an element. The element does not have to exist yet at the time of calling this function.

If the referenced parameter cannot be resolved immediately, resolving is retried later when the specified root element gets initialized.

The chain parameter consists of a list of identifiers that address a property. For example, to address the property width of an element with ID theBox, the chain would be ["theBox", "width"].

The resolver function is expected to take an element ID string as parameter and return the corresponding declarative-level element, or undefined if it could not be resolved yet (because the element has not yet been created).

A simple resolver might look like

(id) => root.find(id);
Name Type Description
root declarative.Element

The root element.
chain Array.<string>

The chain that makes up the reference.
resolver function

A resolver function.
Example
const b = declarative.chainRef(root, ["theBox", "width"], (id) =>
{
    // do something to lookup the element by ID
    ...
    return element;
});

declarative.element (type)declarative.Element static

declarative.js:789

Creates and returns a declarative-level element wrapping the given mid-level type.

Name Type Description
type function

The element constructor.
Returns:
Type Description
declarative.Element The declarative-level element.
Examples
const e = declarative.element(html.Box);

Trees of elements may be created and parameterized by chaining commands

const tree = declarative.element(html.Box).id("theBox")
             .set("color", "black")
             .add(
                 declarative.element(html.MouseBox)
                 .set("fillWidth", true)
                 .set("fillHeight", true)
                 .set("marginLeft", 12)
                 .set("marginRight", 12)
                 .click((ev) =>
                 {
                     console.log("clicked the box");
                 });
             );

declarative.isDynamicValue (v)bool static

declarative.js:68

Returns if the given object is a dynamic value.

Name Type Description
v object
Returns:
Type Description
bool true if the object is a dynamic value.

declarative.routedElement (el, routeTo)declarative.Element static

declarative.js:818

Creates a routed element from the given element. Children added to the routed element are added to the specified element instead.

Name Type Description
el declarative.Element

The element that is routed.
routeTo declarative.Element

The element that is routed to.
Returns:
Type Description
declarative.Element The routed element.