Dashborg Documentation / References / Element Reference - Core

Element Reference - Core

All HTML elements are supported except for html, body, meta, base, frameset, title, and applet (<script> tags are supported, but handled in a special way). Most attributes are supported as well except for JavaScript “onX” handlers. The most common scripting handlers are re-implemented as Dashborg handlers.

Displaying Data

<d-text>

Will output a plain text node. If the style attribute is given it will output a <span>.

Attributes

  • bind (data.bind) : bind-expr
  • format : format-expr
    • null - if no format attribute is present it will convert bind-expr to a string
    • “json” - will pretty print bind-expr to JSON.
    • string - any other string will be passed to js-sprintf to format the bind-expr

Format Expr

A format expression helps to format the bound value to a text string. If format is not specified we’ll convert the bound value directly to a javascript string. If it is set to the value “json”, the bound value will be pretty printed to JSON. Otherwise the value will be formatted using the js-sprintf library. Especially useful for formatting numbers, e.g. format="%0.2f" for two decimal places.

<d-dateformat>

Like <d-text> but for formatting timestamps using the Day.js library (moment.js compatible). The bound value should be a epoch (unix) timestamp (in milliseconds). If you have an epoch time for seconds, microseconds, or nanoseconds, use the mode parameter to perform the conversion. The format attribute specifies the moment.js format value. Will output a plain HTML text node. If style attribute is given will output a <span> instead. Was previously called <d-moment>.

Attributes

  • bind (data.bind): bind-expr
  • format - an format expression to pass to moment.js. e.g. MMMM Do YYYY, h:mm:ss a, MM/DD/YYYY. Can also use “humanize” for durations.
  • relative - set this attribute to output a string comparing the time to now (always uses the “humanize” format). Will output something like “5 min ago”.
  • duration - set this attribute when the bound attribute is a duration (not a static point in time). since this uses time formatting, not recommended for durations longer than 24-hours.
  • mode - used to normalize the bind-expr’s epoch/unix time value. by default, d-moment wants an epoch time in milliseconds. “s” for seconds, “ms” for milliseconds (default), “us” for microseconds, “ns” for nanoseconds.

<d-markdown>

Still experimental. Be careful when using d-markdown. Leading whitespace matters to markdown, so you must not indent your markdown lines to line up with your normal HTML indentation. Uses an XSS safe version of Github’s markdown format. Should only be used for very simple markdown. Do not use HTML tags within d-markdown, there is an interaction with Dashborg’s HTML parser.

Attributes

  • html-children - can only contain text. the text is the markdown to render. Note you cannot use any HTML tags in the markdown text (Dashborg’s parser doesn’t know not to parse them).

Control Flow

<d-if> / <if>

Use to conditionally render its children. If the condition evaluates to a false-y value there will be no output, otherwise the children will be rendered.

Attributes

  • condition - the value to evaluate. Almost always this attribute should start with * to evalute an expression in the data-odel.
  • html-children - Output to be rendered if condition evaluates to a true-like value.

<if-break>

Use to conditionally render children. It will also prevent any further tags in the block from evaluating. Convenient to render error/special cases.

Attributes

  • condition - the value to evaluate. Almost always this attribute should start with * to evalute an expression in the data-odel.
  • html-children - Output to be rendered if condition evaluates to a true-like value.

<d-foreach> / <foreach>

Loops over the bound value (assuming it is an array). On each iteration, it will evaluate its children and set their local data-context to the current array value.

Attributes

  • bind (data.bind): bind-expr - the list/array to iterate over. If the expression evaluates to null, there will be no output. If the expression does not evaluate to an array, then it will be treated like a 1-element array (one iteration of the loop will run).
  • html-children - content to be evaluated on every iteration

Misc

<d-data>

Adds data to the frontend data model. Queries will be re-fetched under two conditions: an “invalidation” of the data handler using InvalidateData() / invalidate_data(), or if querydata changes.

Attributes

  • output.bindpath (bindvalue) - where to write the data into the frontend data model
  • query - a backend data handler (must start with /).
  • querydata - arguments to pass to query data handler

<d-inlinedata>

