# Designing dashboards

Envision dashboards are built from smaller units called tiles. These tiles can be adjusted in size and color, and they can be arranged in any way you see fit within the dashboard page. Envision emphasizes high-productivity dashboards, where all the figures that matter to your commerce are arranged into a single page. Even very complex dashboards are typically displayed in less than half a second. In this section, we explain how to design Envision dashboards from scratch.

We will design our first dashboard using the sample dataset. The screenshot below illustrates the dashboard that you should obtain in your Lokad account.

This dashboard is generated with the script detailed below. At this point, the script probably feels a little bit overwhelming. We are going to decompose this script line by line in the following section.

read "/sample/Lokad_Items.tsv" with
SellPrice: number

show label "Hello World" a1f1 tomato

show table "Items" a2 with sum(1)
show table "Orders" b2 with sum(Orders.1)
show table "Min selling price" c2d2 unit: "$" with min(SellPrice) show table "Max selling price" e2f2 unit: "$" with
max(SellPrice)

Week.oamount := sum(Orders.NetAmount)
Week.pamount := sum(PO.NetAmount)
show linechart "Weekly volumes" a3f5 tomato unit: "$" with Week.oamount as "Sold" Week.pamount as "Purchased" show piechart "Sales by brand" a6c8 tomato with sum(Orders.NetAmount) group by Brand show treemap "Stock value by supplier" d6f8 tomato unit: "$" with
Name
group by Supplier

