Expression Reference

Hibiki HTML features a full expression language to bind your HTML to the frontend data model. Some attributes like bind use expressions directly. Other attributes, and style declarations are just plain strings and are not evaluated by default. Any attribute or style property can be evaulated by using a * as it’s first character.

Here are some examples:

Assuming that $.data = {x: 5, y: 20}

# bind expressions are always evaluated:
<h-text bind="$.data.x"></h-text>:        =>   5

# normal attributes and style properties are not evaluated
<div a="1" style="font-size: 14px">       =>   <div a="1" style="font-size: 14px">

# using a * will turn any attribute or style property into an expression
# like React, Dashborg will add "px" to numbers for CSS attributes where that makes sense.

<td colspan="*$.data.x">                  =>   <td colspan="5">
<div style="font-size: *$.data.y">        =>   <div style="font-size: 20px">
<div style="height: *$.data.x + '%'">     =>   <div style="height: 5%">
<div style="font-weight: *$.data.x > 2 ? 'bold' : 'normal'">  => <div style="font-weight: bold">

# inside of a foreach loop, $local is bound to each value in sequence
<h-foreach bind="[1,2,3,$.data.x]">       =>   2
  <h-text bind="$local * 2"></h-text>          4
</h-foreach>                                   6
                                               10

All data paths start with “$” or “@”. $ is used for data roots and @ is for special contextual values.

• $ - Accesses data from the data root (e.g. $.data.rows or $.state.open).
• @ - Binds to contextual data (e.g. @rownum or @value).
• $c - Binds to component data (data local to a component)
• $state - Binds to Hibiki HTML state data (url params, page title, other internal Hibiki HTML data).

After you specify the root, you can access array elements by using square brackets with numeric values ($.array[0], $.array[4], $.array[$.data.index]) and you can access map fields using dot notation or square brackets with string values ($.data.map.x, $.data.map.bar, $.data.map["y"]).

