Looker Studio Community Component (dscc) library reference

Overview of the API

dscc (Looker Studio Community Component) is a library to help with building community components for Looker Studio. The source code can be found on GitHub.

dscc exposes three functions: getWidth(), getHeight(), and subscribeToData().

`getWidth()`

Name	Parameters	Return Type	Description
getWidth()	None	`number`	Returns the width of the iframe, in pixels

Using `getWidth()`

// to get the width of the iframe
var width = dscc.getWidth();

`getHeight()`

Name	Parameters	Return Type	Description
getHeight()	None	`int`	Returns the height of the iframe, in pixels

Using `getHeight()`

// to get the height of the iframe
var height = dscc.getHeight();

sendInteraction()

The sendInteraction() function sends a message to Looker Studio with the data for a filter.

Parameters:

Name	Type	Description
actionID	`string`	The string that corresponds to the actionId in the config
interaction	`enum(InteractionType)`	Tells Looker Studio about the interaction
data	`object(InteractionData)`	Provides the required data for an interaction

`InteractionType`

Currently, the only valid InteractionType is FILTER.

Name	Type	Description
dscc.InteractionType.FILTER	Enum	Describes the `FILTER` interaction

Using `sendInteraction`


// the actionID can either be hardcoded or parsed from the returned data
var actionId = "interactionConfigId";

// dscc provides enums for the interaction types
var FILTER = dscc.InteractionType.FILTER;

var fieldID = "qt_m9dtntutsb";
var dataValue = "Asia";

// sendInteraction expects data that tells you the concepts and the values of
// those concepts to use in constructing a filter.
var interactionData = {
  "concepts": [fieldId],
  "values": [[dataValue]]
}

dscc.sendInteraction(actionId, FILTER, interactionData);

`interactionData`

var interactionData = {
  "concepts": array(fieldId),
  "values": array(array(dataValue))
}

Field	Type	Description
concepts	`Array`	Array of `fieldIds`
values	`Array<Array>`	Nested array of data values. Each subarray should be the length of the `concepts` array. Each value in the subarray corresponds to a dimension value.

Sample interactionData:

var interactionData = {
  "concepts": ["dim1Id", "dim2Id"],
  "values": [
    ["dim1Val1", "dim2Val1"],
    ["dim1Val2", "dim2Val2"]
    ]
}

Using dscc.sendInteraction with the above interactionData is equivalent to the following SQL statement:

SELECT data WHERE
  (dim1 == dim1Val1 AND dim2 == dim2Val1)
  OR
  (dim1 == dim1Val2 AND dim2 == dim2Val2);

clearInteraction()

The clearInteraction() function sends an message to Looker Studio to clear a filter previously set by this visualization.

Parameters:

Name	Type	Description
actionID	`string`	The string that corresponds to the actionId in the config
interaction	`enum(InteractionType)`	Tells Looker Studio about the interaction

Using `clearInteraction()`


// the actionID can either be hardcoded or parsed from the returned data
var actionId = "interactionConfigId";

// dscc provides enums for the interaction types
var FILTER = dscc.InteractionType.FILTER;

dscc.clearInteraction(actionId, FILTER);

`subscribeToData(callback, options)`

The subscribeToData() function subscribes to messages from Looker Studio.

Parameters:

Name	Type	Description
callback(data)	`function`	A function that takes the data returned by `subscribeToData`.
options	`object`	Defines the desired data return format

The options object looks like:

{
  transform: dscc.tableTransform | dscc.objectTransform
}

Return value:

Type	Description
`function`	Unsubscribes `callback` from further messages from Looker Studio

Using `subscribeToData()`

// define and use a callback
var unsubscribe = dscc.subscribeToData(function(data){
  // console.log the returned data
  console.log(data);
}, {transform: dscc.tableTransform});

// to unsubscribe

unsubscribe();

`data`

