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

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

Descripción general de la API

getWidth()

Usar getWidth()

getHeight()

Usar getHeight()

sendInteraction()

InteractionType

Usar sendInteraction

interactionData

clearInteraction()

Usar clearInteraction()

subscribeToData(callback, options)

Usar subscribeToData()

data

fieldsByConfigId

field

styleById

styleValue

interactionsById

interactionField

interactionValue

theme

tablesById

Referencia de tableFormat

tableObject

Datos tableFormat de muestra

Referencia de objectFormat

objectRow

Datos objectFormat de muestra

`getWidth()`

Usar `getWidth()`

`getHeight()`

Usar `getHeight()`

`InteractionType`

Usar `sendInteraction`

`interactionData`

Usar `clearInteraction()`

`subscribeToData(callback, options)`

Usar `subscribeToData()`

`data`

Referencia de `tableFormat`

Datos `tableFormat` de muestra