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.
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:
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
order by statement orders the lines in increasing order. Decreasing order is obtained by the additional optional statement
group by and
order by are optional and support multiple arguments.
The input table can be exported to a file using the
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
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.