Referencia de la biblioteca de componentes comunitarios de Data Studio (dscc)

Descripción general de la API

La biblioteca dscc permite crear componentes comunitarios para Data Studio. El código fuente está disponible en GitHub.

dscc expone tres funciones: getWidth(), getHeight() y subscribeToData().

getWidth()

Nombre Parámetros Tipo de resultado devuelto Descripción
getWidth() None number Devuelve la anchura del iframe en píxeles.

Usar getWidth()

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

getHeight()

Nombre Parámetros Tipo de resultado devuelto Descripción
getHeight() None int Devuelve la altura del iframe en píxeles.

Usar getHeight()

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

sendInteraction()

La función sendInteraction() envía un mensaje a Data Studio con los datos de un filtro.

Parámetros:

Nombre Tipo Descripción
actionID string Cadena que corresponde a actionID en la configuración.
interaction enum(InteractionType) Informa a Data Studio sobre la interacción.
data object(InteractionData) Proporciona los datos necesarios para llevar a cabo una interacción.

InteractionType

De momento, el único parámetro InteractionType válido es FILTER.

Nombre Tipo Descripción
dscc.InteractionType.FILTER Enum Describe la interacción FILTER.

Usar 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))
    }
    
Campo Tipo Descripción
concepts Array Matriz de fieldIds.
values Array<Array> Matriz anidada de valores de datos. La longitud de cada submatriz debe coincidir con la de la matriz concepts. Cada uno de los valores de la submatriz corresponde a un valor de dimensión.

Ejemplo de interactionData:

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

Usar dscc.sendInteraction con el objeto interactionData indicado arriba equivale a la siguiente declaración SQL:

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

clearInteraction()

La función clearInteraction() envía un mensaje a Data Studio para borrar un filtro que esta visualización ha definido previamente.

Parámetros:

Nombre Tipo Descripción
actionID string Cadena que corresponde a actionID en la configuración.
interaction enum(InteractionType) Informa a Data Studio sobre la interacción.

Usar 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)

La función subscribeToData() realiza la suscripción a los mensajes de Data Studio.

Parámetros:

Nombre Tipo Descripción
callback(data) function Función que recoge los datos que subscribeToData devuelve.
options object Define el formato que tendrán los datos devueltos.

El objeto options tiene este aspecto:

{
      transform: dscc.tableTransform | dscc.objectTransform
    }
    

Valor devuelto:

Tipo Descripción
function Cancela la suscripción de callback a mensajes futuros de Data Studio.

Usar 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

Este es el objeto enviado al parámetro callback, que está registrado con dscc.subscribeToData. Estos son los campos que se comparten entre dscc.objectFormat y dscc.tableFormat.

{
      fields: object(fieldsByConfigId),
      style: object(styleById),
      interactions: object(interactionsById),
      theme: object(themeStyle),
      tables: object(tablesById)
    }
    
Campo Tipo Descripción
fields object(fieldsByConfigId) Objeto que contiene objetos field indexados por su configId.
style object(styleById) Objeto que contiene objetos style indexados por su configId.
interactions object(interactionsById) Objeto que contiene objetos interaction.
theme themeStyle Objeto themeStyle que contiene información sobre estilo de temas del informe.
tables object(tablesById) Objeto que contiene objetos tableObject.

fieldsByConfigId

{
       configId: array(field)
    }
    

El objeto fieldsByConfigId contiene matrices de objetos field indexados por el "id" que se ha definido en la configuración de la visualización. Hay una entrada en este objeto para cada objeto dataField definido en la configuración.

Campo Tipo Descripción
configId Array<field> Matriz de campos asociados con dataField.

field

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

El objeto field proporciona información sobre el campo que el usuario selecciona en el panel de propiedades.

Campo Tipo Descripción
id string ID que Data Studio genera para el campo.
name string Nombre del campo legible por personas.
description string Descripción del campo.
type enum(fieldType) Tipo semántico (semanticType) del campo.
concept enum(conceptType) Tipo de concepto (conceptType) del campo.

styleById

{
       configId: styleValue
    }
    

El objeto styleById proporciona información de estilo indexada por el "id" que se ha definido en la configuración de visualización.

Campo Tipo Descripción
configId styleValue Objeto que contiene el valor de estilo y el valor de estilo predeterminado que se ha definido en la configuración.

styleValue

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

El objeto styleValue proporciona tanto el valor de estilo que ha seleccionado el usuario como el valor predeterminado que se ha definido en la configuración. El tipo de value y defaultValue dependen del elemento style.

Campo Tipo Descripción
value string OR object OR bool OR number Valor del elemento de estilo que ha devuelto la selección del usuario en el panel de propiedades.
defaultValue string OR object OR bool OR number Valor predeterminado del elemento de estilo que se ha definido en la configuración de la visualización.