show table "Top Sellers" a9f12 tomato with
Id as "Product ID"
Supplier
StockOnHand
sum(Orders.NetAmount) as "Sold" unit: "$" order by sum(Orders.NetAmount) desc At this point, we suggest to actually log into your Lokad account, click Create Envision Script, copy the script above, and then click Start Run. Once the run completes, click the newly displayed green link among the Recent runs just below the Start Run button. You should have in front of you a dashboard identical to the one above. The dashboard fits into a single page, but every tile can be expanded if clicked on. Click on the large line chart, and the line chart expands to take advantage of your entire browser window. If you click again anywhere in the black area around the expanded tile, the tile shrinks back to its original size. ## Title, position and color The label tile is the simplest tile available in Envision. This tile is a good starting point to understand the common properties shared by all tiles, that is, their title, position and primary color. The label tile merely displays a piece of text specified in the tile, and the font size is adjusted to fit the tile. show label "Hello World" a1f1 tomato All tiles are displayed by using a show statement. This keyword is followed by 4 arguments. The first argument is the tile type. Envision supports many types of tiles, and label is one of these types. In the following section, we review a couple of other types of tiles that are also present in this dashboard. After the tile type comes the title of the tile defined with a string, hence the quote (“) delimiters. Depending on the type of tiles, the display of the title may vary, but the title is frequently displayed at the top of the tile. Then, after the title, comes the position of the tile, written as a1f1 in the example above. Envision adopts an Excel-like grid to position all the tiles, with letters used for the columns and numbers used for the lines. Hence, a1f1 should be interpreted as the cells ranging from the upper left corner A1 to the lower right corner F1. Envision is not case sensitive, so A1F1 is strictly equivalent to a1f1. Finally comes the color, tomato in the example above. The color argument is optional, and when omitted, the color black is used by default. All the named web colors are valid for Envision. Beyond named colors, Envision also accepts any hex triplet with the minor twist that the hash sign (#) should be omitted. For example, 0099CC should be used instead of #0099CC. However, in practice, colors are too tedious to be edited directly from the script editor. ## The tile editor While editing the tiles’ positioning and colors from the script editor is possible, it is not overly practical since the script editor is not visual. As a result, Envision includes a second editor named the tile editor. The tile editor offers the possibility to adjust the titles, positions and colors of every tile, plus a few extra features to speed-up a complete rearrangement of a dashboard when needed. In your Lokad account, go back to the dashboard that has been generated previously, and click on Edit Tiles. A dark overlay appears on every tile, outlining the position coordinates for each of the tiles. The coordinates are expressed following the Excel-grid conventions as discussed above. Click on any tile, the top label tile for example, and you will see that a dialog box appears, allowing you adjust the properties of the tile. You will also notice green-colored plus (+) buttons on the left side of the page. The purpose of these buttons is to insert a blank grid line just above the button. Click on any of the (+) buttons, and you should see that all tiles are shifted downward. Inserting a blank line is practical when one wants to push a section of the dashboard towards the top (and conversely another section towards the bottom). Once you click the (+) button, on the right, a red-colored minus (-) button appears. These red buttons are the counterparts of the green buttons, and they offer the possibility to delete a blank line. The line has to be blank however for the red button to appear, as this protects you against deleting a line that still contains tiles. As a rule of thumb, when coding a script, we suggest not to pay too much attention to the positioning and colors of the tiles. If tiles end up overlapping, Envision automatically rearranges such tiles to make sure that they all remain visible. Thus, there is no risk of incorrectly positioning the tiles. The tile editor is there to give the final visual touch to your dashboard. ## Displaying single-value indicators While displaying a million numbers is easy, displaying 10 numbers worth being read every day is very difficult, as we’ve mentioned previously. One of the most frequent cases when building a dashboard consists of designing a tile that contains only a single value. This behavior is achieved with the table tile. This tile benefits from a special display when the table merely contains a single cell, that is, a 1x1 table. The following script displays 4 distinct indicators, as outlined below with the relevant lines. show table "Items" a2 with sum(1) show table "Orders" b2 with sum(Orders.1) show table "Min selling price" c2d2 unit: "$" with
min(SellPrice)
show table "Max selling price" e2f2 unit: "$" with max(SellPrice) The show table statement starts with the type, title, position and color options; the pattern is identical to the one used for the label tile. These options are followed by the with keywords. For all tiles that contain data, the with keyword indicates that the variables to be included in the tile are to be enumerated. Here, our tiles only contain a single value each, but in the following sections we will see more complex tiles that embed several values. At this point, we have not yet covered the aggregation capabilities of Envision. Without getting into too much detail, let’s note that sum(), min() and max() are aggregators, and that they operate pretty much according to what could be expected from their Excel counterparts. The sum(1) and sum(Orders.1) are probably a bit puzzling. As we have seen when we were doing our first calculations, Envision primarily deals with vectors. Hence sum(1) is a syntactic sugar for the slightly more verbose script variant: OnePerLine = 1 show table "Items" a2 with sum(OnePerLine) In the code snippet above, the vector OnePerLine is defined, and by convention, this vector is part of the items table. Hence, the assignment results in having a value of 1 being assigned to every item, that is, to every line of the items table. Consequently, the sum of all these values gives the total number of items listed in the Items table. Similarly, the sum(Orders.1) is also the equivalent of an alternative snippet: Orders.OnePerLine = 1 show table "Orders" b2 with sum(Orders.OnePerLine) Again, the assignment is a vector operation, where every line of the Orders table gets assigned a value equal to 1. Thus, when summing all these values, the result also gives the total number of lines in the table. For any table, it is valid to write MyTable.42 as a syntactic sugar in order to assign the value 42 to an anonymous vector. The display of the minimum price follows a similar aggregation pattern, however, a careful observation of the dashboard indicates that we have a slightly different visual behavior here. In fact, the selling price is displayed with the dollar sign ($) as the measurement unit for the indicator. The examination of the relevant lines of script hints at how this behavior is achieved.

show table "Min selling price" c2d2 unit: "$" with min(SellPrice) This behavior is achieved through the unit: "$" option in the column line. The unit is typically displayed on the right side of the values, e.g. 42 miles, but a couple of units, more specifically monetary units like $or £ are usually prefixed, and Envision reflects this pattern. ## Displaying a line chart The line chart is also one of the most frequently used tile types in Envision. In this case, as data needs to be aggregated with a periodicity – per day, per week, per month – using the linechart is slightly more complex than the tiles we have seen so far. Let’s review the piece of script that is used to display a line chart. Week.oamount := sum(Orders.NetAmount) Week.pamount := sum(PO.NetAmount) show linechart "Weekly volumes" a3f5 tomato unit: "$" with
Week.oamount as "Sold"
Week.pamount as "Purchased"

