Widgets no Jitterbit App Builder

Visão geral

Widgets no App Builder permitem que os desenvolvedores forneçam código de terceiros (ou seu próprio) para exibir um Controle personalizado na página. Widgets permitem definir mais metadados; consulte a seção Conteúdo do Arquivo para obter detalhes. Os parâmetros agora oferecem suporte a uma definição mais robusta; consulte a seção API de Widgets para obter detalhes.

Veja a Biblioteca de download de widgets para obter uma lista de widgets suportados que você pode usar no App Builder.

Diretrizes de widgets

1. Os widgets devem mostrar o valor subjacente, ou deve ser óbvio qual é o valor subjacente.

   • Bom: Valor exibido

     
     

   • Bom: Valor óbvio

     
     

   • Ruim:

     

2. Teste de widget. Lembre-se de considerar como o widget será utilizado em dispositivos sensíveis ao toque e não sensíveis ao toque.

3. Os widgets devem respeitar a edição e o salvamento automáticos. Os widgets receberão esse comportamento automaticamente do App Builder.

Conteúdo do arquivo compactado

_manifest.json

Todos os widgets incluem um arquivo de manifesto. Você pode definir mais metadados neste arquivo, conforme descrito abaixo.

{
    "name": "Slider",
    "developer": "App Builder",
    "binder": "binder.js",
    "template": "view.html",
    ...
    "targetContainer": false,
    "purpose": "Site",
    "parameters": [
        {
            "name": "Parameter name",
            "default": "default value",
            "translate": true
        }
    ]
}

• name: O nome do widget que aparecerá no App Builder IDE e também se tornará o nome do arquivo compactado.

• developer: O nome de usuário do desenvolvedor que trabalha neste widget.

• binder: O nome do arquivo do binder do widget. Veja mais informações abaixo.

• template: O nome do arquivo HTML do modelo. Veja mais informações abaixo.

• targetContainer: Suporta o valor true ou false.

• purpose: Suporta o valor definido de Site ou Field, que indica como o widget deve ser usado.

• parameters: Suporta uma série de metadados de parâmetros, para cada:

  • name: o nome do parâmetro
  • default: uma string contendo o valor padrão
  • translate: suporta o valor true ou false

• versão: Número da versão do widget. Aumente esse número para garantir que os usuários recebam a versão mais recente do seu código.

• createdOn: Data de lançamento desta versão. Apenas para fins informativos.

• dependências: Lista delimitada por vírgulas de todas as dependências necessárias para o seu binder de widgets. A ordem em que esses arquivos aparecem corresponderá à ordem em que aparecerão na matriz de dependências da API de widgets. Certifique-se de incluir a extensão do arquivo.

  • JavaScript
  • CSS

  Por exemplo, se você definir uma biblioteca que retorna uma referência que você precisa usar para instalar em um elemento:

  Manifest Entry

  "javascript": [
    "noUiSlider.8.0.2/nouislider.js",
    "noUiSlider.8.0.2/nouislider_extras.js"
  ]
  

  O contexto da sua API de widget incluiria ambos os objetos:

  Usage

  var install = function (holderElement, context) {
    var sliderLibrary = context.loadedDependencies[0];
    sliderLibrary.createSlider(holderElement);
  }
  

  Nota

  Mesmo que você não tenha dependências, inclua as propriedades JavaScript e CSS com um array vazio.

  Manifest Entry

  "javascript": [],
  "css": []
  

binder.js

fichário.js

define(function () {
    return {
        callbacks: {
            events: {
                install: function (holderElement, context) {},
                uninstall: function (holderElement, context) {}
            }
        }
    };
});

O binder fornece dois retornos de chamada necessários para vincular a API do App Builder às suas bibliotecas. Em cada um deles, são fornecidos dois parâmetros de função.

• holderElement: Um elemento DOM que contém a marcação HTML fornecida no arquivo de modelo especificado. Como este arquivo é opcional, o elemento holder pode estar vazio. O elemento holder é a célula que o widget implementará. É a área destacada na captura de tela abaixo e não inclui o rótulo do campo.
  

  

• context: Uma instância do contexto da API Widget. Este objeto contém todas as dependências de JavaScript especificadas no binder, bem como acesso aos dados na célula e no painel.

• view.html (opcional): Este arquivo contém todo o HTML estático necessário para carregar este widget. Se não for especificado, o widget será criado sem nenhum conteúdo e o retorno de chamada de instalação definido no binder precisará renderizar o HTML necessário.

API de widgets

obterCélula()
Retorna uma instância do WidgetApiCell.

obterLinha()
Retorna uma instância do WidgetApiRow.

isEditState() - booleano
Identifica se a linha é editável.

getParameter(nome) - string
Recuperará o parâmetro definido do valor padrão ou da célula nesta linha que foi nomeada pelo designer.

loadedDependencies
Uma propriedade que contém uma matriz de objetos retornados por RequireJS. Essa matriz é fornecida na mesma ordem em que as dependências são definidas no arquivo _manifest.json.

WidgetApiCell
Representa uma única célula. As células são o modelo de visualização de apoio do controle visto na página. Elas contêm valores, podem ser monitoradas quanto a alterações e existem em uma linha de uma tabela.

