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) as "Stock on hand"
  sum(StockOnHand * BuyPrice) as "Stock value"
  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. In addition, order by supports multiple arguments with multiple directions, e.g.:

show table "my table" with 
  order by [T.X desc, T.Y]

T.X desc would be automatically translated to -T.X, thus will work in case of numbers, yet, will fail for non-number expressions, such as text. T.X desc can be used for both, numbers and non-number expressions.

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 show table tile can be exported to a file using the export option:

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

Supported export formats are:

Two tiles may not export to the same file path. As an exception, they may export to the same Excel file, but not to the same sheet. All the spreadsheets within one Excel file will be alphabetically ordered.

It is also possible to export the tile to several locations at once, using multiple export statements:

show table "hello" a1c2 tomato export:"/foo1.tsv" export:"/foo2.tsv" with
  sum(StockOnHand) as "Stock on Hand"
  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
  /// 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
  order by PO.Date

Slicing linechart tile

Slicing the linechart tile requires a group by argument to specify the date vector against which to plot. This can be done with:

Slice = sliceDashboard(Id, Name) by Id
Week.Slice = Slice
Week.monday := same(monday(date))

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

Notice how Slice is broadcast on Week.Slice.