This is the object passed to the callback registered with dscc.subscribeToData. These following are the fields that are shared between dscc.objectFormat and dscc.tableFormat.

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

Field	Type	Description
fields	`object(fieldsByConfigId)`	An object that contains fields indexed by their configId
style	`object(styleById)`	An object that contains style objects indexed by their configId
interactions	`object(interactionsById)`	An object that contains interaction objects
theme	`themeStyle`	A themeStyle object that contains theme styling information for the report
tables	`object(tablesById)`	An object that contains tableObjects
dateRanges	`object(dateRangesById)`	An object that contains dateRanges

fieldsByConfigId

{
   configId: array(field)
}

The fieldsByConfigId object contains arrays of field objects indexed by the "id" defined in the visualization config. There is one entry in this object for each dataField defined in the config.

Field	Type	Description
configId	`Array<field>`	An array of field(s) associated with the dataField

field

{
  id: fieldId,
  name: string,
  description: string,
  type: fieldType,
  concept: enum(conceptType)
}

The field object provides information about the field that the user selects in the property panel.

Field	Type	Description
id	`string`	The Looker Studio generated ID for the field
name	`string`	The human-readable field name
description	`string`	The description of the field
type	`enum(fieldType)`	The semanticType of the field
concept	`enum(conceptType)`	The conceptType of the field

styleById

{
   configId: styleValue
}

The styleById object provides style information indexed by the "id" defined in the visualization config.

Field	Type	Description
configId	`styleValue`	An object that contains the style value and the config-defined default style value

styleValue

{
  value: string | object | bool | number,
  defaultValue: string | object | bool | number
}

The styleValue object provides both the user-selected style value and the default value defined in the config. The type of value and defaultValue depend on the style element.

Field	Type	Description
value	`string OR object OR bool OR number`	The value of the style element returned from user selection in the property panel
defaultValue	`string OR object OR bool OR number`	The default value of the style element defined in the visualization config

interactionsById

{

}

interactionsById object provides interaction data indexed by the interactionId visualization config.

Index	Type	Description
configId	`interaction`	An object that contains data associated with an interaction

interactionField

{
  value: object(interactionValue),
  supportedActions: array(InteractionType)
}

The interactionField object contains the array of supportedActions defined in the config, as well as the user-selected values for the interaction.

Field	Type	Description
value	`string OR object OR bool OR number`	The value of the style element returned from user selection in the property panel
supportedActions	`Array<InteractionType>`	The actions supported by this interaction, as defined in the config

interactionValue

The interactionValue object provides user-selected values for the interaction type. If the data key exists, the InteractionData object reflects the current state of the filter. If the data key does not exist, the visualization is not currently configured as a filter.

{
  type: enum(InteractionType)
  data: object(interactionData) | None
}

Field	Type	Description
type	`enum(InteractionType)`	The user-selected InteractionType
data	`object(InteractionData)`	The data associated with the current state of the filter. This key does not exist if the filter is currently cleared.

theme

{
  fillColor: {
    color: string,
    opacity: number
  },
  fontColor: {
    color: string,
    opacity: number
  },
  accentFillColor: {
    color: string,
    opacity: number
  },
  accentFontColor: {
    color: string,
    opacity: number
  },
  fontFamily: string,
  accentFontFamily: string,
  increaseColor: {
    color: string,
    opacity: number
  },
  decreaseColor: {
    color: string,
    opacity: number
  },
  gridColor: {
    color: string,
    opacity: number
  },
  seriesColor: [
    {
      color: string,
      opacity: number
    }
  ]
}

The themeStyle object passes report theme information to the visualization.

