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, how descriptive metadata can be attached to those exports, and how to create the slices for a dashboard.

Syntax overview

The generic syntax for a tile is:

show table "my title" a1c2 tomato slices: SX {backgroundColor: "#fdad31"} with
  Category as "My category"
  Supplier as "My supplier"
  sum(StockOnHand)
  sum(StockOnHand * BuyPrice)
  group by [Category,Supplier]
  order by [Category, sum(StockOnHand * BuyPrice)] desc

The elements that compose a tile are as follow:

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 (not just for table tiles, but for all tiles). 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:

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

Envision also offers a concise inline syntax without line returns which is appropriate for simple tiles:

show table "my table" with T.X, T.Y, T.Z

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

Dashboard slicing

Each dashboard is allowed to have a slice set. Slices are numbered internally from 0 to N-1. The identifier of a slice is represented by a special type called slice. To create the slices for a dashboard, use the sliceDashboard function anywhere in the script (but no more than once):

Slice = sliceDashboard(Name) by [Category, Sku]

In this example, there will be one slice for each distinct value of the [Category, Sku] pair. The slice identifier assigned to each value is then inflated back into the original table (here, Items). Selecting a slice (on the dashboard user interface) consists in selecting its internal identifier by means of a form field, using auto-completion to narrow down possible choices until one can be picked. Auto-completion is based on searching through the display text of the slice, which is composed of:

Slice = sliceDashboard(Name, Label) by [Category, Sku] 

Some tiles can be sliced by introducing a slice vector (of the same table as the tile’s actual data) as the slices option, in which each slice will contain only the lines associated with it:

show table "Purchase Orders" slices: Slice with
  PO.OrderId
  PO.Date
  PO.Quantity
  order by PO.Date

Slicing linecharts

Slicing the linechart tile requires a group by argument along with date. This can be done with:

Slice = sliceDashboard(Id, Name) by Id
Day.Slice = Slice
week.Monday = same(monday(date)) into Week

show linechart "Weekly Quantity Sold" slices: Day.Slice with
  sum(week.QtySold) as "Qty Sold"
  group by Week.Monday

Notice how Slice is broadcast on Day.Slice.