valor - string
Esta propriedade pode ser usada para obter e definir o valor subjacente da célula.

customTextbox.on('change', function (value) {
    cell.value = value;
});

formattedValue - string
Esta propriedade pode ser usada para obter e definir o valor de exibição subjacente da célula. Por exemplo, o valor subjacente de um campo de porcentagem seria 0,25, enquanto o valor de exibição (valor formatado) seria "25%". Ou, um controle de lista poderia ter o valor de um GUID, enquanto o valor formatado seria o nome e o sobrenome de um cliente.

persistedValue - string
Esta propriedade pode ser usada para obter o valor persistente subjacente da célula. Um valor persistente é o valor não editado atualmente armazenado na fonte de dados. Isso pode ser usado para reverter uma célula para um estado limpo.

setDataChangeCallback
Esta função é usada para definir retornos de chamada a serem executados quando o formulário em que o widget está localizado obtiver novos dados.

context.setDataChangeCallback(function () {
   var updatedMin = parseInt(context.getParameter("Min"), 10);
});

setChangeCallback(nome: string, valor: Função)
Esta função é usada para definir retornos de chamada em uma célula. Os seguintes retornos de chamada nomeados podem ser definidos:

• valor
• valorformatado
• desativado

cell.setChangeCallback('value', function (value) {
    console.log("The cell's value has been changed to", value);
});

O App Builder pode causar alterações na célula durante eventos de validação, se valores padrão forem definidos ou se outro widget causar alterações que afetem esta célula. O App Builder também pode desabilitar células durante a execução de eventos.

O App Builder passará um único parâmetro para o retorno de chamada fornecido contendo o valor alterado. Caso esteja desabilitado, o valor será true ou false.

dropChangeCallback(nome: string)
Remove a assinatura de um retorno de chamada de alteração.

Linha WidgetApi
Representa uma linha na fonte de dados. Esta linha contém a célula que o widget está implementando.

getCellByColumnName(nome: string) - WidgetApiCell
Retorna uma instância de uma célula nesta linha. O nome diferencia maiúsculas de minúsculas e deve corresponder ao nome definido no controle, não ao nome da fonte de dados.

editar()
Altera a linha para o modo de edição.

salvar()
Salva quaisquer valores modificados de volta na fonte de dados.

deleteRow()
Tentará excluir a linha da fonte de dados.

Parâmetros
Os parâmetros de um widget podem ser definidos no nível do painel. Ao adicionar um parâmetro, o desenvolvedor pode configurar:

• Parâmetro do widget: Nome atribuído ao valor do parâmetro.

• Tipo de parâmetro: Padrão para Control, também pode ser definido como Column ou Static Value. Dependendo do Tipo definido, você terá valores diferentes para configurar adequadamente:

  • Controle:
    • Controle de destino: um controle do painel pai que fornecerá este valor de parâmetro.
    • Usar valor formatado: usar o valor de exibição formatado.
    • Ativo: indica se esta vinculação está ativa ou não. Vinculações inativas não serão utilizadas.
  • Coluna:
    • Coluna de destino: uma coluna da tabela de origem do painel pai que fornecerá este valor de parâmetro.
    • Usar valor formatado: usar o valor de exibição formatado.
    • Ativo: indica se esta vinculação está ativa ou não. Vinculações inativas não serão utilizadas.
  • Valor estático:
    • Valor: Valor estático para o parâmetro.
    • Traduzível: se ativado, permite que o widget seja traduzido quando aplicável.
    • Ativo: indica se esta vinculação está ativa ou não. Vinculações inativas não serão utilizadas.

Como construir um widget e solução de problemas

Widgets são uma tela em branco. O App Builder executará o código do widget em vez da implementação do App Builder.

Mostrando o valor atual
Se você estiver renderizando um termômetro, por exemplo, provavelmente precisará incluir o valor atual junto com o nível de mercúrio. (veja o texto de exemplo de US$ 3.500 abaixo)

No entanto, um widget de classificação por estrelas pode não precisar indicar o valor real da célula.

Obtendo e definindo o valor do App Builder no seu widget
O App Builder pode atualizar o valor por meio de padrões ou alterações nos registros pai. Sua biblioteca precisará ser capaz de se atualizar quando esses eventos ocorrerem.

Fornecer retornos de chamada permite que o App Builder execute seu código quando precisar enviar novos valores para o seu widget. Veja setChangeCallback acima.

Além disso, ao instalar uma biblioteca, normalmente você precisará definir o valor inicial da célula fornecida. O App Builder não executará o retorno de chamada de alteração na instalação, apenas quando os eventos exigirem.

Carregando novas versões e depuração
Depois que você tiver um widget operacional e estiver depurando um erro, siga os seguintes passos:

1. Compacte o conteúdo da pasta local em que você está trabalhando (certifique-se de não compactar a pasta pai, pois isso criará uma pasta extra no arquivo zip)
2. Carregue o arquivo zip do widget no aplicativo Look & Feel
3. Pressione "Atualizar" na página usando seu widget. Observação: pode ser necessário desabilitar o cache do navegador durante o desenvolvimento, caso contrário, você pode acabar com um código obsoleto.