The Week table is not a usual table in the sense that it is not a table loaded from the data. As periodic aggregations are frequently encountered in commerce, in Envision, such periodic aggregations are treated as first-class citizens. As a result, operations that involve periodic aggregations are much simpler to implement. However, this specific aspect of the Envision language goes beyond the scope of this document. Let’s just say that Week acts as a recipient where the data is grouped into weekly buckets.

Then, we also have a special assignment := called the scalar assignment. This assignment differs from the regular = assignment because instead of calculating one value per item, the scalar assignment computes only one value independent of all the items. Thus, in the present case, in the first two lines, we compute one value per week for Week.oamount and another value per week for Week.pamount.

The line chart statement that starts with show linechart is a bit longer than, say, a simple label tile. In order to avoid a long and somewhat unreadable statement, we use the block syntax. The block should start after the with, and then all tile arguments can be listed below, one argument per line.

The title of the line chart also includes a declaration of a monetary unit with the unit: "$" option, as we have already seen with the indicator display. Following that, after the line return, we have two vectors listed, namely Week.oamount and Week.pamount. As previously mentioned, after the with, it is possible to list one or several variables separated by comma. Those variables are displayed by the tile. In the present case, two variables are passed to the tile. A linechart can support more than two variables, however in practice, we recommend not to include more than three variables, because such charts tend to become quite unreadable when more than three lines are present in the script. The variables passed as an argument to the tile can also be explicitly renamed. This behavior is achieved with the as keyword, followed by the string defining the new name. Every tile type tends to have its own way of dealing with variable names as to improve the look and feel of the tile. For example, the line chart turns these names into a legend displayed below the actual chart. However, the variable naming mechanism using the as keyword is shared across all the tiles and is not restricted to the linechart. The string associated to the as can also contain a measurement unit, with a behavior identical to the one of the title. By default, the linechart picks a series of colors based on the color specified for the tile itself. However, it is also possible to specify one color for each line to be plotted. This can be done with the syntax: show linechart "Weekly volumes" unit:"$" a3f5 with
Week.oamount as "Sold" color: "blue"
Week.pamount as "Purchased" color: "red"

## Displaying a table

Let’s skip the piechart and the treemap for now to directly cover a more advanced usage of the table. Tables, while not being overly visual, are probably one of the most versatile ingredients of action-oriented dashboards. Tables are frequently used to display prioritized action lists such as the most overstocked or the most understocked products. In the script above, we have a semi-complex table defined at the end of the script (copied below for the sake of clarity).

show table "Top Sellers" a9f12 tomato with
Id as "Product ID"
Supplier
StockOnHand
sum(Orders.NetAmount) as "Sold" unit: "$" order by sum(Orders.NetAmount) desc This statement could be written in a single line, however, to make it more readable, we use, once again, the tile block syntax. The syntax follows the general Envision norms that we have seen so far with 4 variables being listed after the with keyword. The declaration ends with a special order by statement that we will review below. In addition, Envision does not merely allow variables to be listed, but expressions as well. We are taking advantage of this capability in line 5 here above. The sum() computes an aggregate at the item level, and this calculation is expressed directly within the tile. It would have been possible to declare the vector beforehand with: Sold = sum(Orders.NetAmount) show table "Top Sellers" a9f12 tomato with Id as "Product ID" Supplier StockOnHand Sold as "Sold" unit: "$"
order by sum(Orders.NetAmount) desc

The possibility of declaring expressions within a tile statement makes the script more compact and typically easier to read and to maintain.

Finally, the last line starts with order by and, as the name suggests, this line controls the order of the lines to be displayed in the table. The desc flag indicates that a descending order should be used. Alternatively, when the desc flag is omitted, the ascending order is used.