How to create a Google Data Studio Community Visualization

Matt Redford,

We’ve guided you through the process of creating a custom data connector within Google Data Studio. This allows you to define your own data sources and use the existing visualisation library to create powerful dashboards tailored to your own requirements. With the launch of community visualizations you are now able to look at dashboards from both sides and create your own visualisations using a framework of your choice.

Example of google data visualization

There are a number of visualisation frameworks we can use for this such as:

If you’re in any way familiar with the frameworks above then you’ll know how much of a game changer this feature is.

In this post I’ll guide you through the whole process of creating a relatively straight forward radar chart using Chart JS like the one below within Google Data Studio.

Example google data visualization

We’ll touch upon:

  • The local development workflow to build locally and push to development and production environments
  • Google Cloud storage buckets
  • Accessing the created visualisation within Google Data Studio

Table of Contents

  1. Install the required software and define the environments
  2. Build the visualisation and preview locally
  3. Publish and access the visualisation within Google Data Studio
  4. Summary

Requirements

You’ll need:

  • A Google account with access to the Cloud Platform
  • A HTML web editor with a good understanding of JavaScript
  • Basic understanding of the Google Data Studio interface
  • Some experience of using command line which we’ll use as part of the local development workflow

Step 1: Install the required software and define the environment

The local development workflow is the preferred option for creating visualisations at ease. It handles a lot of the back end processes for you and encourages you to use both development and production environments. In addition you can also preview your visualisations locally using sample data. Speaking from experience, you’ll definately appreciate this workflow once you become familiar with it.

To start with the local development workflow you’ll need to install the following:

  • npm 5.2.0 or later. This enables you to install packages using the command prompt along with a couple of other benefits.
  • gsutil. This handles the Google authentication side of things which you’ll use to connect to the Google Cloud Platform. This process will guide you through the process of connecting to a Google account of your choice.

Once installed correctly open the command prompt interface and navigate to the folder directory of your choice. This is where your visualisation code will be stored. This command line cheat sheet will help you a lot if you are new to it.

Run the following command:

npx @google/dscc-gen viz

This will download the local development framework and start the project wizard.

You’ll be prompted to enter a project name. We’ve called it "Starter_Project".

? Project name Starter_Project

We’ll now need to input both the "dev" and "prod" environment locations. These environments store the specific files that Google Data Studio requires to display your visualisation. The "dev" environment is a test environment used to debug and preview your visualisation with caching disabled. The "prod" environment is a more streamlined and faster environment with caching enabled. You’ll use the latter when your visualisation is ready to be used by your target audience, whether that be internal or open to the public.

To get the environment locations we’ll first need to create them with within Google Cloud Storage. This quick start guide will help you get started with storage buckets. Note that you’ll need to enable billing, however the free tier is very generous so it will be very unlikely that you’ll exceed it for this project alone. It is always worth bookmarking the cloud storage pricing page to ensure you’re fully aware of any costs associated with the cloud platform.

Using the Cloud Storage browser for simplicity we’ll create the environments (advanced tip: you can also create storage buckets using the command prompt). I’ve already created a folder structure for both environments:

Example of storage buckets

In this scenario the environment directories will be:

  • gs://data_studio_projects/chartjs/dev for the dev environment
  • gs://data_studio_projects/chartjs/prod for the prod environment

It is important to note that these directories require public access enabled so Google Data Studio can communicate with them.

Enter these environment directories when required in the command prompt:

? What is your GCS prod directory? gs://data_studio_projects/chartjs/prod

? What is your GCS dev directory? gs://data_studio_projects/chartjs/dev

The prompt will now install the remaining dependencies. This may take several minutes. Once you see the confirmation message below you are able to move onto the next step.

Created new community viz: Starter_Project

We now need to install the specific visualisation frameworks used for your visualisation. In this case we’ll be installing Chart JS. Run the following command:

npm install chart.js

Once installed you can confirm this by opening the "package.json" file within the root of your local project folder. You’ll see "chart.js" as a dependency.

Chart.js dependency example

You’ll instantly become familiar with the remaining contents of this file and start to get more comfortable with the process.

Step 2: Build the visualisation and preview locally

We can now start the visualisation build process. In the local project folder you’ll only ever need to access the "src" folder. This folder contains the following files:

  • index.css to contain any additional CSS rules
  • index.js for containing the JavaScript code (this is where we will be focusing our efforts)
  • index.json to contain specific Google Data Studio rules and options for your visualisation. These will become available once the visualisation has been loaded into Data Studio
  • manifest.json to contain top level information about your visualisation such as name and location of the required resources
  • localMessage.js to contain sample data to be used when previewing your visualisation locally