Field	Type	Description
fillColor	`object`	An object of the format `{color: string, opacity: number}`
fontColor	`object`	An object of the format `{color: string, opacity: number}`
accentFillColor	`object`	An object of the format `{color: string, opacity: number}`
accentFontColor	`object`	An object of the format `{color: string, opacity: number}`
fontFamily	`string`	A string describing the font family
accentFontFamily	`string`	A string describing the accent font family
increaseColor	`object`	An object of the format `{color: string, opacity: number}`
decreaseColor	`object`	An object of the format `{color: string, opacity: number}`
gridColor	`object`	An object of the format `{color: string, opacity: number}`
seriesColor	`Array<object>`	An array of objects of the format`{color: string, opacity: number}`

tablesById

{
  "DEFAULT": object(tableObject),
  "COMPARISON": object(tableObject) | undefined
}

The tableObject provides heading and data information for each row. "DEFAULT" always will return data, and "COMPARISON" will only be populated if the user configures the data with comparison rows.

The format of the tableObject is the only difference between dscc.tableFormat and dscc.objectFormat.

Field	Type	Description
"DEFAULT"	`object(tableObject) OR Array<objectRow>`	The `tableObject` associated with the data a user adds to a visualization
"COMPARISON"	`object(tableObject) OR Array<objectRow>`	The `tableObject` associated with the date comparison data, if applicable

dateRangesById

{
  "DEFAULT": object(dateRange),
  "COMPARISON": object(dateRange)
}

The dateRangesById object provides information about default and comparison date ranges. If there are no date ranges, the object will be empty. DEFAULT and COMPARISON will only be populated if the respective date ranges are configured by the user. The data in the date ranges are related to the default and comparison data as defined in tablesById.

Field	Type	Description
"DEFAULT"	`object(dateRange)`	The `dateRange` associated with the default date range, if applicable.
"COMPARISON"	`object(dateRange)`	The `dateRange` associated with a comparison date range, if applicable.

dateRange

{
  start: string,
  end: string
}

The dateRange object provides information about the start and end dates of a default or comparison date range.

Field	Type	Description
start	`string`	Start date of date range in YYYYMMDD format.
end	`string`	End date of date range in YYYYMMDD format.

`tableFormat` reference

tableObject

{
  headers: array(object),
  rows: array(array)
}

Field	Type	Description
headers	`Array`	An array of fields objects. These field objects additionally have a `configId` property that corresponds to the IDs from the config.
rows	`Array<Array>`	An array of arrays: each array is a row of data

Sample `tableFormat` data

This is sample data returned by using dscc.subscribeToData() with the option dscc.tableFormat.

{
  "tables": {
    "DEFAULT": {
      "headers": [{
        "id": "qt_ky8sltutsb",
        "name": "dimension",
        "type": "TEXT",
        "concept": "DIMENSION",
        "configId": "configId1"
      }, {
        "id": "qt_b5bvmtutsb",
        "name": "second dim",
        "type": "TEXT",
        "concept": "DIMENSION"
        "configId": "configId1"
      }, {
        "id": "qt_m9dtntutsb",
        "name": "metric",
        "type": "NUMBER",
        "concept": "METRIC",
        "configId": "configId2"
      }],
      "rows": [
        ["Week 4", "lm", 55]
      ]
    },
    "COMPARISON": {
      "headers": [{
        "id": "qt_ky8sltutsb",
        "name": "dimension",
        "type": "TEXT",
        "concept": "DIMENSION",
        "configId": "configId1"
      }, {
        "id": "qt_b5bvmtutsb",
        "name": "second dim",
        "type": "TEXT",
        "concept": "DIMENSION"
        "configId": "configId1"
      }, {
        "id": "qt_m9dtntutsb",
        "name": "metric",
        "type": "NUMBER",
        "concept": "METRIC",
        "configId": "configId2"
      }],
      "rows": [
        ["Week 5", "no", 123]
      ]
    }
  },
  "fields": {
    "configId1": [
      {
        "id": "qt_ky8sltutsb",
        "name": "week",
        "type": "TEXT",
        "concept": "DIMENSION"
      },
      {
        "id": "qt_b5bvmtutsb",
        "name": "textId",
        "type": "TEXT",
        "concept": "DIMENSION"
      }
    ],
    "configId2": [
      {
        "id": "qt_m9dtntutsb",
        "name": "orders",
        "type": "NUMBER",
        "concept": "METRIC"
      }
    ]
  },
  "style": {
    "nodeColor": {
      "value": {
        "color": "#000000"
      }
    }
  },
  "theme": {},
  "dateRanges": {
    "DEFAULT": {
      "start": "20210501",
      "end": "20210531"
    },
    "COMPARISON": {
      "start": "20200501",
      "end": "20200531"
    }
  },
  "interactions": {
    "onClick": {
      "value": {
        "type": "FILTER",
        "data": {
          "concepts": [
            "qt_h6oibrb6wb",
            "qt_i6oibrb6wb"
          ],
          "values": [
            [
              "Afternoon",
              "Sunday"
            ],
            [
              "Afternoon",
              "Thursday"
            ],
            [
              "Morning",
              "Tuesday"
            ]
          ]
        }
      },
      "supportedActions": [
        "FILTER"
      ]
    }
  }
}

