1. Intro
Looker Studio lets you build live, interactive dashboards with beautiful data visualizations, for free. Fetch your data from a variety of sources and create unlimited reports in Looker Studio, with full editing and sharing capabilities. The following screenshot is an example Looker Studio report:
( Click here to view this example report in Looker Studio)
Looker Studio provides several built-in chart types, including line charts, bar charts, pie charts, and scatter plots. Community visualizations allow you to build and use your own custom JavaScript visualizations in Looker Studio. You can also share your community visualizations with others so that they can use them with their own data.
What you'll learn
In this code lab, you'll learn:
- How a Looker Studio community visualization works.
- How to build a community visualization using the ds-component helper library (dscc).
- How to use your community visualization in a Looker Studio report.
What you'll need
To complete this code lab, you'll need:
- Access to the internet and a web browser.
- A Google account.
- Access to a Google Cloud Platform storage bucket.
- Familiarity with Javascript.
2. Quick survey
Why did you choose this codelab?
How do you plan to use this codelab/tutorial?
How would you rate your experience with Looker Studio?
What best describes your background?
What JavaScript visualization libraries are you interested in using?
Move to the next page to submit survey information.
3. Overview of community visualizations
Looker Studio community visualizations allow you to create and use custom JavaScript visualizations in your dashboards.
In this codelab, you will create a table chart community visualization that supports 1 dimension, 1 metric, and table header styling.
4. Community visualization development workflow
To create a community visualization, you need the following files in a Google Cloud Platform storage bucket, which you will create in a later step:
Filename | Filetype | Purpose |
manifest.json* | JSON | Metadata about the visualization and the locations of all visualization resources. |
viz-codelab.json | JSON | Data and style configuration options for the Property panel. |
viz-codelab.js | JavaScript | The JavaScript code to render the visualization. |
viz-codelab.css (optional) | CSS | CSS styles for the visualization. |
*The manifest is the only file that has a required name. The other files can be named differently, as long as their name/location is specified in the manifest file.
5. Write a Hello, world! visualization
In this section, you'll add the code required to render a simple Hello, world! visualization.
Write the visualization JavaScript source
Step 1: Download the dscc.min.js file from the Looker Studio Community Component Library (dscc) page and copy it to your working directory.
Step 2: Copy the following code into a text editor and save it as viz-codelab-src.js in your local working directory.
viz-codelab-src.js
function drawViz(data) {
// Container setup.
let container = document.getElementById('container');
if (container) {
container.textContent = '';
} else {
container = document.createElement('div')
container.id = 'container'
document.body.appendChild(container);
}
// Render the viz.
container.textContent = 'Hello, viz world!';
}
// Subscribe to data and style changes. Use the table format for data.
dscc.subscribeToData(drawViz, { transform: dscc.tableTransform });
Prepare the JavaScript bundle file
Step 3: Combine all JavaScript required into a single file by copying the contents of the visualization helper library (dscc.min.js) and your viz-codelab-src.js file into a new file named viz-codelab.js. The following commands can be executed to concatenate the files. Repeat this step each time you update the source visualization code.
Linux/Mac OS concatenation script
cat dscc.min.js > viz-codelab.js
echo >> viz-codelab.js
cat viz-codelab-src.js >> viz-codelab.js
Windows concatenation script
del viz-codelab.js
type nul > viz-codelab.js
type dscc.min.js >> viz-codelab.js
echo.>> viz-codelab.js
type viz-codelab-src.js >> viz-codelab.js
6. Write the visualization CSS
The CSS file defines the styling for your visualization and is optional. Copy the following CSS and save it as viz-codelab.css.
viz-codelab.css
table {
width: 100%;
border-collapse: collapse;
}
tr {
border-bottom: 1pt solid #d1d1d1;
}
th, td {
padding: 8px;
text-align: left;
}
7. Write the JSON config
The visualization config defines the data and style attributes supported and required by your visualization. This visualization in this codelab requires one dimension and one metric, and has one style element to select a fill color. Learn more about dimensions and metrics.
Copy the following code and save it as viz-codelab.json.To learn more about the properties you can configure, review the Community Visualization Config Reference.
viz-codelab.json
{
"data": [
{
"id": "concepts",
"label": "Concepts",
"elements": [
{
"id": "tableDimension",
"label": "Dimension",
"type": "DIMENSION",
"options": {
"min": 1,
"max": 1
}
},
{
"id": "tableMetric",
"label": "Metric",
"type": "METRIC",
"options": {
"min": 1,
"max": 1
}
}
]
}
],
"style": [
{
"id": "header",
"label": "Table Header",
"elements": [
{
"type": "FILL_COLOR",
"id": "headerBg",
"label": "Header Background Color",
"defaultValue": "#e0e0e0"
}
]
}
]
}
8. Create a cloud storage project and bucket
Step 1: Create a Google Cloud Platform (GCP) Project or use an existing one.
Step 2: Create a GCP bucket. The recommended storage class is Regional. Visit Cloud Storage Pricing for details on free tiers. Note: It is unlikely your visualization storage will incur any costs for the Regional storage class.
Step 3: Take note of your bucket name/path, beginning with the section after Buckets/. The path is referred to as a "component ID" in Looker Studio and is used to identify and deploy a visualization.
9. Write the manifest.json file
The manifest file provides information about your visualization location and resources. It must be named "manifest.json", and it must be located in the bucket/path created in the previous step, the same path used for your component ID.
Copy the following code into a text editor and save it as manifest.json.
To learn more about the manifest, visit the manifest reference documentation.
manifest.json
{
"name": "Community Visualization",
"logoUrl": "https://raw.githubusercontent.com/googledatastudio/community-visualizations/master/docs/codelab/img/table-chart.png",
"organization": "Looker Studio Codelab",
"organizationUrl": "https://url",
"termsOfServiceUrl": "https://url",
"supportUrl": "https://url",
"packageUrl": "https://url",
"privacyPolicyUrl": "https://url",
"description": "Community Visualization Codelab",
"devMode": true,
"components": [
{
"id": "tableChart",
"name": "Table",
"iconUrl": "https://raw.githubusercontent.com/googledatastudio/community-visualizations/master/docs/codelab/img/table-chart.png",
"description": "A simple table chart.",
"resource": {
"js": "gs://MY_GOOGLE_CLOUD_STORAGE_BUCKET/viz-codelab.js",
"config": "gs://MY_GOOGLE_CLOUD_STORAGE_BUCKET/viz-codelab.json",
"css": "gs://MY_GOOGLE_CLOUD_STORAGE_BUCKET/viz-codelab.css"
}
}
]
}
10. Upload your visualization files to Google Cloud Storage
- Upload the
manifest.json,viz-codelab.js,viz-codelab.json, andviz-codelab.cssfiles to your Google Cloud Storage bucket using the web interface or the gsutil command-line tool. Repeat this each time you update your visualization.
gsutil upload commands
gsutil cp -a public-read manifest.json gs://MY_GOOGLE_CLOUD_STORAGE_BUCKET
gsutil cp -a public-read viz-codelab.* gs://MY_GOOGLE_CLOUD_STORAGE_BUCKET
11. Test your Community Visualization in Looker Studio
Create a report and add data
Step 1: Copy the URL for the Community Visualization sample data set. Alternatively, use any data source you prefer and skip the following steps.
Step 2: Sign in to Looker Studio. In the top left, click + Create, then select Report.
Step 3: You'll see the report editor tool, with the Add data to report panel open.
Step 4: In the Connect to data tab, select the Google Sheets by Google connector.
Step 5: Select URL and paste in the URL of the Google Sheet from step 1.
Step 6: In the bottom right, click Add.
Step 7: If prompted to confirm You are about to add data to this report, click ADD TO REPORT. An Untitled Report is created and a default table is added to the report with sample data. Optionally, select and delete the default table so that you are left with a blank report.
Add your community visualization to the report
Step 1: In the toolbar, click Community visualizations and components 
.
Step 2: Click + Explore more to open the Community Gallery.
Step 3: Click Build your own visualization
Step 4: Under Test and add your community visualization, enter the Manifest path and click Submit. The manifest path is the Google Cloud Storage bucket name and path that points to the location of your visualization's manifest, prefixed with gs://. For example: gs://community-viz-docs/viz-codelab. If you have entered a valid Manifest path, a visualization card should render.
Step 5: Click the visualization card to add it to your report.
Step 6: If prompted, grant your consent to allow the visualization to render.
Step 7: Optionally, update the selected dimension and metric for the table. If you're using the provided sample data set, set the dimension to Country and the metric to Population. This will not have any effect on the visualization until later in the codelab.
The property panel on the right-hand side reflects the elements configured in viz-codelab.json.
Under the Setup panel, the visualization allows for one Dimension and one Metric.
Under the Style panel, the visualization has a single element to style the Table Header. At this point, the style control will have no effect on the visualization until the visualization code is updated in a later step. Note: You will see additional style options for your visualization that you did not define in the configuration file. This is expected, since all visualizations have a set of common controls that are automatically available.
12. Render the data as a table
In this section, you will update your visualization to display the Community Visualization sample data set as a table.
The data to render is available in the tables object and is structured based on the transform specified by your visualization. In this codelab the visualization requested the table format (tableTransform) which includes a headers object and a rows object that contains all of the data we need to render a table.
Step 1: Replace the contents of viz-codelab-src.js with the code below.
viz-codelab-src.js
function drawViz(data) {
// Container setup.
let container = document.getElementById('container');
if (container) {
container.textContent = '';
} else {
container = document.createElement('div')
container.id = 'container'
document.body.appendChild(container);
}
// Create the table.
const table = document.createElement('table');
const tableHeader = document.createElement('thead');
const tableBody = document.createElement('tbody');
data.tables.DEFAULT.headers.forEach(function (column) {
const tableColumn = document.createElement('th');
tableColumn.textContent = column.name;
tableHeader.appendChild(tableColumn);
});
data.tables.DEFAULT.rows.forEach(function(row) {
const tableRow = document.createElement('tr');
row.forEach(function(cell) {
const tableCell = document.createElement('td');
if (typeof cell == 'number') {
tableCell.textContent = new Intl.NumberFormat().format(cell);
} else {
tableCell.textContent = cell;
}
tableRow.appendChild(tableCell);
});
tableBody.appendChild(tableRow);
});
table.appendChild(tableHeader);
table.appendChild(tableBody);
// Render the table.
container.appendChild(table);
}
// Subscribe to data and style changes. Use the table format for data.
dscc.subscribeToData(drawViz, { transform: dscc.tableTransform });
Step 2: Prepare the JavaScript bundle file, then upload and overwrite your visualization files to Google Cloud Storage.
Step 3: Refresh the Looker Studio report to reload and test your community visualization. The table now renders data (i.e. the Google Sheet) and displays header columns based on the selected dimension and metric. Resize the visualization to see all rows.
13. Dynamically apply style changes
In this section, you will update the visualization to style the table header based on the fill color selected in the Style panel.
The state of all style elements is available in the style object, where each item key is defined based on your visualization style configuration (viz-codelab.json). For this section, you will get the selected fill color and use that to update the background color of the table header.
Step 1: Replace the code in your viz-codelab-src.js file with the code below.
viz-codelab-src.js
function drawViz(data) {
// Container setup.
let container = document.getElementById('container');
if (container) {
container.textContent = '';
} else {
container = document.createElement('div')
container.id = 'container'
document.body.appendChild(container);
}
// Create the table.
const table = document.createElement('table');
const tableHeader = document.createElement('thead');
const tableBody = document.createElement('tbody');
data.tables.DEFAULT.headers.forEach(function (column) {
const tableColumn = document.createElement('th');
tableColumn.textContent = column.name;
tableHeader.appendChild(tableColumn);
});
data.tables.DEFAULT.rows.forEach(function(row) {
const tableRow = document.createElement('tr');
row.forEach(function(cell) {
const tableCell = document.createElement('td');
if (typeof cell == 'number') {
tableCell.textContent = new Intl.NumberFormat().format(cell);
} else {
tableCell.textContent = cell;
}
tableRow.appendChild(tableCell);
});
tableBody.appendChild(tableRow);
});
table.appendChild(tableHeader);
table.appendChild(tableBody);
// Set header color based on style control.
tableHeader.style.backgroundColor = data.style.headerBg.value.color;
// Render the table.
container.appendChild(table);
}
// Subscribe to data and style changes. Use the table format for data.
dscc.subscribeToData(drawViz, { transform: dscc.tableTransform });
Step 2: Prepare the JavaScript bundle file, then upload and overwrite your visualization files to Google Cloud Storage.
Step 3: Refresh the Looker Studio report to reload and test your community visualization.
Step 4: Under the Style panel, use the Header Background Color style control to change the table header background color.
Congratulations! You've created a community visualization in Looker Studio! This brings you to the end of this codelab. Now, let's see what next steps you can take.
14. Next steps
Extend your visualization
- Learn more about the data and formats available to your visualization.
- Learn more about available style elements and add additional styling to your visualization.
- Add interactions to your visualization
- Learn to develop a visualization locally
Do more with community visualizations
- Review the references for the dscc helper library, manifest, and configuration file.
- Submit your visualization to our Community Visualization Gallery.
- Build a community connector for Looker Studio.
Additional resources
Below are various resources you can access to help you dig deeper into the material covered in this codelab.
Resource Type | User Features | Developer Features |
Documentation | ||
News & Updates | Sign up in Looker Studio > User Settings | |
Ask Questions | ||
Examples |