ConstraintJS API

cjs is ConstraintJS's only visible object; every other method an property is a property of cjs. The cjs object itself can also be called to create a constraint object.

Create an array constraint

arrayDiff returns an object with attributes: removed, added, and moved. Every item in removed has the format: {item, index} Every item in added has the format: {item, index} Every item in moved has the format: {from_index, to_index} Every item in index_changed has the format: {from_index, to_index}

When oldArray removes every item in removed, adds every item in added, and moves every item in moved (in that order), it will result in an array that is equivalent to newArray. Note: this function is used internally to determine how to keep DOM nodes in sync with an underlying model with the smallest number of modifications to the DOM tree.

Constrain a DOM node's attribute values

Constrain a DOM node's CSS style

Constrain a DOM node's children

Constrain a DOM node's class names

Constrain a DOM node's HTML content

Constrain a DOM node's text content

Constrain a DOM node's value

Constraint constructor

Parses a string and returns a constraint whose value represents the result of evaling that string

Create a new template. If context is specified, then this function returns a DOM node with the specified template. Otherwise, it returns a function that can be called with context and [parent] to create a new template.

ConstraintJS templates use a (Handlebars)[http://handlebarsjs.com/]. A template can be created with cjs.createTemplate. The format is described below.

Basics

ConstraintJS templates take standard HTML and add some features

Constraints

Unary handlebars can contain expressions.

 <h1>{{title}}</h1>
 <p>{{subtext.toUpperCase()+"!"}}</p>

called with { title: cjs('hello'), subtext: 'world'}:

<h1>hello</h1>
<p>WORLD!</p>

Literals

If the tags in a node should be treated as HTML, use triple braces: {{{ literal_val }}}. These literals (triple braces) should be created immediately under a DOM node.

 <h1>{{title}}</h1>
 <p>{{{subtext}}}</p>

called with { title: cjs('hello'), subtext: '<strong>steel</strong city'}:

<h1>hello</h1>
<p><strong>steel</strong> city</p>

Comments

{{! comments will be ignored in the output}}

Constraint output

To call my_func on event (event-name), give any targets the attribute:

data-cjs-on-(event-name)=my_func

For example:

<div data-cjs-on-click=update_obj />

Will call update_obj (a property of the template's context when this div is clicked.

To add the value of an input element to the template's context, use the property data-cjs-out:

<input data-cjs-out=user_name />
<h1>Hello, {{user_name}}</h1>

Block Helpers

Loops

To create an object for every item in an array or object, you can use the {{#each}} block helper. {{this}} refers to the current item and @key and @index refer to the keys for arrays and objects respectively.

{{#each obj_name}}
    {{@key}}: {{this}}
{{/each}}

{{#each arr_name}}
    {{@index}}: {{this}}
{{/each}}

If the length of the array is zero (or the object has no keys) then an {{#else}} block can be used:

{{#each arr_name}}
    {{@index}}: {{this}
    {{#else}}
        <strong>No items!</strong>
{{/each}}

Conditions

The {{#if}} block helper can vary the content of a template depending on some condition. This block helper can have any number of sub-conditions with the related {{#elif}} and {{#else}} tags.

{{#if cond1}}
    Cond content
{{#elif other_cond}}
    other_cond content
{{#else}}
    else content
{{/if}}

The opposite of an {{#if}} block is {{#unless}}: {{#unless logged_in}} Not logged in! {{/unless}

State

The {{#fsm}} block helper can vary the content of a template depending on an FSM state

{{#fsm my_fsm}}
    {{#state1}}
        State1 content
    {{#state2}}
        State2 content
    {{#state3}}
        State3 content
{{/fsm}}

With helper

The {{#with}} block helper changes the context in which constraints are evaluated.

{{#with obj}}
    Value: {{x}}
{{/with}}

when called with { obj: {x: 1} } results in Value: 1

Partials

Partials allow templates to be nested.

var my_temp = cjs.createTemplate(...);
cjs.registerPartial('my_template', my_temp);

Then, in any other template,

{{>my_template context}}

Nests a copy of my_template in context

Destroy a template instance

Create an FSM

Gets the value of an object regardless of if it's a constraint (standard, array, or map) or not.

Create a new constraint whose value changes by state

Take an input element and create a constraint whose value is constrained to the value of that input element

Determine whether an object is an array constraint

Determine whether an object is a constraint

Determine whether an object is an FSM

Determine whether an object is a map constraint

Memoize a function to avoid unnecessary re-evaluation. Its options are:

• context: The context in which func should be evaluated
• run_on_create: Whether to run func immediately after creating the live function. (default: true)
• pause_while_running: Whether to explicitly prevent this live function from being called recursively (default: false)
• on_destroy: A function to call when destroy is called (default: false)

The return value of this method also has two functions:

• pause: Pause evaluation of the live function
• resume: Resume evaluation of the live function
• run: Run func if it's invalid

Create a map constraint

Memoize a function to avoid unnecessary re-evaluation. Its options are:

• hash: Create a unique value for each set of arguments (call with an argument array)
• equals: check if two sets of arguments are equal (call with two argument arrays)
• context: The context in which getter_fn should be evaluated
• literal_values: Whether values should be literal if they are functions

The return value of this method also has two functions:

• each: Iterate through every set of arguments and value that is memoized
• destroy: Clear the memoized values to clean up memory

Restore the previous value of cjs

Create a new event for use in a finite state machine transition

Pause dynamic updates to a template

Register a custom partial that can be used in other templates

Options are (only createNode is mandatory):

• createNode(...): A function that returns a new dom node any time this partial is invoked (called with the arguments passed into the partial)
• onAdd(dom_node): A function that is called when dom_node is added to the DOM tree
• onRemove(dom_node): A function that is called when dom_node is removed from the DOM tree
• pause(dom_node): A function that is called when the template has been paused (usually with pauseTemplate)
• resume(dom_node): A function that is called when the template has been resumed (usually with resumeTemplate)
• destroyNode(dom_node): A function that is called when the template has been destroyed (usually with destroyTemplate)

Register a partial that can be used in other templates

Remove the edge going from fromNode to toNode

Resume dynamic updates to a template

Tells the constraint solver it is ready to run any onChange listeners. Note that signal needs to be called the same number of times as wait before the onChange listeners will run.

Print out the name and version of ConstraintJS

Unregister a partial for other templates

The version number of ConstraintJS

Tells the constraint solver to delay before running any onChange listeners

Note that signal needs to be called the same number of times as wait before the onChange listeners will run.

Note: The preferred constructor for arrays is cjs.array

This class is meant to emulate standard arrays, but with constraints It contains many of the standard array functions (push, pop, slice, etc) and makes them constraint-enabled.

x[1] = y[2] + z[3] === x.item(1, y.item(2) + z.item(3))

Options:

• equals: the function to check if two values are equal, default: ===
• value: an array for the initial value of this constraint

Any iterator in forEach can return this object to break out of its loop.

The concat() method returns a new array comprised of this array joined with other array(s) and/or value(s).

Clear this array and try to clean up any memory.

Return true if filter against every item in my array is truthy

The filter() method creates a new array with all elements that pass the test implemented by the provided function.

The forEach() method executes a provided function once per array element.

Returns the first index of item

Returns the first item where calling filter is truthy

Convert my value to a standard JavaScript array

Return a constraint whose value is bound to my value for key

The join() method joins all elements of an array into a string.

Returns the last index of item

Returns the last item where calling filter is truthy

Get the length of the array.

The map() method creates a new array (not array constraint) with the results of calling a provided function on every element in this array.

The pop() method removes the last element from an array and returns that element.

The push() method mutates an array by appending the given elements and returning the new length of the array.

The reverse() method reverses an array in place. The first array element becomes the last and the last becomes the first.

Change the equality check; useful for indexOf

Replaces the whole array

The shift() method removes the first element from an array and returns that element. This method changes the length of the array.

The slice() method returns a portion of an array.

Return true if filter against any item in my array is truthy

The sort() method sorts the elements of an array in place and returns the array. The default sort order is lexicographic (not numeric).

The splice() method changes the content of an array, adding new elements while removing old elements.

Converts this array to a JavaScript array

The toString() method returns a string representing the specified array and its elements.

The unshift() method adds one or more elements to the beginning of an array and returns the new length of the array.

A binding calls some arbitrary functions passed into options. It is responsible for keeping some aspect of a DOM node in line with a constraint value. For example, it might keep an element's class name in sync with a class_name constraint

Stop updating the binding and try to clean up any memory

Pause binding (no updates to the attribute until resume is called)

Resume binding (after pause)

Require at least min_delay milliseconds between setting the attribute

Note: the preferred way to create this object is with the cjs.on function Creates an event that can be used in a finite-state machine transition

Add a transition to my list of transitions that this event is attached to

When I fire, go through every transition I'm attached to and fire it then let any interested listeners know as well

Remove a transition from my list of transitions

Create a transition that calls filter whenever it fires to ensure that it should fire

Note: The preferred way to create a constraint is with the cjs.constraint function (lower-case 'c') cjs.Constraint is the constructor for the base constraint. Valid properties for options are:

• auto_add_outgoing_dependencies: allow the constraint solver to determine when things depend on me. default: true
• auto_add_incoming_dependencies: allow the constraint solver to determine when things I depend on things. default: true
• cache_value: whether or not to keep track of the current value. default: true
• check_on_nullify: when nullified, check if my value has actually changed (requires immediately re-evaluating me). default: false
• context: if value is a function, the value of this, when that function is called. default: window
• equals: the function to check if two values are equal, default: ===
• literal: if value is a function, the value of the constraint should be the function itself (not its return value). default: false
• run_on_add_listener: when onChange is called, whether or not immediately validate the value. default: true

Absolute value constraint modifier

Arccosine

Addition constraint modifier

Returns the last value in the array [this].concat(args) if every value is truthy. Otherwise, returns false. Every argument won't necessarily be evaluated. For instance:

• x = cjs(false); cjs.get(x.and(a)) does not evaluate a

Arcsin

Arctan

Arctan2

Bitwise not operator

Ceil

Cosine

Removes any dependent constraint, clears this constraints options, and removes every change listener. This is useful for making sure no memory is deallocated

Division constraint modifier

Equals unary operator

Strict equals operator

Exp (E^x)

Floor

Get the current value of this constraint. For computed constraints, if the constraint is invalid, its value will be re-computed.

Inline if function: similar to the javascript a ? b : c expression

Change this constraint's value in different states

Object instance check modifier

Mark this constraint's value as invalid. This signals that the next time its value is fetched, it should be recomputed, rather than returning the cached value.

An invalid constraint's value is only updated when it is next requested (for example, via .get()).

Find out if this constraint's value needs to be recomputed (i.e. whether it's invalid).

An invalid constraint's value is only updated when it is next requested (for example, via .get()).

Natural Log (base e)

Max

Min

Multiplication constraint modifier

Negative operator

Not equals operator

Not strict equals binary operator

Not operator

Removes the first listener to callback that was created by onChange. thisArg is optional and if specified, it only removes listeners within the same context. If thisArg is not specified, the first callback is removed.

Call callback as soon as this constraint's value is invalidated. Note that if the constraint's value is invalidated multiple times, callback is only called once.

Returns the first truthy value in the array [this].concat(args). If no value is truthy, returns false. Every argument won't necessarily be evaluated. For instance:

• y = cjs(true); cjs.get(y.or(b)) does not evaluate b

Signal that this constraint's value will be computed later. For instance, for asyncronous values.

Coerce an object to a number

Power

Property constraint modifier.

Removes every dependency to this node

Signal that this Constraint, which has been paused with pauseGetter now has a value.

Round

Change the current value of the constraint. Other constraints that depend on its value will be invalidated.

Change how this constraint is computed (see Constraint options)

Sine

Square root

Subtraction constraint modifier

Tangent

Float conversion constraint modifier.

Integer conversion constraint modifier.

Object type modifier

Note: The preferred way to create a FSM is through the cjs.fsm function This class represents a finite-state machine to track the state of an interface or component

The name of this FSM's active state

Changes the active state of this FSM. This function should, ideally, be called by a transition instead of directly.

Create states and set the current "chain state" to that state

Add a transition between two states

Remove all of the states and transitions of this FSM. Useful for cleaning up memory

Returns the name of the state this machine is currently in. Constraints that depend on the return value will be automatically updated.

Check if the current state is state_name

Remove the listener specified by an on call; pass in just the callback

Call a given function when the finite-state machine enters a given state. spec can be of the form:

• '*': any state
• 'state1': A state named state1
• 'state1 -> state2': Immediately after state1 transitions to state2
• 'state1 >- state2': Immediately before state1 transitions to state2
• 'state1 <-> state2': Immediately after any transition between state1 and state2
• 'state1 >-< state2': Immediately before any transition between state1 and state2
• 'state1 <- state2': Immediately after state2 transitions 2 state1
• 'state1 -< state2': Immediately before state2 transitions 2 state1
• 'state1 -> *': Any transition from state1
• '* -> state2': Any transition to state2

Specify which state this FSM should begin at.

Note: the preferred way to create a map constraint is with cjs.map This class is meant to emulate JavaScript objects ({}) but with constraints

Options:

• hash: a key hash to use to improve performance when searching for a key (default: x.toString())
• valuehash: a value hash to use improve performance when searching for a value (default: false)
• equals: How to check for equality when searching for a key (default: ===)
• valueequals: How to check for equality when searching for a value (default: ===)
• value: An optional starting value (default: {})
• keys: An optional starting set of keys (default: [])
• values: An optional starting set of values (default: [])
• literal_values: True if values that are functions should return a function rather than that function's return value. (default: false)
• create_unsubstantiated: Create a constraint when searching for non-existent keys. (default: true)

Any iterator in forEach can return this object to break out of its loop.

Clear every entry of this object.

Clear this object and try to clean up any memory.

Get every key and value of this object as an array.

The forEach() method executes a provided function once per entry. If cjs.MapConstraint.BREAK is returned for any element, we stop looping

Get the item at key (like this[key])

Search for a key or create it if it wasn't found

Check if there is any entry with key = key

Get the index of the entry with key = key

Check if this object has any entries

Convert my value to a standard JavaScript object. The keys are converted using toString

Return a constraint whose value is bound to my value for key

Given a value, find the corresponding key

Get the keys on this object.

Move the entry with key key to `index

Move the entry at old_index to index new_index

Set the entry for key to value (this[key]=value)

Remove a key's entry (like delete this[key])

Change the default equality check when getting a key

Change the hash function when getting a key

Change the default value equality check when getting a value

Change the hash function when getting a value

Get the number of entries in this object.

Converts this array to a JavaScript object.

Get the values on this object.