Substitutions in a D3 Visualization Dashboard
A dashboard receives its instructions of what and where to display controls etc., from the JSON configuration file. The file consists of a series of properties and their values that provide the information. Depending on the complexity of the dashboard, the property-value lists can become lengthy. To minimize the length of a JSON configuration file, to apply a common style to several widgets, or avoid duplicating repetitive data, for example, substitutions for the property-value pairs can be created, and the parameters for the substitutions passed to the configuration file via the URL.
A substitution is defined by creating a parameter key and assigning a value to it, which can be a string, number, Boolean, or a JSON object. The parameter key can then be set for any property in the configuration file.
Substitution Syntax
The syntax for creating a substitution in the configuration file is: $[ParameterKey]$.
Example:
- No substitution: “rows”:6,
- Substitution: "rows": “$rowsKey$”
- Copied and entered in the URL: Rows = 6
Once the key-values are manually created for a configuration file, they are stored in the URL. During runtime, the dashboard reads the JSON configuration file, makes a list of all the keys it needs to resolve. Once the parameter key is found in the URL and its value is resolved, the property value is replaced in the JSON file at all the places where the key is used. If the specified JSON configuration file is not found in the dashboards folder, then the values from the defaultconfig.json file is used as the default.
You can use a text editor to create and store your parameter key-value substitutions. You can then copy and paste the pairs into the URL.
Substitution Rules and Defaults
- A parameter key may not contain another parameter key within a parameter key.
- If no value is found for a parameter key in the URL, the following defaults are calculated:
- Rows and Columns are based on the number of widgets in the Widgets section the rows or columns will get calculated and assigned
- Margins: default value is “5”
- Logger: If the dashboard application is running in a browser, the default value is “Browser logger” and is created by default.
- Widgets and baseURI are mandatory fields from configuration file. Default values are not assigned for these properties. If no parameter values are found for these properties, the dashboard will not load properly.
JSON Object Example
A JSON object is a group of properties in curly brackets. In the example below, a JSON object is substituted.
Example
Under the DashboardLayout section, LoggingConfig is configured as follows:
"DashboardLayout":{ "Rows": 6, "Columns": 3, |
"LoggingConfig": { "LoggerName": "AFWLogger", "TurnOnInfoTrace": true, "TurnOnErrorTrace": true, "TurnOnWarningTrace": true }, |
"Margins": |
In the following section, the LoggingConfig section has been substituted, as follows:
"DashboardLayout":{ "Rows": 6, "Columns": 3, |
""LoggingConfig":“$LoggerObjectKey$” |
"Margins": |
In the URL the parameter value for the key, $LoggerObjectKeys$, is set as follows:
LoggerObjectKey = { "LoggerName": "AFWLogger", "TurnOnInfoTrace": true, "TurnOnErrorTrace": true, "TurnOnWarningTrace": true } |
Entire JSON Substitution
A JSON configuration file can be used as a value substitution. In this case, the configuration file is provided as a URL parameter, the JSON extension is dropped.
Normally, a dashboard receives its visual instructions from the JSON configuration file, which can also be specified in the URL, as follows:
http://AAEINPU746563W.xyz.Delta.net/EnergyBldg1Floor2DashboardApp1/#/dashboard?configfile=dashboardconfig.json&pName=GMS_AP2_Enhanced_LAO_1
To use the JSON configuration file as a value substitution,
- Drop the JSON extension from the file name
- Substitute „pName“ with another parameter name.
Boolean, String, and Integer Example
"DashboardLayout":{
"Rows": 2,
"Columns": 2,
"Logging":
{
"LoggerName": "$stringValue$",
"TurnOnInfoTrace": "$boolValue_True$",
"TurnOnErrorTrace": "$boolValue_True$",
"TurnOnWarningTrace": "$boolValue_False$"
},
"Margins":
{
"Top": "$NumericValue$",
"Right":"$NumericValue$",
"Bottom":"$NumericValue$",
"Left":"$NumericValue$"
}
}
NOTES:
Where value replicable parameters in URL can be as follows
$stringValue$ = "AWFLogger"
$boolValue_True$ = true
$boolValue_False$ = false
$NumericValue$ = 2
Array Example
{
"DashboardLayout":{
"Rows": 2,
"Columns": 2,
"Logging":
{
"LoggerName": "AFWLogger",
"TurnOnInfoTrace": true,
"TurnOnErrorTrace": true,
"TurnOnWarningTrace": true
},
"Margins":
{
"Top": 2,
"Right":2,
"Bottom":2,
"Left":2
}
},
"widgets": “$widgetsCollection$",
"baseURI":"http://localhost:8080"
}
==========================================================
The value of $widgetsCollection$ in URL is expected as follows
Widgets
Collection = "[
{
"Name":"My Chart 1",
"ChartType":"PieChart",
"layout": {
"startRow": 1,
"startColumn":1,
"rowspan":1,
"columnSpan":1
},
"dataProvider":{
"name":"ProviderNamer",
"privateConfig":
{
"counterType" : "UnprocessedCount"
}
},
"style":{
}
},
{
"Name":"My Chart 1",
"ChartType":"PieChart",
"layout": {
"startRow": 1,
"startColumn":2,
"rowspan":1,