Adds data to the frontend data model by parsing its innerHTML text. By default it uses a strict JSON format, but you can specify “js-eval” to use JavaScript syntax to define your data. If you use “js-eval” and define a function, that function will be called to produce the data.

It is best to keep inlinedata nodes at the top-level of your app’s HTML (or somewhere where they do not interact with components, if, and foreach nodes). They normally will only run once, but their behavior is undefined when removed and added to the element tree.

Attributes

  • output.bindpath (bindvalue) - where to write the data into the frontend data model
  • format - how to evaluate the text. either “json” or “js-eval” (default is “json”).
  • child-elements - JSON data to write to bindvalue - only if query is not specified

Examples:

<d-inlinedata output.bindpath="$.mydata">
{"x": 5, "y": [1,2,3]}
</d-inlinedata>

<d-inlinedata output.bindpath="$.mydata2" format="js-eval">
{x: 5, y: [1,2,3]}
</d-inlinedata>

<d-inlinedata output.bindpath="$.mydata3" format="js-eval">
function() {
    let y = [1,2,3];
    return {x: 5, y: y};
}
</d-inlinedata>

<d-datasorter>

Will do a simple sort on data and write the sorted data to a new spot in the data model. If used in the “inplace” mode, it will sort the data in-place and overwrite the existing data. Note that the input “data” attribute must be a “bindpath” to use inplace mode.

Attributes

  • sortspec (sortspec.bind, sortspec.bindpath): how to sort the data. sortspec is an object with two fields “column” for the column to sort by and “asc” a boolean for ascending or decending. e.g. {“column”: “email”, asc: true}
  • data.bind (or data.bindpath for inplace mode): the data to sort. must be an array.
  • output.bindpath - where to write the sorted data (unless inplace is set). note that it is undefined if output.bindpath is the same as data.bind and inplace is not set.
  • inplace - sort the data inplace (data must be a bindpath).

Here’s an example of a datasorter working with a table control. Note that the table will write to sortspec. The sortid in the columns is written to the “column” of the sortspec.

...

<d-datapager>

Will paginate data in the frontend.

Attributes

  • pagespec.bindpath - output by datapager with metadata about the pagination (for displaying paging controls). The pagespec is an object with these fields: start, num, pagesize, curpage, total, hasnext, hasprev, and lastpage. An external component can set curpage to force the datapager to repaginate the data (paging controls bindpath to pagespec.curpage).
  • bind (data.bind, data.bindpath) - The data to paginate
  • output.bindpath - Where to write the output data
  • pagesize - page size (defaults to 10 if <= 0).

Here’s an example of a datapager working with a pagination control working with a table control. Note that the pagination control needs to read the pagespec and write to pagespec.curpage. table “startrownum” is set to automatically correct @index.

...

<d-dyn>

Used to display dynamic HTML content. The bound value will be converted to a string, then parsed as Dashborg HTML and rendered inside of the d-dyn tag. There may be a short delay as the HTML is evaluated asynchronously. The <dyn> tag evaulates to a HTML fragment and disappears from the rendered output so it cannot be styled.

Use of this element is usually not necessary (it is often better to include the static HTML and show/hide it using conditionals), but some use cases will require it (e.g. the Dashborg Playground).

Attributes

  • bind (data.bind): bind-expr* - the data model value to evaluate as Dashborg HTML and render

Special Processing

If you add a class that starts with “no-” it will not be added as a class, instead it will remove the class named without the “no-”. e.g. adding the class “no-primary” will remove the “primary” class if it already exists.

Any CSS style property may be written as an attribute instead if you prefix it with “style.”. So <div style="font-weight: bold"> is equivalent to <div style.font-weight="bold">. Individual classes can be turned on/off using a similar syntax “class.”. So <div class="foo"> is equivalent to <div class.foo="*true">.

Any attribute or CSS property that begins with a * will be evaluated in the panel’s data model as a data-expr.

CSS properties may not contain the ‘;’ character. This means certain “data” URLs with content-types, and other URLs will are not allowed in Dashborg CSS. They can be added in the data model and be referenced using the * syntax.