Using the helper library

Looker Studio uses the postMessage interface to provide data and styling information to the iframe containing the community visualization. This guide provides more detail on using the helper library.

For community visualizations, ds-component serves two functions.

1. Obtain the dimensions of the iframe
2. Manage communication with Looker Studio

Subscribing to events

When a user interacts with your visualization, such as changing selected fields, style, or resizing the component, Looker Studio sends events to your visualization.

dscc.subscribeToData registers a callback that will be invoked for each postMessage event from Looker Studio. The callback is passed a data object.

function drawViz(data){
  // obtain the height and width to scale your visualization appropriately
  var height = dscc.getHeight();
  var width = dscc.getWidth();
  // write your visualization code here
  console.log("I'm the callback and I was passed this data: " + JSON.stringify(data, null, '  '));
}

// call drawViz every time Looker Studio sends a new postMessage
dscc.subscribeToData(drawViz, {transform: dscc.objectTransform});

The returned data

Both data transforms return an object with five keys.

Key	Purpose
style	User-selected and default style information
fields	User-selected fields information
interactions	User-selected interactions
theme	Report theme information
tables	Rows of data
dateRanges	Default and comparison date ranges

Format of the data:

{
  fields: object(fieldsByConfigId),
  style: object(styleById),
  interactions: object(interactionsById),
  theme: object(themeStyle),
  tables: object(tablesById),
  dateRanges: object(dateRangesById),
}

Different visualizations require different data formats. Two common formats are an array of arrays or an array of objects. The ds-component library provides two transforms, which are designed to get you straight to these data formats.

The two transforms are documented in the library-reference. These transforms map easily to data formats commonly expected by JavaScript visualization libraries. The two supported transforms are: objectTransform, which returns an array of objects, and tableTransform, which returns an array of arrays.

dscc.objectTransform

Some visualizations expect data as an array of objects.

For example:

var data = [
  {'colA': 'hello', 'colB', 'world'},
  {'colA': 'hello', 'colB', 'world'}
];

The following code shows how to access an array of objects from the dscc.objectTransform format.

function drawViz(data){
  // what the object transform could look like
  // [
  //  {'configId1': ['hello'], 'configId2': [1] },
  //  {'configId1': ['world'], 'configId2': [2] }
  // ]
  var dsccObjectTransformData = data.tables.DEFAULT;

  // creating an array of objects
  var arrayOfObjects = dscc.ObjectTransformData.rows.map(function(d){
    return {
      'configId1': d.configId1[0],
      'configId2': d.configId2[0]
    };
  };

}

If data sections are defined such that a user can input multiple fields (for example, if there were two dimensions defined for a sankey diagram), then the transform will depend on your use case, as the data format returned by Looker Studio will look more like:

var dsccObjectTransformData = [
{'configId1': ['hello', 'there'], 'configId2': [1] },
{'configId1': ['world', 'globe'], 'configId2': [2] }
]

Note: The data transformations needed will depend on your visualization config.

dscc.tableTransform

Some visualization libraries expect an array of arrays.

For example:

var data = [
  ['hello', 1],
  ['world', 2]
];

The following code shows how to access a row of rows from the dscc.tableTransform format.

function drawViz(data);
  // what the below object looks like
  // {
  //    headers: [{
  //      "id": "qt_ky8sltutsb",
  //      "name": "dimension",
  //      "type": "TEXT",
  //      "concept": "DIMENSION",
  //      "configId": "configId1"
  //    }, {
  //      "id": "qt_m9dtntutsb",
  //      "name": "metric",
  //      "type": "NUMBER",
  //      "concept": "METRIC",
  //      "configId": "configId2"
  //    }],
  //  rows: [
  //    ['hello', 1],
  //    ['world', 2]
  //  ];
  // }
  var dsccTableTransformObject = data.tables.DEFAULT;

  // accessing the row of rows
  var rowOfRows = dsccTableTransformObject.rows;

  // accessing the header row
  var headers = dsccTableTransformObject.headers;
}

dscc.subscribeToData(drawViz, {transform: tableTransform});