Dashboards - Technical Details

This page is for users who wish to build custom dashboards. This is still an overview rather than a full manual, and a certain amount of familiarity with SQL and JSON data is assumed.

For clients who wish to have custom dashboards built for them, this is an additional service offered to Venture Tracker clients.

It is also worth noting that some elements of the overall functionality described need to be enabled within the VT configuration and are subject to the specific VT license type as well as user permissions.

These are the basic reports used by both the simple VT Reports dashboard, but also at the core of custom dashboards. VT Reports is where a report may be run, but to create a new report, they are found under Admin Items → SQL Reports.

You can develop and test your custom reports directly in the VT Reports section of VT if you have the correct user permissions. If not, you can simply run reports which have already been developed.

These are configured within a database table called statistics - if enabled in your global configuration, this will appear under the Admin Menu as 'Dashboard Stats'.

A display widget takes an existing SQL report and displays it on your dashboard with some additional configuration. For example, you can set the colour of the widget and an icon to be displayed (using the font-awesome icon library). To edit, you require manager permissions - see User Classes

To make an SQL report available for use within a stats widget, the SQL Report boolean - 'Used in Stats' - must be True. The stat displayed is either the content of an SQL field called ’total’ or 'count' (case insensitive), if present, or a count of the returned records if not.

Finally you can set the order in which widgets will appear in a MiniStats Panel - this is simply a numeric ascending sort.

Once you have built a widget, it can be used in multiple Ministats panels by entering a comma separated list in the Panels field of the widget. You can also disable or enable a widget here. Disabled widgets simply do not display.

Active BRP Panellists
 
SELECT COUNT(id) AS total 
FROM panellists 
WHERE active=1
 
Active Companies, excluding historic members
 
SELECT COUNT(Company.id) AS total
FROM companies AS Company
LEFT JOIN company_types AS CompanyType ON (Company.company_type_id = CompanyType.id)
WHERE Company.enabled=1
AND CompanyType.title NOT LIKE 'historic%'

A dashboard is simply a number of panels arranged visually on a page, with each panel showing a different kind of data representation. Panel types include:

• Table Panels - tabular results from a report
• Chart Panels - results plotted onto a graph. Currently, only Pie charts have been released. More chart types will be available soon.
• Ministats Panels - a collection of widgets
• Cell Panels - specialised hand-coded panels

Here is a view of the Admin Items → Custom Dashboards table with a list of panels for the example dashboard ‘Our Performance’:

Page Layout for this example will be:

The first row represents a top level entry (no Parent) and is therefore an actual dashboard. The title (Our Performance) will appear under the Dashboards menu. The other rows are child panels within that dashboard, as seen in the Parent column. A dashboard can have any number of child panels.

Child panels display on the page in order as defined by the Order column (numerical, ascending). You may either manually edit, or use the up and down arrow icons to the right of each row on the index table to vary the order.

When adding a new panel to a dashboard, the parent should be chosen from the dropdown list and the title for that specific panel should be entered. To create a new dashboard, no parent will be set. The element type will be one of a number of pre-defined panel types, such as Tables, Pie Charts etc. selected from a dropdown list.

The screen of VT is nominally 12 columns wide, and each panel can therefore be up to 12 columns. In this list, two panels are 6 columns wide, so they will appear side by side in the final layout.

Finally, a dashboard or an individual panel will only display if it is enabled, and if it is a dashboard and set to Private, it will only display if a user is logged into VT. Otherwise, dashboards are visible even without being logged in.

The following settings can be configured for a top level dashboard or a panel

• parent : A top level dashboard will have no parent, but a child will link to it’s containing parent here.
• title : the title of this panel or dashboard. If a top level dashboard, this will also be the name of the dashboard on the left hand menu.
• panel / element type : a top level dashboard will have that same type, i.e. 'dashboard'. However, a child dashboard will have its type specified here, e.g. Pie Chart or Table etc,

• columns : determines the width of a panel on a dashboard. A full window width is 12 columns. By setting this field to 6 you could enable two panels to sit side-by-side, for example. If the column width of a panel combined with the starting point (width of previous panels) means it would cover more than 12 columns across the page, it will wrap to begin a new row.
• enabled : If false, the dashboard / panel will not show in display mode. Default: true

• params : see below

The following settings are only used for a top level dashboard

• is_private : if true, the dashboard will not show in display mode unless the user is currently logged in to Venture Tracker. This setting has no effect on a child panel. Default: false
• report : some panel types such as pie charts and tables require data to be generated by an existing SQL Report. The report to be used should be selected here. If the panel type does not require a report, this setting will be ignored. Default: none

Each panel takes a number of parameters for detailed configuration. The params field must be valid JSON. Details of parameters are given below with each panel type. There is a built in JSON editor to try and ensure correct JSON is written. No additional configuration parameters are needed for a top level entry.

The following settings are common to all panel types

• card (optional) A boolean value that will determine whether the displayed element is contained in a highlighted card with a header. Default: true

A Ministats panel will show a collection of statistic widgets (see above). It will select widgets to display based upon a pre-defined panel name, or ‘slug’. All widgets that contain the same slug name in the configuration of the individual widget will be included in the panel, respecting the sort order and the 'enabled' flag set in the statistics table.

A Ministats panel can appear on any dashboard. The same widgets can appear in multiple panels. If you require a different combination of widgets on another dashboard, define a new slug name and add that to the required widgets. This gives a very flexible way of reusing widgets once they have been configured.

Params:

• slug (required). The name assigned to this ministats panel which will be used to select widgets for display from the Statistics table.
• colsPerCard (optional). The width of each individual widget. If set at 4, for example, you will display 3 widgets per row in a full page width of 12 columns. Default: 4

This panel will display an existing SQL Report (VT Report) in a tabular view. The required report must be selected in the main panel settings.

Params:

• search (optional). A boolean value that will append a search box and pagination controls to the table as well as allowing the table to be sorted by each header. Default: false.
• showTotals (optional). If true, the element will display a totals row below the table. Default: false

This panel will display an existing VT Report in a pie chart view. The required report must be selected in the main panel settings.

Params:

• category (optional). The name of the field in the report that will be used to identify each slice of the pie chart. It will be assumed that the VT Report will contain a field with this name. Default: 'category'
• value (optional). The name of the field in the report that will be used to identify the value of each slice of the pie chart. It will be assumed that the VT Report will contain a field with this name. Default: 'value'
• showTitle (optional). If true, the element will display a title above the pie chart. The title will be the title of the linked query. Default: false
• table (optional). If true, the element will display a table to the right of the pie chart with the report data. This table will not have a search box. Default: false
• showTotals (optional). If true, the element will display a totals row below the table, if displayed. Default: false

Show current active companies by class of membership (company_type)

SELECT CompanyType.title AS 'class', COUNT(Company.id) AS 'value'
FROM companies AS Company
LEFT JOIN company_types AS CompanyType ON (Company.company_type_id = CompanyType.id)
WHERE Company.enabled=1
AND CompanyType.title NOT LIKE 'historic%'
GROUP BY class

For this example, the 'category' parameter would be set to 'class'. The value parameter can be left as default as the field is already called 'value' in the SQL

This panel will display an existing handcoded cell view.

Params:

• cell (required). The name of the cell to display.
• cellParams (optional). An object containing the required params for the cell as param-value pairs. These will only be visible in the source code for the cell itself. Default: [ ] (the empty array, or no params)