Criando uma lista suspensa interativa para parâmetros do Tableau usando a API JavaScript

Integração de parâmetros orientados pelo usuário aos painéis incorporados do Tableau

A incorporação de painéis do Tableau em aplicativos Web usando a API de incorporação do Tableau permite que os desenvolvedores forneçam soluções dinâmicas e baseadas em dados. Uma maneira poderosa de aprimorar a experiência do usuário é permitir a interação com os parâmetros do painel por meio de menus suspensos.

Neste exemplo, o desafio está em configurar um menu suspenso para manipular um parâmetro específico do Tableau chamado . Ao contrário dos filtros, que são mais fáceis de integrar, os parâmetros requerem um tratamento preciso para serem carregados e atualizados corretamente usando JavaScript.

Embora a API do Tableau forneça métodos para acessar parâmetros, pode ser complicado exibir corretamente os valores dos parâmetros disponíveis como opções suspensas e garantir atualizações contínuas quando os usuários fazem uma seleção.

O objetivo deste artigo é orientá-lo nas etapas de configuração do parâmetro com um menu suspenso. Você aprenderá como buscar valores permitidos, exibi-los no menu suspenso e garantir que os parâmetros sejam atualizados de maneira eficaz quando uma seleção for feita, resolvendo problemas comuns enfrentados pelos desenvolvedores.