This detailed reference resource will supply all the information you need for the configuration files.

We now need to gather a suitable example dataset for our visualisation. To do this we first need to update the “index.json” file. We’ve updated it to only require 1 dimension and 4 metrics like so:

Image of example dataset

Let’s return to command line mode and enter the following command:

npm run update_message

This publishes an interim visualisation to your "dev" location. We now need to access Google Data Studio to gather the sample data request we can use in our project when testing locally. Within Data Studio click "Explore More":

example showing what google data studio looks like

Click "Build your own visualisation":

Google data studio build your own visualisation

Add the "dev" location that was defined earlier:

Image showing where manifest path goes

Click on your visualisation tile (note: the name, company, description and image are being pulled from the relevant fields in the "manifest.json" file which was mentioned earlier):

Example of visualisation tile

You will likely see the following message:

Image warning that visualisation is turned off

To resolve it we first need to connect it to a data source with community visualisations enabled. Our test data source will be a Google Sheet with the following schema and sample data:

Example of data and schema

Once created we can go back to Data Studio and add a new data source located within the toolbar:

Add data to dataset image

Click "Google Sheets":

Example image on how to link google sheet to data studio

Select "URL" and enter the URL of the Google Sheet which you created:

example image of entering google sheet url

Click "Add" to complete the process.

It is important to ensure that "Community visualisation access" is switched on. By default it is switched off. This can be configured by editing the data source connection.

Image showing community visualizations is off

Update the setting and click "Save".

example on how to enable community visualisation

Use the following concepts for the data source (remember that we defined 1 dimension and 4 metrics earlier):

schema column structure

The visualisation widget you added earlier will now refresh and display what appears to be code. This is an example of a data request that your visualisation will receive and interpret.

example of data request

Switch the Data Studio report to "View" mode and copy the entire code block. The code should be pasted into the "localMessage.js" file in your project directory so it replaces the entire contents which will already be present. This essentially keeps a copy of a Data Studio request offline so you can preview your visualisation locally with a full simulated response.

We’re now going to go through the fine detail of building the visualisation. Open "index.js" in your project directory (remember that the files you need are located in the "src" folder). This file will already contain a basic template for you to build upon but in this scenario we’ll guide you through the specific updates for the visualisation which you are creating.

Firstly we are including 3 files – the Google Data Studio local development helper, Chart JS (which we installed previously as the required visualisation framework) and the local file which contains the simulated data response for testing purposes.

const dscc = require('@google/dscc');
const chartjs = require('chart.js');
const local = require('./localMessage.js');

The "LOCAL" setting is very important and an easy one to miss. You’ll want to set this to "true" when testing locally.

export const LOCAL = true;

The following section creates a HTML canvas element with a set margin upon which your visualisation will be written. New to this HTML element? This introduction will help.

var margin = { top: 10, bottom: 10, right: 10, left: 10 };

var height = dscc.getHeight() - margin.top - margin.bottom;
var width = dscc.getWidth() - margin.left - margin.right;

var canvasElement = document.createElement('canvas');
var ctx = canvasElement.getContext('2d');
canvasElement.id = 'myViz';
canvasElement.height = height;
canvasElement.width = width;
document.body.appendChild(canvasElement);

We’ve now reached the primary function of this file. The "drawViz" function has one supplied variable called "data" which contains the data supplied by the Google Data Studio request. This function is called each and every time a request is sent so we start the function by effectively clearing the canvas to prepare it for the newly written visualisation. The remainder of this function is a blank canvas for you to develop your visualisation using your selected framework. Please see the full code example later in this guide which reveals the code used to create the radar chart using Chart JS.

const drawViz = (data) => {

var ctx = canvasElement.getContext('2d');
 ctx.clearRect(0, 0, canvasElement.width, canvasElement.height);

// Visualisation code can be added here

};

A statement concludes the file which determines which data source is used. If you changed the value of "LOCAL" to true then it will work with your local data request. If false it will subscribe to a live data request which is needed when you publish your visualisation and for it to work correctly within Google Data Studio.

if (LOCAL) {
 drawViz(local.message);
}
else {
 dscc.subscribeToData(drawViz, {transform: dscc.objectTransform});
}

The full syntax example including our Chart JS radar chart workflow is included below. This also includes the specific code used to build the required radar chart discussed in this guide. The code is annotated with step by step references to help you get an understanding of the build. The official Chart JS radar chart reference guide can be found here.

