5.1.2.7. Custom Visualizations¶
Project erosion data can be displayed on the Dashboard Page in various visualization formats—graphs, charts, tables, images, etc—by creating custom scripts that fetch and process the relevant data from the Dashboard API.
Dashboard page with custom visualizations.¶
Caution
Depending on the amount of data processed by visualization scripts, this feature may place a noticeable load on the server; however, visualization results are cached between page loads to maintain server responsiveness. Furthermore, if the generated visualizations contain a large amount of data that needs to be processed on the client side—e.g., complex SVG graphics with many shapes and paths—browser performance may degrade on the Dashboard Page.
To add custom visualizations, the Visualization Creation
Interface must be enabled and
configured on the Reporting > Custom Visualizations page of
the general settings.
Note
Starting with 7.11, the Visualization Creation
Interface is enabled by
default for newly created Axivion Dashboard Server configurations, with the
module search path set to <confdir>/modules. Additionally, this
directory is populated with a set of example
scripts.
Adding your own visualization scripts¶
A custom visualization is a Python script whose file name matches the
pattern visualization_*.py and which defines a
create_visualization_writer() factory method (see
Section 7.2.4 for the programming
details). For the Dashboard to discover such a script, the script file
must be placed in the Module Folder that the Visualization
Creation Interface is
configured to scan:
Open the Visualization Creation Interface on the
Reporting>Custom Visualizationspage of the general settings and make sure that it is enabled. Take note of the Module Folder setting: it is a filesystem path relative to the Dashboard configuration directory—the directory referred to as<confdir>below and passed to the server viadashserver ... --confdir <confdir>.The default value of the Module Folder depends on how the configuration was created:
For Dashboard configurations newly created with version 7.11 or later, it is
modules, i.e., scripts are placed into<confdir>/modules.Configurations that were migrated from a version prior to 7.11 keep their previous folder
visualization_modules, i.e.,<confdir>/visualization_modules.
You may change the Module Folder to any path relative to
<confdir>and save the settings.Place your
visualization_*.pyscript inside that folder on the Dashboard host. For example:<confdir>/modules/visualization_my_chart.py
The supplied example scripts are a good starting point. Starting with version 7.11.0, they are copied automatically into the default Module Folder (
<confdir>/modules) during Dashboard setup (cf. Migration to 7.11.0), so in a default configuration you can simply duplicate one of them in place and adapt it to your needs.Add or configure a Custom Visualization gadget on the Dashboard Page. The Module Folder is scanned whenever a custom visualization is configured, so the newly added module is immediately selectable—no server restart or page reload is required.
Caution
The Module Folder is scanned for Python scripts that are executed on the Dashboard host. Make sure that only trusted users have write access to this folder; otherwise, malicious Python code could be run on the server.
In order for a user to customize the project portal on the
Dashboard Page, they must be
granted the Manage Portal
permission. Additionally,
the Generate Reports
permission is
required to add Custom Visualization
Gadgets.
Visualizations can be added to the project portal via Custom Visualization gadgets (cf. Section 5.1.4.3).¶
Similar to Custom Report Scripts, visualization scripts support configurable parameters that can be set through the UI and that are stored along with the gadget. After portal configuration is complete, all users will see the same gadgets for all projects; i.e., there exists only one portal configuration, and regular users will not be able to change it.
More details on creating new report modules can be found in Section 7.2.4.