Table of Contents
- Install node modules for template
- D3 Visualization Template File Customization
- Debugging your visualization
- Package version numbering
- Generate GUIDs
- Multiple visualizations in a package
Install node modules for template
Before customising the template files you will need to install the node modules that the template depends on.
In a Visual Studio Code terminal run the following:
npm install
If you include any additional packages for your visualization, you need to install them individually
npm install additional-package-name
D3 Visualization Template File Customization
Warning: do not change the name of the following files
src/visualizationNN/no-guid.visualization.config.json.ejs
src/no-guid.package.json.ejs
After you have generated GUIDs for the package configuration files, the following configuration files are generated each time you rebuild the package for debugging or production:
src/visualizationNN/visualization.config.json
is generated fromsrc/visualizationNN/visualization.config.json.ejs
src/package.json
is generated fromsrc/package.json.ejs
Warning: generated configuration files
If you need to amend configuration only edit the source .json.ejs
file, not the generated .json
file. Any edits you make in the .json
file will be lost the next time you rebuild the package for debugging or production.
webpack.common.js
-
Babel loader configuration, including supported browsers
-
visualization entry point(s)
-
Possible SplitChunks for any additional D3 chart libraries
You will need to update the dependencies in
src/no-guid.package.json.ejs
(see below) for any chunks you addFor example
optimization: {
splitChunks: {
cacheGroups: {
"d3" : {
test: /[\\/]node_modules[\\/](d3.*)[\\/]/,
name: 'd3',
chunks: 'all',
priority: -3,
enforce: true
},
"other" : {
test: /[\\/]node_modules[\\/]/,
name: 'other',
chunks: 'all',
priority: -10,
enforce: true
}
}
}
}
or update test property for "d3"
For example
"d3" : {
test: /[\\/]node_modules[\\/](d3-hexbin.*)[\\/]/,
- VersionFile plugins for any additional visualizations
package.json
-
Webpack Chart Package properties
For example
{
"name": "scatter_plot",
"description": "Example scatter plot chart based on D3 framework",
"version": "1.1.10",
"supportedVersions": "0",
"license": "MIT",
package-lock.json
-
Webpack Chart Package properties (lines 2 and 3)
For example
{
"name": "scatter_plot",
"version": "1.1.10",
src/visualization01/visualization.js
-
Add import statements for any additional D3 chart libraries
Add import any additional import statements after the d3 import
//
// Entry function declaration
//
import * as d3 from "d3";
import * as d3Hex from "d3-hexbin";
-
Add chart code to visualization function
Add the chart code at the TODO comment
//
// TODO: Add D3 visualization code here, referencing configuration above
//
//
// append the svg to the element in MooD config
//
// set the dimensions and margins of the graph
// append the svg object to the body of the page
var svg = d3.select("#" + config.element)
.append("svg")
.attr("width", width + margin.left + margin.right)
.attr("height", height + margin.top + margin.bottom)
.append("g")
.attr("transform",
"translate(" + margin.left + "," + margin.top + ")");
...
- Pay attention to the domains within scaleLinear functions
// Add X axis
var x = d3.scaleLinear()
.domain([xMin, xMax])
src/visualization01/no-guid.visualization.config.json.ejs
Embedded JavaScript Template for visualization.config.json.ejs template.
See below for instructions on how to generate visualization.config.json.ejs containing a GUID after customising this file.
-
Do not alter the id or version properties
-
Update visualization properties
For example
{
"id": "<%= uuid.v4(); %>",
"name": "Simple Scatter Plot",
"description": "Example of a scatter plot diagram using D3 framework",
"version": "<%%= package.version %%>",
"supportedVersions": "0.1",
"moodVersion": "16.0.076",
"entry": {
"file": "visualization.js",
"function": "vis.visualization"
},
"supportedBrowsers": "Chrome, Edge, Firefox",
-
Update visualization default Inputs
For example
{
"inputs": [
{
"name": "xAxisMin",
"displayName": "X Axis Range Minimum",
"type": "Number",
"default": 0.0
},
{
"name": "xAxisMax",
"displayName": "X Axis Range Maximum",
"type": "Number",
"default": 10.0
},
{
"name": "yAxisMin",
"displayName": "Y Axis Range Minimum",
"type": "Number",
"default": 0.0
},
{
"name": "yAxisMax",
"displayName": "Y Axis Range Maximum",
"type": "Number",
"default": 10.0
}
],
}
-
Update visualization default Styles
For example
{
"style": {
"URL": "visualization01/simple.css",
"JSON": {
"margin": {
"top": 20,
"bottom": 20,
"left": 20,
"right": 20
},
"xAxisLabel": "X Axis",
"yAxisLabel": "Y Axis",
"spotRadius": 1.5,
"fillColour": "#69b3a2"
}
}
}
src/visualization01/visualization.datashape.gql
-
Define visualization graph shape
For example
type data {
rows: [row]
}
type row implements MooDElement{
key: ID!
x: Number!
y: Number!
}
src/no-guid.package.json.ejs
Embedded JavaScript Template for visualization package.json.ejs template.
See below for instructions on how to generate package.json.ejs containing a GUID after customising this file.
-
Do not alter the id or version properties
-
Update visualization package properties
For example
{
"id": "<%= uuid.v4(); %>",
"name": "Scatter Plot",
"description": "Example scatter plot diagram",
"version": "<%%= package.version %%>",
-
Update dependencies - e.g. chart library
Add dependencies for any chunks added by changes to
webpack.common.js
aboveFor example
{
"dependencies": {
"d3": "./d3/visualization.js",
"other": "./other/visualization.js"
}
}
Debugging your visualization
Populate the following JSON files with sample data matching the structure required by your visualization
test/visualization01/data.json
For example
{
"data" : {"rows" : [
{
"key": "guid-1",
"x": 1.0,
"y": 1.0
},
test/visualization01/inputs.json
For example
{
"inputs" : {
"xAxisMin": 0.0,
"xAxisMax": 10.0,
"yAxisMin": 0.0,
"yAxisMax": 10.0
}
}
test/visualization01/MooDConfig.json
For example
{
"width": "800px",
"height": "600px",
"element": "visualisation01_element_guid"
}
test/visualization01/style.json
For example
{
"URL": "visualization01/simple.css",
"style" : {
"margin": {
"left": 20,
"right": 20,
"top": 20,
"bottom": 20
},
"spotRadius": 1.5,
"fillColour": "#69b3a2"
}
}
Package version numbering
MooD requires the visualization package and each visualization within the package to have their own version number. When changes are made to the visualization, the version number must be updated. To enure that you don't forget to update the version number, the template has been configured to update the patch number in the semantic version number (major.minor.patch) of the webpack visualization package configuration file ./package.json
. This version is only updated when creating the production package, not when debugging. To avoid updating the version number, use the rebuild
script instead of the build
script.
In a package with multiple visualizations, the version number is updated in all visualizations even if only one visualization is updated. If you need to control version numbers of the individual visualizations separately you can disable the automatic version numbering of visualizations. You then need to manually update the version number (and any other visualization configuration) in the src/visualizationNN/visualization.config.json
file; the src/visualizationNN/visualization.config.json.ejs
will no longer be used. To disable automatic version numbering remove or comment out the following code from the .\webpack.common.js
file:
//
// VersionFiles for each visualization configuration
//
let vcVersionFiles = VisualizationDirectories
.map(d => Object(new VersionFile({
packageFile: path.join(__dirname, 'package.json'),
template: path.join(__dirname, 'src', d.directoryName, 'visualization.config.json.ejs'),
outputFile: path.join(__dirname, 'src', d.directoryName, 'visualization.config.json')
})));
When running the build script to create the production package, the newly updated version number is copied from the webpack package configuration file into the following files
src/package.json
src/visualizationNN/visualization.config.json
The files are updated via the corresponding EJS template files
src/package.json.ejs
src/visualizationNN/visualization.config.json.ejs
Generate GUIDs
A GUID is required in the following files
src/package.json
src/visualizationNN/visualization.config.json
To generate the GUIDs in these files, execute npm run-script generate-guids
. This uses the following EJS template files
src/no-guid.package.json.ejs
src/no-guid.visualizationNN\visualization.config.json.ejs
The GUIDs are written to the following files, which are the EJS templates for version numbering.
src/package.json.ejs
src/visualizationNN\visualization.config.json.ejs
If you need to amend configuration only edit the source .json.ejs
files for version numbering, not the generated .json
file. Any edits you make in the .json
file will be lost the next time you rebuild the package for debugging or production.
Multiple visualizations in a package
If you want to have multiple visualizations in a package, the following files need to be updated
- create folder for additional visualization and should contain the following:
no-guid.visualization.config.json.ejs
- See Package version numbering above about manually setting visualization version numbers in a multi-visualization package.
visualization.datashape.gql
- JavaScript entry file containing visualization entry function
- Create test folder for additional visualization as a copy of
./test/visualization01
- Update json files and
visualization.js
in new test folder for the additional visualization
Comments
0 comments
Please sign in to leave a comment.