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)
group by [Category,Supplier]
order by [Category, sum(StockOnHand * BuyPrice)] desc

The elements that compose a tile are as follow:

• a tile type - table here above - which defines the type of tile to be displayed.
• a tile title - my title here above - which defines a label intended to display prominently.
• a tile position (optional) - a1c2 here above - which defines both the tile and its size within the dashboard over an Excel-like grid: letters refer to column, numbers to lines.
• a tile color (optional) - tomato here above - which is expected to either a named web colors, or as a hex color name but without the # sign (ex: FF6347 for tomato).
• a slice option (optional) - a slices: SX here above - which indicates that the tile display depends on the selected slice.
• a stylecode expression (optional) - {backgroundColor: "#fdad31"} - which is delimited by { and }, and which configures the display behavior of the tile (check out StyleCode reference).

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:

• 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. In addition, order by supports multiple arguments with multiple directions, e.g.:

show table "my table" with
T.X
T.Y
T.Z
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:"/mytable.tsv" with Category, Supplier, sum(StockOnHand)

Supported export formats are:

• .csv and .tsv flat files,
• .csv.gz and .tsv.gz compressed flat files,
• .ion internal Lokad file format, “Ionic”,
• .xlsx Excel files ; the sheet name can be specified in braces after the name: foo.tsv{Sheet A}.

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.

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 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 variable data type
• the table name and its keys (ex. Orders[Id, Date, *])
• the path of the script where the variable was written
• the documentation specified about the table
• the documentation specified about the specific variable.

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:

• the Name value, which should be the same for all lines in a slice
• on a second line, the optional label passed as argument (and which must, again, be the same for all lines in a given slice).
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 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.