Visualizar vs. Editar estado
Ao adicionar um widget a um painel, você pode especificar se o widget processará a renderização dos estados de edição e visualização. Se o widget processar apenas o estado de edição, o App Builder renderizará o valor da célula quando estiver no estado de visualização.

Se o seu widget manipula ambos os estados, seu controle PODE ser usado para editar valores sem precisar clicar primeiro no botão de edição da barra de ferramentas.

Para fazer isso, você precisa alternar a linha para o estado de edição, caso ainda não esteja. Aqui está um exemplo:

if (!context.isEditState()) {
  context.getRow().edit();
}
context.getCell().value = myNewValueVariable;
context.getRow().save();

Você também pode usar a propriedade isEditState para renderizar uma versão "somente leitura" do widget que exibe o valor, mas não pode ser usada para modificar a célula.

Carregando grandes dependências
Recursos grandes, como o JQuery UI, levam muito tempo para baixar e instalar. Para fins de desempenho, recomenda-se implementar apenas bibliotecas leves ou bibliotecas que utilizem dependências existentes do App Builder. Alguns erros foram relatados quando as dependências demoram muito para carregar.

Trabalhando com dados binários
Algumas células no App Builder podem conter dados binários armazenados como uma string base64. Bibliotecas podem ser usadas para modificar e armazenar dados nessas células, como utilitários de edição de imagens. Consulte a biblioteca Image Resizer na coleção App Builder para obter um exemplo de código.

linha.ViewModel
A versão atual do App Builder expõe um parâmetro chamado ViewModel na API de linha. Isso fornece acesso aos dados de back-end do App Builder e não há garantia de que funcione ao atualizar o App Builder. Não é recomendável escrever código que dependa dessa propriedade.

Widgets do site

Os widgets também podem ser "de nível de site". Isso é definido no nível do widget e eles são usados em Central de Controle > Configurações da Instância > Widgets do Site.

Os widgets do site são executados assim que o navegador carrega. Isso permite que o código seja executado o mais rápido possível. O código será executado de forma assíncrona, ou seja, a página não esperará para ser renderizada até que o código seja executado.

Os parâmetros do site não são vinculados a dados, eles suportam apenas valores de texto simples.

Como adicionar um widget de site no App Builder

1. Vá para App Workbench > Aparência > Widgets
   
2. Selecione a Coleção à qual deseja adicionar o widget
   
3. Clique no botão + Widget
4. Forneça um Nome para o widget. Por exemplo: Widget de Discagem
5. Clique em Procurar e localize o arquivo .zip do widget que contém todos os arquivos do widget necessários, selecione-o e clique em Abrir
6. Forneça qualquer Documentação para descrever o widget. As informações de texto de ajuda que aparecem no IDE para um widget são fornecidas pelo registro do widget.
7. Clique em Salvar
8. No painel Parâmetros do widget, clique em + Parâmetro e defina quaisquer parâmetros necessários para o widget
9. Na página que executará seu widget, selecione o widget na região Informações do widget do Control Designer e defina os valores de Interface e Modo ativo
   

API

getParameter(nome) - string
Recuperará o parâmetro definido do valor padrão ou do parâmetro fornecido pelo designer por meio da definição do widget do site.

getCurrentPageLocation() - sequência de caracteres
Obtém o URL atual da página.

getCurrentAuthenticationUserName() - sequência de caracteres
Obtém o nome de usuário conectado no momento ou nulo se não estiver autenticado.

onPageLocationChange(manipulador: Função(evento))
Esta função é usada para definir retornos de chamada que são executados quando a localização da página muda. Retornará o caminho como uma string.

onAuthenticationChange(handler: Function(event))
Esta função é usada para definir retornos de chamada que são executados quando o usuário autenticado muda. Retornará o nome de usuário como uma string.

Solução de problemas

O App Builder suporta atalhos de teclado, com o qual algumas bibliotecas de widgets podem entrar em conflito. O App Builder atualmente suporta as seguintes teclas de atalho: text; enter; esc; left-arrow; up-arrow; right-arrow; down-arrow; backtick; e delete.

As instruções a seguir permitem que você desabilite o suporte a teclas de atalho para um determinado elemento HTML e seus elementos filhos.

Para ignorar todos os atalhos de teclado, use uma classe CSS ou o valor do campo de dados vinyl-hotkeys-ignore:

• <div class="vinyl-hotkeys-ignore"></div>
• <div data-vinyl-hotkeys-ignore="true"></div>

Para ignorar apenas algumas combinações de teclas, adicione-as ao sufixo da classe CSS. Se houver mais de uma palavra, coloque-as em hífen no sufixo da classe CSS:

• <div class="vinyl-hotkeys-ignore-text"></div>
• <div data-vinyl-hotkeys-ignore-text="true"></div>
• <div class="vinyl-hotkeys-ignore-left-allow"></div>
• <div data-vinyl-hotkeys-ignore-left-allow="true"></div>

O App Builder ignorará automaticamente os campos de texto e divs marcados como conteúdo editável:

• <div contenteditable="true"></div>