Comando	Exemplo de uso
viz.workbook.getParametersAsync()	Esse método assíncrono recupera uma lista de todos os parâmetros disponíveis na pasta de trabalho do Tableau. É essencial carregar os dados dos parâmetros dinamicamente antes de interagir com eles no painel incorporado.
viz.workbook.changeParameterValueAsync()	Atualiza o valor de um parâmetro específico no Tableau. Ele garante que quando o usuário altera a seleção suspensa, o parâmetro na pasta de trabalho seja atualizado em tempo real.
allowableValues	Esta propriedade contém os valores permitidos para um parâmetro do Tableau. Ele é usado para preencher o menu suspenso com todas as opções de parâmetros válidas que os usuários podem selecionar.
currentValue.value	Acessa o valor atual de um parâmetro do Tableau. Isso garante que a seleção padrão do menu suspenso corresponda ao estado atual do parâmetro no painel.
document.createElement("select")	Cria um elemento suspenso
dropdown.addEventListener("change")	Adiciona um ouvinte de eventos ao menu suspenso para detectar alterações na seleção do usuário. Quando acionado, inicia o processo de atualização de parâmetros na pasta de trabalho do Tableau.
find((p) =>find((p) => p.name === "Moeda")	Usa o método find() no array de parâmetros para localizar o parâmetro "Moeda" específico. Isso garante que o parâmetro correto seja direcionado para atualizações.
viz.addEventListener(TableauEventType.FirstInteractive)	Este comando garante que a função para carregar o menu suspenso de parâmetros seja executada somente quando o painel do Tableau estiver totalmente carregado, evitando problemas de tempo.
option.value = value.value	Define o atributo value de um elemento
jest.fn().mockResolvedValue()	Usado em testes unitários para simular o comportamento de funções assíncronas. Isso garante que a lógica de atualização dos parâmetros seja simulada corretamente durante o teste, sem a necessidade de um ambiente ativo do Tableau.

Como controlar dinamicamente os parâmetros do Tableau usando JavaScript

Os scripts fornecidos acima foram projetados para permitir uma interação tranquila entre um painel do Tableau e um HTML personalizado. menu. Esses scripts usam a API de incorporação do Tableau, que permite aos desenvolvedores incorporar painéis do Tableau em aplicativos Web e ampliar sua interatividade. O foco principal é manipular um parâmetro chamado “Moeda” através de JavaScript, buscando seus valores permitidos e atualizando o parâmetro dinamicamente quando o usuário faz uma seleção.

A primeira parte do script começa com a função de carregar o parâmetro “Moeda”. Esta função aproveita o método para recuperar todos os parâmetros disponíveis na pasta de trabalho. Uma vez carregados os parâmetros, o script identifica o parâmetro específico "Moeda" usando o método. Se o parâmetro não for encontrado, ele registra um erro para evitar a quebra do restante do código. Isto é crucial, pois trabalhar com parâmetros requer saber se eles existem antes de prosseguir com a lógica.

Depois de identificar o parâmetro, um menu é criado dinamicamente usando métodos de manipulação DOM do JavaScript. Cada valor dos valores permitidos do parâmetro é adicionado como uma opção no menu suspenso. O script garante que o menu suspenso reflita o estado atual do parâmetro definindo a opção selecionada para o valor atual do parâmetro. Esta etapa é essencial para garantir que o usuário veja o valor mais recente no dashboard, fornecendo consistência entre o estado do dashboard e a opção padrão do menu suspenso.

A última parte do script envolve adicionar um ouvinte de evento ao menu suspenso. Este ouvinte de eventos detecta quando o usuário altera a opção selecionada e aciona o função para atualizar o parâmetro no Tableau. Além disso, o script garante que o menu suspenso só seja renderizado depois que o painel for totalmente carregado usando o comando evento. Isso garante que o menu suspenso não seja preenchido prematuramente, evitando erros ou valores de parâmetros ausentes. A solução é modular e escalável, facilitando a adaptação a outros parâmetros ou dashboards, reutilizando a mesma estrutura lógica.

// Solution 1: Basic Implementation Using Async/Await and Tableau API
async function loadMoedaParameter() {
  try {
    const parameters = await viz.workbook.getParametersAsync();
    const moedaParam = parameters.find((p) => p.name === "Moeda");
    if (!moedaParam) {
      console.error("Parameter 'Moeda' not found!");
      return;
    }
    const dropdown = document.createElement("select");
    moedaParam.allowableValues.forEach((value) => {
      const option = document.createElement("option");
      option.text = value.formattedValue;
      option.value = value.value;
      dropdown.appendChild(option);
    });
    dropdown.value = moedaParam.currentValue.value;
    dropdown.addEventListener("change", async (e) => {
      const selectedMoeda = e.target.value;
      try {
        await viz.workbook.changeParameterValueAsync("Moeda", selectedMoeda);
        console.log("Moeda changed to:", selectedMoeda);
      } catch (error) {
        console.error("Error changing the Moeda parameter:", error);
      }
    });
    document.getElementById("Moeda-container-desktop").appendChild(dropdown);
  } catch (error) {
    console.error("Error loading the Moeda parameter:", error);
  }
}
viz.addEventListener(TableauEventType.FirstInteractive, loadMoedaParameter);

// Solution 2: Modular and Reusable Code with Error Handling
function createDropdown(options, onChangeCallback) {
  const dropdown = document.createElement("select");
  dropdown.style.cssText = "border:none; width:100%; height:40px; background:#FFF;";
  options.forEach(({ text, value }) => {
    const option = document.createElement("option");
    option.text = text;
    option.value = value;
    dropdown.appendChild(option);
  });
  dropdown.addEventListener("change", (e) => onChangeCallback(e.target.value));
  return dropdown;
}

async function updateParameter(parameterName, value) {
  try {
    await viz.workbook.changeParameterValueAsync(parameterName, value);
    console.log(\`${parameterName} changed to: \${value}\`);
  } catch (error) {
    console.error("Error updating parameter:", error);
  }
}

async function loadParameterDropdown(containerId, parameterName) {
  try {
    const parameters = await viz.workbook.getParametersAsync();
    const param = parameters.find((p) => p.name === parameterName);
    if (!param) throw new Error(\`Parameter '\${parameterName}' not found!\`);
    const options = param.allowableValues.map((val) => ({
      text: val.formattedValue,
      value: val.value,
    }));
    const dropdown = createDropdown(options, (value) => {
      updateParameter(parameterName, value);
    });
    document.getElementById(containerId).appendChild(dropdown);
  } catch (error) {
    console.error("Error loading parameter dropdown:", error);
  }
}

viz.addEventListener(TableauEventType.FirstInteractive, () => {
  loadParameterDropdown("Moeda-container-desktop", "Moeda");
});

// Solution 3: Unit Test to Validate Parameter Changes
function mockVizWorkbook() {
  return {
    parameters: [{
      name: "Moeda",
      allowableValues: [{ value: "USD", formattedValue: "USD" }],
      currentValue: { value: "USD" },
    }],
    changeParameterValueAsync: jest.fn().mockResolvedValue(),
  };
}

test("Dropdown updates Moeda parameter correctly", async () => {
  const vizMock = { workbook: mockVizWorkbook() };
  const updateSpy = vizMock.workbook.changeParameterValueAsync;
  document.body.innerHTML = '<div id="Moeda-container-desktop"></div>'; 

  await loadParameterDropdown("Moeda-container-desktop", "Moeda");
  const dropdown = document.querySelector("select");
  dropdown.value = "USD";
  dropdown.dispatchEvent(new Event("change"));

  expect(updateSpy).toHaveBeenCalledWith("Moeda", "USD");
});

Práticas recomendadas para lidar com parâmetros do Tableau com JavaScript

Ao incorporar painéis do Tableau em aplicativos Web, os desenvolvedores muitas vezes precisam dinamizar os parâmetros para melhorar a interatividade do usuário. Um desafio importante é lidar com parâmetros como através de um menu suspenso em vez de usar filtros. Os parâmetros são mais complexos porque exigem chamadas de API para recuperar seus valores permitidos e precisam ser atualizados por meio de funções, como . Essa abordagem oferece aos usuários mais controle sobre visualizações de dados específicas no painel sem atualizar a página.

O gerenciamento de parâmetros nos painéis do Tableau envolve identificá-los corretamente com . Uma armadilha comum é que alguns parâmetros podem não estar disponíveis ou podem precisar de diferentes níveis de acesso, dependendo da configuração da pasta de trabalho. Portanto, é importante incluir o tratamento de erros para evitar que a lógica suspensa seja interrompida se um parâmetro não for encontrado. Outro aspecto a considerar é renderizar o menu suspenso somente depois que o painel estiver totalmente carregado. Usando o O evento garante que os elementos do painel estejam prontos antes de aplicar personalizações.

A otimização do desempenho também é crucial, especialmente ao lidar com grandes conjuntos de dados ou painéis com múltiplos parâmetros. Funções JavaScript como ajudam a restringir a pesquisa de parâmetros, mas o código deve permanecer modular para permitir escalabilidade futura. Os desenvolvedores também devem validar os valores dos parâmetros antes de atualizá-los para evitar inconsistências entre a interface do usuário e os dados do painel. Com essas estratégias, fica mais fácil gerenciar os parâmetros do Tableau com eficiência e criar painéis com uma experiência de usuário perfeita.

1. Qual é a diferença entre um parâmetro e um filtro no Tableau?
2. Os parâmetros permitem que os usuários passem valores específicos para o painel, enquanto os filtros limitam os dados mostrados com base em critérios. Os filtros atuam em conjuntos de dados, enquanto os parâmetros afetam campos ou cálculos específicos.
3. Por que meu menu suspenso permanece vazio ao buscar parâmetros?
4. Certifique-se de que função recupera o parâmetro com sucesso. Caso contrário, o parâmetro poderá estar oculto ou inacessível devido a restrições da pasta de trabalho.
5. Como posso garantir que o menu suspenso corresponda ao estado atual do parâmetro?
6. Use o propriedade para definir a opção padrão no menu suspenso. Isso mantém a IU e o painel alinhados.
7. Como posso lidar com erros ao atualizar parâmetros no Tableau?
8. Embrulhe o ligue para dentro de um bloco para lidar com quaisquer erros que ocorrem quando o parâmetro é atualizado.
9. Qual evento garante que o painel esteja pronto antes da personalização?
10. O O evento na API do Tableau sinaliza que o painel foi totalmente carregado e está pronto para outras interações, como adicionar um menu suspenso.

A incorporação de painéis interativos com menus suspensos parametrizados oferece maior flexibilidade aos usuários. Com uma configuração adequada, os desenvolvedores podem buscar parâmetros como e use a API do Tableau para aprimorar o controle do painel. Esta configuração permite que os usuários explorem os dados de forma mais eficaz.

Elementos-chave, como o eventos e tratamento robusto de erros, garantem que os menus suspensos funcionem perfeitamente no aplicativo. Seguindo essa abordagem, os desenvolvedores podem gerenciar parâmetros com eficiência e oferecer aos usuários finais uma experiência de painel dinâmica e responsiva.