objectFormat reference

objectRow

{
  configId1: array(string | bool | number),
  configId2: array(string | bool | number)
}

Field	Type	Description
configId	array	array of values associated with a particular config ID

Sample objectFormat data

This is sample data returned by using dscc.subscribeToData() with the option dscc.objectFormat.

{
  "tables": {
    "COMPARISON": [
      {
        "configId1": ["Week 5", "cd"],
        "configId2": [123]
      }
    ],
    "DEFAULT": [
      {
        "configId1": ["Week 1", "ab"],
        "configId2": [24]
      }
    ]
  },
  "fields": {
    "configId1": [
      {
        "id": "qt_h6oibrb6wb",
        "name": "time of day",
        "type": "TEXT",
        "concept": "DIMENSION"
      },
      {
        "id": "qt_i6oibrb6wb",
        "name": "day",
        "type": "TEXT",
        "concept": "DIMENSION"
      }
    ],
    "configId2": [
      {
        "id": "qt_m9dtntutsb",
        "name": "metric",
        "type": "NUMBER",
        "concept": "METRIC"
      }
    ]
  },
  "style": {
    "nodeColor": {
      "value": {
        "color": "#000000"
      }
    }
  },
  "theme": {},
  "dateRanges": {
    "DEFAULT": {
      "start": "20210501",
      "end": "20210531"
    },
    "COMPARISON": {
      "start": "20200501",
      "end": "20200531"
    }
  },
  "interactions": {
    "onClick": {
      "value": {
        "type": "FILTER",
        "data": {
          "concepts": [
            "qt_h6oibrb6wb",
            "qt_i6oibrb6wb"
          ],
          "values": [
            [
              "Afternoon",
              "Sunday"
            ],
            [
              "Afternoon",
              "Thursday"
            ],
            [
              "Morning",
              "Tuesday"
            ]
          ]
        }
      },
      "supportedActions": [
        "FILTER"
      ]
    }
  }
}

Looker Studio Community Component (dscc) library reference

Overview of the API

getWidth()

Using getWidth()

getHeight()

Using getHeight()

sendInteraction()

InteractionType

Using sendInteraction

interactionData

clearInteraction()

Using clearInteraction()

subscribeToData(callback, options)

Using subscribeToData()

data

fieldsByConfigId

field

styleById

styleValue

interactionsById

interactionField

interactionValue

theme

tablesById

dateRangesById

dateRange

tableFormat reference

tableObject

Sample tableFormat data

objectFormat reference

objectRow

Sample objectFormat data

`getWidth()`

Using `getWidth()`

`getHeight()`

Using `getHeight()`

`InteractionType`

Using `sendInteraction`

`interactionData`

Using `clearInteraction()`

`subscribeToData(callback, options)`

Using `subscribeToData()`

`data`

`tableFormat` reference

Sample `tableFormat` data