Dashborg Documentation / References / Expression Reference

Expression Reference

Dashborg 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 expression are always evaluated:
<d-text bind="$.data.x"/>:                =>   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">

<d-foreach bind="[1,2,3,$.data.x]">       =>   2
  <d-text bind=". * 2">                        4
</d-foreach>                                   6
                                               10

Specifying Data Paths

All data paths start with “$”, “.”, or “@”. For most data references you use $, but when iterating over data you’ll often be using . (foreach, table, lists), and @ is for special contextual values.

  • $ - Accesses data from the data root (e.g. $.data.rows or $.state.open).
  • . - Binds to “local” data (e.g. in a d-foreach, d-table, or d-list).
  • @ - Binds to contextual data (e.g. @rownum or @value).

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"]).

Literals

  • Strings - can be either single or double quoted. Remember normal HTML entity encoding applies before any Dashborg processing so &quot; 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
  • Note that true, false, and null, are keywords (not allowed for identifiers, dot-notation, or unquoted map keys).

Operators

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

Operator Type Op Notes
Ternary Conditional ? : [conditional-expression] ? [true-value] : [false-value]
NullishCoalescing ?? Like || but returns first non-null value (instead of first truthy value). See Nullish Coalescing Reference (Mozilla)
Logical Or || Short circuits. Returns first truthy value, or false
Logical And && Short circuits. Returns first value if falsey, otherwise returns second value.
Equality ==, != Shallow equality tests
Relational >=, <=, >, <
Additive +, - + will work with strings for concatenation
Multiplicative *, /, %
Unary !, -, +

Functions

More functions may be added in the future. To call a function you use fn:[function-name]([arguments]), e.g. fn:deref($.data.expr).

Function Notes
fn:deref 1 argument, converts argument to a string and evalutes it as an expression.
fn:len 1 argument. arrays: length, objects/maps: length, scalars: 1, null: 0
fn:index 2 arguments, strings, calls arg1.indexOf(arg2)
fn:slice 3 arguments. first argument is an array, 2nd is start element (inclusive), 3rd element is end element (exclusive). See Array.slice
fn:int converts argument to integer (truncates floats and converts strings to integer or NaN). See parseInt
fn:float converts argument to floating point number (converts strings to float or NaN). See parseFloat
fn:js call an external js function. 1+ arguments, first argument is a string, rest of the args get converted to a parameter list. window[arg1].apply(null, args2-n)
fn:split splits a string into an array. 1st argument is string to split, 2nd argument is string to split on.
fn:ts equivalent to javascript Date.now() (unix timestamp millis)
fn:substr arg1.substr(arg2, arg3)
fn:sprintf sprintf(arg1, …)
fn:startsWith arg1.startsWith(arg2)
fn:match creates a regex with arg2 and and arg3 as options. tries to match arg1.
e.g. arg1.match(new Regexp(arg2, arg3))

Special Data Roots

Data Root Notes
$ Alias for $data
. Alias for $local
@ Alias for $context
$data Returns root of frontend data model
$state Returns root of panel state – passed to all handlers
$local Returns local data – localdata is set by loops, tables, lists, datacontext, etc.
$context Returns contextual data – e.g. iteration index (@index), or input value in data (@value)
$localstack Returns an array (stack) of local data. Used for nested loops to access outer loop’s data: $localstack[1]
$contextstack Returns an array (stack) of context data. Used for nested loops to access outer loop’s data: $contextstack[1].index

Handler Statements

Dashborg handlers (handler, onclickhandler, onchangehandler, etc.) execute statements. There are three types of statements:

  • Call Handler
  • Invalidate Data
  • Assignment

Statements must be terminated with a ;.

Call Handler Statement

Here are some examples of calling panel handlers:

/handler/path;
/select/item(.ItemId);
/complex/run-handler([{x: 5, y: 10}, "hello"]);
@rtnval = /handler/path;

call "/test-handler", [1, 2, 3];
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.

Invalidate Data

Same as the req.InvalidateData() call on the backend. The argument to invalidate data is a string or array of strings for regular expressions of data handlers to invalidate. If you do not pass any expressions it will invalidate all data handlers (including blobs).

invalidate "/job-by-id";
invalidate "/test-handler/" + $state.handlername;
invalidate;

Assignment

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;

Expressions

Raw expressions can be statements. This is only useful if your expression has side effects. Useful in conjunction with fn:js.

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

Fire Statement

When writing components (inside of <define-component>) you can use the “fire” statement to trigger an event on the calling element. This lets you transmit a click event from an element inside of your component to the caller.

fire @node->onclickhandler();
fire @node->customhandler({val: 55});
fire @node, "customhandler", {val: 22};

<!-- here we define a component that when clicked will "fire" customhandler on the caller -->
<define-component name="primary-button" dashelem>
    <div class="ui primary button" onclickhandler="fire @node->oncustomhandler();">
        <d-children bind="@node.all"/>
    </div>
</define-component>

<!-- here's the caller, who can define a custom handler that will be called when the button gets clicked -->
<local-primary-button oncustomhandler="...">Click Me</local-primary-button>

Switch Apps

switchapp("app2", {accid: $.accountid});
switchapp("app4");
pushapp("app3", {x: 5});
popapp();

Misc Statements

// reports an error to the Dashborg Chrome
reporterror "error value";

// throws an exception (which can be caught) or displayed in the Dashborg Chrome
throw "exception value";

// writes some data to console.log() for debugging.
log $.somedata;
log "a string";