const dscc = require('@google/dscc');
const chartjs = require('chart.js');
const local = require('./localMessage.js');

// change this to 'true' for local development
// change this to 'false' before deploying
export const LOCAL = true;

var margin = { top: 10, bottom: 10, right: 10, left: 10 };

var height = dscc.getHeight() - margin.top - margin.bottom;
var width = dscc.getWidth() - margin.left - margin.right;

var canvasElement = document.createElement('canvas');
var ctx = canvasElement.getContext('2d');
canvasElement.id = 'myViz';
canvasElement.height = height;
canvasElement.width = width;
document.body.appendChild(canvasElement);

// write viz code here
const drawViz = (data) => {

var ctx = canvasElement.getContext('2d');
 ctx.clearRect(0, 0, canvasElement.width, canvasElement.height);

// Map the data response to create the required labels and data sets for the Chart JS radar chart

var dataLabels = data.fields.metricID.map(function (dataLabel) {
return dataLabel.name
});

var dataSets = data.tables.DEFAULT.map(function (dataSet) {
return {'label':dataSet.dimID,'data':dataSet.metricID,'borderColor': 'black','pointRadius': 4,'fill':false,'pointBackgroundColor':'black'}
});

// The Chart JS radar visualisation is created and written onto the "ctx" canvas. Additional style options are configured

var myRadarChart = new Chart(ctx, {
   type: 'radar',
   data: {labels: dataLabels, datasets: dataSets},
   options: {tooltips:
true,scale: { gridLines: { circular: true },ticks: {beginAtZero: true,suggestedMax:100,stepSize: 25,callback: function(value, index, values) {return value+'%';}}},legend: {display: false},elements:{line:{tension:0,borderWidth:3}}}
});

};

// renders locally
if (LOCAL) {
 drawViz(local.message);
}
else {
 dscc.subscribeToData(drawViz, {transform: dscc.objectTransform});
}

Once saved we’re now ready to preview the visualisation locally. Please ensure that the value of "LOCAL" is set to true.

Let’s return to the command line and enter the following command:

npm run start

After a short while this process will open a new browser window from which your visualisation will be displayed (all going to plan!). The radar chart displays the data which was previously inputted into the external Google Sheet data connection.

In addition each time you save the "index.js" file locally the visualisation within the previously opened browser window will refresh automatically which is a helpful feature for quick testing.

Step 3: Publish and access the visualisation within Google Data Studio

Once you are happy with local testing we’re now at a stage where we can publish the changes.

Please ensure that the value of "LOCAL" is set to false before continuing with this step.

Let’s return to the command line and enter the following command:

npm run build:dev

This command builds the associated visualisation files locally for the "dev" environment which is a required step before it can be published.

Once built we can enter the following command:

npm run push:dev

This will push the visualisation into your selected storage location for the "dev" environment.

In Google Data Studio we can now enter the "dev" location using the same process that was used earlier in this guide.

example of manifest path in data studio

Using the same data connection that was created earlier (the Google Sheet) the visualisation will now be displayed. Magic!

example of data visualisation now showing

The visualisation is now using a dynamic data connection so you’ll be able to update the values in the Google Sheet and see the changes reflected within Data Studio.

If you are happy with the visualisation on the "dev" environment we can complete the process of publishing it to the "prod" environment. As highlighted earlier this is a more streamlined environment with caching enabled which will improve the time it takes for your visualisation to load.

Let’s return to the command line and enter the following command:

npm run build:prod

Once built we can enter the following command:

npm run push:prod

You can now enter the "prod" path into Google Data Studio when adding a new visualisation.

If you have developed something particularly useful to the community then it is definitely worthwhile publishing it to the official gallery.

Summary

The ability to create your own visualisations within Google Data Studio is a very useful and flexible feature.

This post guided you through the process of creating a relatively simple visualisation using the local development workflow. This new workflow will significantly reduce the amount of time it takes you to build, test and publish a visualisation. This visualisation could be expanded with some of the following features which are worthwhile exploring:

  • Adding interactions and filters
  • Adding customisable styling options

I hope it has given you the confidence and inspiration to start developing your own. The following resources will be incredibly useful to you as you progress:

Any questions or feedback? Please reach out to us on our social channels below.

Maximise business opportunity with data-driven decision making. Find out more about our Data team.


The Author

Matt Redford

Senior Analytics Architect

Matt focuses on the technical planning, implementation and testing of analytics, tag management, data connectivity, CRO activity and other tracking solutions at 26.

Want to know more?

Let's connect