Controle de detalhamento dinâmico

O recurso de controle de detalhamento dinâmico permite que o visual habilite ou desabilite o recurso de detalhamento de forma dinâmica fazendo uma chamada à API. Quando o recurso de detalhamento está habilitado, todas as funcionalidades de drill down e os recursos de expansão/recolhimento estão disponíveis, incluindo chamadas à API, comandos de menu de contexto, botões de detalhamento de cabeçalho e suporte a dados de hierarquia. Quando desabilitadas, essas funcionalidades não estão disponíveis.

As imagens a seguir mostram um exemplo de um visual com o recurso de controle de detalhamento dinâmico habilitado e desabilitado:

O recurso de controle de detalhamento dinâmico inclui os seguintes elementos de API:

• O sinalizador isDrillDisabled no DataRolesInfo:

  export interface DataRolesInfo {
        //…
        isDrillDisabled?: boolean; // ----- NEW -----
    }
  

• O método setCanDrill na interface IVisualHost:

    export interface IVisualHost extends extensibility.IVisualHost {
        //…
        setCanDrill: (drillAllowed: boolean) => void; // ----- NEW -----
    }
  

Para identificar se o detalhamento está desabilitado, use a propriedade isDrillDisabled no método de atualização:

    private update(options: VisualUpdateOptions) {
      //…
      const isDrillDisabled = options.dataViews[0].metadata.dataRoles.isDrillDisabled;
      //…
    }

Em seguida, use a chamada à API para habilitar ou desabilitar o detalhamento conforme necessário:

• Para habilitar: this.host.setCanDrill(true /* drillAllowed */);

• Para desabilitar: this.host.setCanDrill(false /* drillAllowed */);

Requisitos do controle de detalhamento dinâmico

O detalhamento é habilitado por padrão, mas o recurso de controle de detalhamento dinâmico permite que o visual habilite ou desabilite o detalhamento usando uma chamada à API.

Um visual com o recurso de controle de detalhamento dinâmico tem o seguinte código no arquivo capabilities.json:

• Com o detalhamento desabilitado por padrão:

      "drilldown": {
          "roles": [
              "Rows",
              "Columns"
          ],
          "canDisableDrill": { 
              "disabledByDefault": true
          }
      },
  

• Com o detalhamento habilitado por padrão:

      "drilldown": {
          "roles": [
              "Rows",
              "Columns"
          ],
          "canDisableDrill": {}
      },
  

A propriedade canDisableDrill indica que o visual dá suporte a esse recurso. Sem essa propriedade, a chamada à API não será respeitada.
A propriedade disabledByDefault indica se o recurso de detalhamento deve ou não ser desabilitado por padrão.

Adicionar suporte a drill down a uma nova versão de um visual existente

Usar o recurso de drill down representa uma alteração interruptiva. Portanto, para uma transição mais tranquila, recomendamos que você use um novo GUID visual para a nova versão.

Se, no entanto, você quiser manter o mesmo GUID, tenha em mente os seguintes pontos:

• Quando você migra de uma versão que não permite o detalhamento para uma nova versão que permite, alguns dados podem não ser fornecidos no dataView devido ao suporte a dados hierárquicos introduzidos como parte do recurso de detalhamento. O recurso de controle de detalhamento dinâmico não oferece suporte automático para esse problema, mas pode ser usado para gerenciar o processo de migração.

• Para a auto-migração do visual, o visual deve executar as seguintes ações:

  • Identifique a primeira vez que a nova versão é carregada em vez da versão mais antiga e aplique a API persistProperties.

  • Desabilite o detalhamento para receber todos os dados usando a API setCanDrill.

O exemplo a seguir mostra como fazer a auto-migração de um visual mais antigo para um que usa o controle de detalhamento dinâmico:

1. Adicione o seguinte objeto ao arquivo capabilities.json:

   "DrillMigration": {
     "displayName": "Drill Migration",
     "properties": {
         "isMigrated": {
             "displayName": "Is Drill Migrated",
             "type": {
                 "bool": true
             }
         }
     }
   },
   

2. Adicione o seguinte ao arquivo visual.ts:

   export class Visual implements IVisual {
       //...
         private isCalledToDisableDrillInMigrationScenario = false;
         private drillMigration = { disabledByDefault: true };
         constructor(options: VisualConstructorOptions) {
          //...
          this.host = options.host;
          //...
         }
         private update(options: VisualUpdateOptions) {
            this.handleSelfDrillMigration(options);
             //...
         }
         private handleSelfDrillMigration(options: VisualUpdateOptions): void {
             if (options && options.dataViews && options.dataViews[0] && options.dataViews[0].metadata) {
                 const metadata = options.dataViews[0].metadata;
                 if (metadata && metadata.dataRoles) {
                     const isDrillDisabled = metadata.dataRoles.isDrillDisabled;
                     if (isDrillDisabled === undefined) {
                         return;
                     }
                     // Continue in case the visual is already migrated
                     if (!metadata.objects?.DrillMigration?.isMigrated) {
                         // Persist the isMigrated property when the drill has the correct state
                         if (this.drillMigration.disabledByDefault === isDrillDisabled) {
                             this.persistMigrationProperty();
                         } else if (!this.isCalledToDisableDrillInMigrationScenario) {
                             // Use the API call only once
                             this.host.setCanDrill(!this.drillMigration.disabledByDefault);
                             this.isCalledToDisableDrillInMigrationScenario = true;
                         }
                     }
                 }
             }
         }
         private persistMigrationProperty(): void {
             let property = {
                 merge: [{
                     objectName: "DrillMigration",
                     properties: {
                         isMigrated: true
                     },
                     selector: null
                 }]
             };
             this.host.persistProperties(property);
         }
     }
   

Na primeira vez que o visual é aberto depois de adicionar esse código, a variável DrillMigration é definida como true e o visual é aberto no estado padrão.

Considerações e limitações

• O estado de detalhamento não é salvo depois de desabilitar o detalhamento. Se você reabilitar o detalhamento depois de desabilitá-lo, somente o primeiro nível será exibido independentemente do que foi exibido antes de ser desabilitado.

• O estado de expansão/recolhimento não é salvo depois de desabilitar o detalhamento. Todas as linhas são recolhidas depois que o detalhamento for habilitado novamente.

• Não há suporte para a chamada à API para dashboards.

• Condições de mapeamento da exibição de dados: use "max": 1 para todas as condições da função de detalhamento para limitar o visual a mostrar apenas um campo quando o detalhamento estiver desabilitado. Por exemplo:

  • Para exibição de dados categóricos:

    "conditions": [
         { "category": { "min": 1 }, "measure": { "max": 1 }}
    ]
    

  • Para exibição de dados de matriz:

    "conditions": [
        { "Rows": { "max": 0 }, "Columns": { "max": 0 }, "Value": { "min": 1 } },
        { "Rows": { "min": 1 }, "Columns": { "min": 0 }, "Value": { "min": 0 } },
        { "Rows": { "min": 0 }, "Columns": { "min": 1 }, "Value": { "min": 0 } },
    ]