interactionsById

{

    }
    

El objeto interactionsById proporciona datos de interacción que ha indexado la configuración de visualización de interactionId.

Índice Tipo Descripción
configId interaction Objeto que contiene datos asociados con una interacción.

interactionField

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

El objeto interactionField contiene la matriz de acciones supportedActions que se ha definido en la configuración, así como los valores que ha seleccionado el usuario para la interacción.

Campo Tipo Descripción
value string OR object OR bool OR number Valor del elemento de estilo que ha devuelto la selección del usuario en el panel de propiedades.
supportedActions Array<InteractionType> Acciones compatibles con esta interacción, según se han definido en la configuración.

interactionValue

El objeto interactionValue proporciona valores que ha seleccionado el usuario para el tipo de interacción en cuestión. Si existe la clave data, el objeto InteractionData refleja el estado del filtro en ese momento. Si no existe la clave data, se debe a que la visualización no está configurada en ese momento como un filtro.

{
      type: enum(InteractionType)
      data: object(interactionData) | None
    }
    
Campo Tipo Descripción
type enum(InteractionType) Función InteractionType que ha seleccionado el usuario.
data object(InteractionData) El objeto data asociado con el estado del filtro. Esta clave no existe si el filtro se ha borrado.

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
        }
      ]
    }
    

El objeto themeStyle envía información sobre el tema del informe a la visualización.

Campo Tipo Descripción
fillColor object Objeto con el formato {color: string, opacity: number}.
fontColor object Objeto con el formato {color: string, opacity: number}.
accentFillColor object Objeto con el formato {color: string, opacity: number}.
accentFontColor object Objeto con el formato {color: string, opacity: number}.
fontFamily string Cadena que describe el conjunto de fuentes.
accentFontFamily string Cadena que describe el conjunto de fuentes con acento.
increaseColor object Objeto con el formato {color: string, opacity: number}.
decreaseColor object Objeto con el formato {color: string, opacity: number}.
gridColor object Objeto con el formato {color: string, opacity: number}.
seriesColor Array<object> Matriz de objetos con el formato {color: string, opacity: number}.

tablesById

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

El objeto tableObject proporciona información sobre el encabezado y los datos de cada fila. "DEFAULT" siempre devolverá datos, y "COMPARISON" solo se rellenará si el usuario configura los datos con filas de comparación.

El formato de tableObject es la única diferencia entre dscc.tableFormat y dscc.objectFormat.

Campo Tipo Descripción
"DEFAULT" object(tableObject) OR Array<objectRow> Objeto tableObject asociado a los datos que un usuario añade a una visualización.
"COMPARISON" object(tableObject) OR Array<objectRow> Objeto tableObject asociado a los datos de comparación de fechas, si corresponde.

Referencia de tableFormat

tableObject

{
      headers: array(object),
      rows: array(array)
    }
    
Campo Tipo Descripción
headers Array Matriz de objetos field. Estos objetos tienen, además, una propiedad configId correspondiente a los ID de la configuración.
rows Array<Array> Matriz de matrices, donde cada matriz es una fila de datos.

Datos tableFormat de muestra

Se trata de datos (data) de muestra que se devuelven al usar dscc.subscribeToData() con la opción 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": {},
      "interactions": {
        "onClick": {
          "value": {
            "type": "FILTER",
            "data": {
              "concepts": [
                "qt_h6oibrb6wb",
                "qt_i6oibrb6wb"
              ],
              "values": [
                [
                  "Afternoon",
                  "Sunday"
                ],
                [
                  "Afternoon",
                  "Thursday"
                ],
                [
                  "Morning",
                  "Tuesday"
                ]
              ]
            }
          },
          "supportedActions": [
            "FILTER"
          ]
        }
      }
    }
    

Referencia de objectFormat

objectRow

{
      configId1: array(string | bool | number),
      configId2: array(string | bool | number)
    }
    
Campo Tipo Descripción
configId array Matriz de valores asociada con un determinado ID de configuración.

Datos objectFormat de muestra

Se trata de datos (data) de muestra que se devuelven al usar dscc.subscribeToData() con la opción 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": {},
      "interactions": {
        "onClick": {
          "value": {
            "type": "FILTER",
            "data": {
              "concepts": [
                "qt_h6oibrb6wb",
                "qt_i6oibrb6wb"
              ],
              "values": [
                [
                  "Afternoon",
                  "Sunday"
                ],
                [
                  "Afternoon",
                  "Thursday"
                ],
                [
                  "Morning",
                  "Tuesday"
                ]
              ]
            }
          },
          "supportedActions": [
            "FILTER"
          ]
        }
      }
    }