Tile syntax

The tiles represent the building blocks of Envision’s dashboards. Below, we detail the generic syntax of the tiles, how tiles can be used to export data to files and how descriptive metadata can be attached to those exports.

Syntax overview

The generic inline syntax for a tile is:

show table "hello" a1c2 tomato with
  Category
  Supplier
  sum(StockOnHand)
  sum(StockOnHand * BuyPrice)
  group by [Category,Supplier]
  order by [Category, sum(StockOnHand * BuyPrice)] desc

The first argument after the tile name (table above) is the title of the tile. The title is followed by the tile position and size within the dashboard, encoded as an Excel-like grid (letters refer to column, numbers to lines). Finally, the color is specified, either as one of the web colors, or as their hex name but without the # sign (ex: FF6347 for tomato).

The expressions passed as arguments after the with keyword are automatically aligned by Envision, in order to treat the input data as a table for the tile.

In order to set up the grouping and ordering of lines within this input table, an optional statement can be added at the end of the column list: * The group by statement applies the same grouping to all fields. When group by is used, expressions must expose aggregators (sum(), in the example above). If they are pre-aggregated already, they have to be introduced by the aggregator same(). * The order by statement orders the lines in increasing order. Decreasing order is obtained by the additional optional statement desc.

Both group by and order by are optional and support multiple arguments.

Exporting data

The input table can be exported to a file using the export option:

show table "hello" a1c2 tomato export:"/mytable.tsv" with Category, Supplier, sum(StockOnHand)

The file formats CSV, TSV, XLSX (Excel) and RFF (raw flat file) are supported. If the specified file extension is unknown, then the export will trigger an error.

It is also possible to export the tile in two - or more - locations at once, using multiple export statements:

show table "hello" a1c2 tomato export:"/foo1.tsv" export:"/foo2.tsv" with Category, Supplier, sum(StockOnHand)

In practice, as the entire statement for a tile tends to be long, Envision also provides a tile block syntax with:

show table "hello" a1c2 tomato export:"/foo1.tsv" export:"/foo2.tsv" with
  Category
  Supplier 
  sum(StockOnHand) as "StockQty"
  sum(StockOnHand * BuyPrice) as "Stock Value" unit: "$"
  group by [Category,Supplier]
  order by [Category, sum(StockOnHand * BuyPrice)] desc

Attaching meta descriptions to exports

When a file is produced through Envision, it is possible to attach descriptive metadata to this file and its columns. Those metadata are optional. Those descriptions are intended to facilitate later data manipulation of the file itself by making the descriptions accessible from the Envision code editor itself. Attaching those descriptions can be done with well placed /// triple-slash comment, as illustrated with:

/// Stock value summary table
show table "hello" a1c2 tomato export:"/foo1.tsv" export:"/foo2.tsv" with
  Category
  Supplier 
  /// Stock on hand by category and supplier
  sum(StockOnHand) as "StockQty"
  /// Stock on hand value by category and supplier
  sum(StockOnHand * BuyPrice) as "StockValue" unit: "$"
  group by [Category,Supplier]
  order by [Category, sum(StockOnHand * BuyPrice)] desc

In the Envision code editor, when hovering a variable obtained through a read statement, an attempt is made to locate the originating export which produced the variable. If such originating export statement is found, the descriptive metadata is contextually displayed.

The displayed information is:

The first two details are available also for any new table, vector and scalar, that are created in that very script (ex. day.qty).