Step 1 - Preparing the environment

Fast-lane

If you prefer, you can follow the walk-through step-by-step but skip writing the code itself. Just clone the sample repository and install its dependencies:

# Clone the sample repository.
git clone https://github.com/pentaho/pentaho-engineering-samples
cd pentaho-engineering-samples
git checkout -b 8.3

# Go to the complete sample's directory.
cd Samples_for_Extending_Pentaho/javascript-apis/platform/visual-samples-bar-d3

# Install the dependencies.
npm install

Go directly to Visualize it.

Setup the sandbox environment

Create an empty folder and then initialize it:

 # Create the package.json file.
 npm init
 # Write "@pentaho/visual-samples-bar-d3" as the package name.
 # Accept the default for the other fields or write whatever you want.
    
 # Create a file named ".npmrc" with Pentaho's NPM registry configuration.
 echo '@pentaho:registry=https://nexus.pentaho.org/repository/group-npm' > .npmrc
    
 # Add and install the Visualization API development dependency.
 # (the runtime dependency is provided by the platform)
 npm install @pentaho/visual-sandbox@^3.0.0 --save-dev

 # Install the sandbox.
 npx init-sandbox

Now, you should edit the just created package.json file and add the paths property to it, to define the root AMD/RequireJS module identifier as pentaho/visual/samples/barD3:
```
{
  "name": "@pentaho/visual-samples-bar-d3",
  "version": "0.0.1",
     
  "paths": {
    "pentaho/visual/samples/barD3": "/"
  },
     
  "devDependencies": {
    "@pentaho/visual-sandbox": "^3.0.0"
  }
}
```
See Pentaho Web Package for more information about the format of a package.json file.

Attention

This tutorial assumes the name @pentaho/visual-samples-bar-d3 as your package name and the name pentaho/visual/samples/barD3 as the root AMD/RequireJS module identifier. If you which to use different names, you will have to take care to change all the references to the original names throughout the tutorial.
You should now also have the sandbox.html and sandbox-data.json files.

Those files provide a minimal sandbox from which sandboxes for specific samples or experiments may be derived. As is, it simply displays the pentaho/visual/samples/calc visualization — the only visualization that comes bundled with the Visualization API.

Open each file and get acquainted with it.

Visualize it

Open sandbox.html in a browser. You should see the result of the average operation: The result is 1002566.29.

The page shows the simplest (and kind of useless) visualization: a calculator, which just displays the result of aggregating the values of one column of a dataset.

That’s why you have to create your own!

Directly opening the file through the filesystem will not work when using Google Chrome (and possibly other browsers), because of security restrictions that disallow the loading of local resources using XHR — a functionality that is required by the Visualization API to load localization bundles and other resources.

To overcome this limitation you need to serve the project files through an HTTP server. There are several simple-to-use solutions:

Node:

npm install -g node-static
static -p 8000

PHP:

php -S localhost:8000

Python 2:

python -m SimpleHTTPServer 8000

Python 3:

python -m http.server 8000

Ruby:

ruby -run -e httpd . -p 8000

After one of the above, you can open http://localhost:8000/sandbox.html in the browser.

Continue to Creating the model.