• Strings - can be either single or double quoted. Remember normal HTML entity encoding applies before any Dashborg processing so " becomes a quote character.
  • Double Quoted - Allow escapes using \. Use \n for newlines (n, b, f, r, t, v are valid escapes). Can also be used to escape any other character (most useful for escaping double quotes ").
  • Single Quoted - No escapes allowed.
• Numbers - integers and floating point numbers, base 10 format, no exponents. (regexp: /[-+]?[0-9]*\.?[0-9]+/).
• Arrays - Use square brackets, comma separated values, trailing comma is okay. ([2, "hello", 5, ]).
• Maps - Use braces, colon after keys, commas between key-values, trailing comma is okay. Use quotes for keys that are not identifier safe. ({x: 5, "abc#foo": 10}).
• true, false - for boolean values.
• null - no value
• noattr - special null value that when passed as an attribute makes it appear that the attribute was not specified (see noattr/isnoattr below).
• Note that true, false, and null, are keywords (not allowed for identifiers, dot-notation, or unquoted map keys).

These are the supported Dashborg operators, listed in increasing precedence order:

To call a function you use fn:[function-name]([arguments]), e.g. fn:len($.data.expr). Function names are not case sensitive.

Requires 2 arguments, the two values to be compared. Returns -1, 0, or 1 if the first argument is less than, equal to, or greater than the 2nd argument (respectively). The named parameters affect the comparison:

Named Parameters:

• type (string) - “numeric” or “string”. if null, the comparison will be based on the types of the arguments. If both are numbers, then it will be a numeric comparison, otherwise string. nulls will always sort before any value in either type.
• locale (string) - override the locale of the comparison (otherwise uses the browser’s locale value). e.g. for french should use “fr”.
• sensitivity (string) - “base”, “accent”, “case”, or “varient”. See Intl Collator Docs. By default it is set to “varient”, but other sensitivity types allow different characters to be treated as equal.
• nocase - sets sensitivity to “accent” (sensitivity option takes precendence). this makes the comparison case-insensitive.
• field - if both arguments are objects, compares the sub-field named field within them. e.g. if you call fn:compare($.foo, $.bar, field=‘test’), it will compare $.foo.test with $.bar.test. if argument is null, or does not contain the specified field, will compare against null.
• index - if both arguments are arrays, compares the sub-index index within them. e.g. if you call fn:compare($.foo, $.bar, index=8), it will compare $.foo[8] with $.bar[8]. if argument is null, or does not contain the specified index, will compare against null.

fn:compare($.v1, $.v2, type="numeric")                # force numeric comparison
fn:compare($.v1, $.v2, type="string", nocase=true)    # force case-insensitive string comparison
fn:compare($.v1, $.v2, field="qty", type="numeric")   # numeric comparison between $.v1.qty and $.v2.qty

# compare $.v1.name with $.v2.name, using rules from french locale.
# comparison will be case-insensitive and will ignore accents
fn:compare($.v1, $.v2, field="name", locale="fr", sensitivity="base")

Requires 1 argument, the data to be sorted. Returns a new array where the input data is sorted according to the provided arguments.

Named Parameters:

• data (array) - the data to be sorted. can also be passed as the first positional argument.
• sortexpr (lambda) - a lambda expression that overrides the built in compare function. Gets two context variables @a (first value), and @b (second value). Should return -1, 0, or 1.
• desc (boolean) - if true, will reverse the sort order
• makerefs (boolean) - if true, will create a sorted array of references that point back to the original array elements.
• slice ([number, number]) - a one or two element array to slice the final array. same arguments as fn:slice().
• nosort (boolean) - if set to true, do not sort the array (just return a copy).
• (any parameter that can be passed to fn:compare) - these parameters are passed to fn:compare() when comparing values. not used if sortexpr is provided.

fn:sort($.data)                               // sorts data naturally using fn:compare() function
fn:sort($.data, field="qty", type="numeric")  // sort objects using field "qty" numerically
fn:sort($.data, makerefs=true)                // returns array of references to original array
fn:sort($.data, field="qty", desc=true)       // sort objects using field "qty", reverse order
fn:sort($.data, slice=[10,20])                // sort data naturally, return elements 10-19

Hibiki HTML handlers (handler, click.handler, change.handler, mount.handler, init.handler, etc.) execute actions. The Hibiki HTML parser will convert these action statements into Hibiki Actions. Every action that can be parsed can also be represented as JSON and vice-versa.

Statements must be separated with a ;. Trailing ; is allowed.

Used to set values into the data model. Note you can only set values into $data ($), $state, or $context (@). Context values are local to the handler block (just used for temporary variables).

$state.x = 5;
$.job = {jobid: 22, jobname: "Test Job"};
@temp = 5 * $state.val;
@temp2 = @temp * @temp;
$.newval = @temp2;
@foo = /test/handler;

Used to return values from a handler. Does not terminate the running handler, just sets the return value.

setreturn(5);
setreturn({x: 10, y:20});
setreturn(null);

Call handlers always start with /. They consist of 3 parts, an optional module, an optional path, and an optional path fragment. Either module or path must be specified (path will default to /).

/@[module-name]/[path]:[pathfrag]

Handlers can take an optional parameter list of data. Data is specified as key = value pairs separated by commas (trailing commas are allowed). Positional parameters are also allowed before any key/value pairs, and will be placed into a special data key named *args. Some handlers allow special ‘@'-key parameter values..

Here are some example paths, with and without arguments:

# simple path, no module, no arguments
/handler/path

# 'fetch' module, 'get' pathfrag, path defaults to '/'.
# 1 positional argument, 3 key-value arguments passed.  'x', and 'y' are normal, @method is a special parameter
/@fetch:get('/api/test', @method='post', x=10, y=20)

# no module, 2 positional parameters, one key-value parameter
/complex/run-handler(5, 10, userid=$.userid);

# can assign the return value from handlers to the data model
$.index = /api/get-index(partid=22)

# using the 'call' keyword, we can construct dynamic call paths
# arguments and return values work the same.
call "/test-handler" (x=10, @method='post');
call "/test" + $state.handlername, (x = $state.x, y = $state.y);
@rtnval = call "/test/handler";

Note that handlers are not expressions, so only simple assignment works, you can’t write @foo = /test + 5.

Fire an event that triggers event handlers. Parameters can be name-value pairs which will create context (@vars) in the callee. A single positional parameter will set the ‘value’ key. Adding the @bubble at-param will make the event bubble.

fire->click;
fire->custom1();
fire->submit(itemid=22, price=100, @bubble=true)
fire->custom2(@bubble=true);
fire->custom3(88)

Throws an error. Takes one argument which will be evaluated as a string (the error message):

throw("Invalid User Id");
throw("No value is set");

Logs a sequence of positional arguments to the JavaScript console. If @debug is true, it will output extra debugging information and a Hibiki/JavaScript call stack. If @alert is true, it will cause a browser alert.

log("the value is", $.value);
log("show stack trace", @debug=true);
log("Not Logged In!", @alert=true);

if/then/else implementation. Parenthesis around the conditional expression, Braces are required around the then/else statement blocks, else statement is optional. If statements require a ; to separate them from subsequent statements;

if ($.primary) { $.openpopup = true; };
if ($.color == 'blue') { $.blue = true } else { $.red = true };

Does nothing.

nop;
nop();

Raw expressions can be statements. This is only useful if your expression has side effects. Useful in conjunction with fn:js. There is no “expr” JSON action, instead you can use a “setdata” action with a null setpath.

expr fn:js('external_fn_name', 55);
expr fn:js('alert', 'hello');