Elementos

Visão Geral

Widgets em App Builder permite que os desenvolvedores forneçam código de terceiros (ou seu próprio) para mostrar um Controle personalizado na página. Os widgets permitem que você defina mais metadados, veja a seção Conteúdo do Arquivo de Arquivo para detalhes. Os parâmetros agora suportam uma definição mais robusta, veja a seção API do Widget para detalhes.

Veja a Biblioteca de download de widgets para obter uma lista de widgets suportados que você pode usar em 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á interagido em dispositivos touch e não touch.

3. Os widgets devem respeitar a edição automática e o salvamento automático. Os widgets obterão esse comportamento de App Builder automaticamente.

Conteúdo do Arquivo de Arquivo

_manifest.json

Todos os widgets incluem um arquivo manifest. 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, bem como 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 abaixo para mais informações.

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

• 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 matriz 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

• version: Número da versão do Widget. Incremente esse número para garantir que os usuários recebam a última edição do seu código.

• createdOn: Data em que esta versão foi lançada. Apenas para fins informativos.

• dependências: Lista delimitada por vírgulas de quaisquer dependências necessárias para seu binder de Widget. A ordem em que esses arquivos aparecem corresponderá à ordem em que aparecerão na matriz de dependências da API de Widget. 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.

  title="Manifest Entry" "javascript": [], "css": []

encadernador.js

encadernador.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 o App Builder API para suas bibliotecas. Em cada uma, dois parâmetros de função são fornecidos.

• holderElement: Um elemento DOM que contém a marcação HTML fornecida no arquivo de modelo especificado. Como esse 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 quaisquer dependências 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 callback de instalação definido no binder precisará renderizar qualquer 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 contendo 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 para alterações e existem em uma linha de uma tabela.

valor - sequência de caracteres
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) é "25%". Ou um controle de lista pode ter um valor de um GUID, enquanto o valor formatado é o primeiro e o último nome 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á obtém novos dados.

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

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

• value
• formattedValue
• disabled

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

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. App Builder também pode desabilitar células quando eventos estão sendo executados.

App Builder passará um único parâmetro para o retorno de chamada fornecido contendo o valor alterado. No caso de desabilitado, o valor é 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 conforme 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
Parâmetros para 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 que você definir, 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: Use o valor de exibição formatado.
    • Ativo: Indica se esta ligação está ativa ou não. Ligações inativas não serão usadas.
  • Coluna:
    • Coluna de Destino: Uma coluna da tabela de origem do painel pai que fornecerá este valor de parâmetro.
    • Usar valor formatado: Use o valor de exibição formatado.
    • Ativo: Indica se esta ligação está ativa ou não. Ligações inativas não serão usadas.
  • Valor estático:
    • Valor: Valor estático para o parâmetro.
    • Traduzível: Se habilitado, permite que o widget seja traduzido quando aplicável.
    • Ativo: Indica se esta ligação está ativa ou não. Ligações inativas não serão usadas.

Como construir um widget e solução de problemas

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

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 $ 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 de App Builder no seu widget
App Builder pode atualizar o valor por meio de padrões ou alterações nos registros pais. Sua biblioteca precisará ser capaz de se atualizar quando esses eventos acontecerem.

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

Além disso, ao instalar uma biblioteca, você normalmente precisará definir o valor inicial da célula fornecida. App Builder não executará o Change Callback na instalação, somente quando os eventos exigirem.

Carregando novas versões e depurando
Depois que você tiver um widget operacional e estiver depurando um erro, siga as seguintes etapas:

1. Compacte o conteúdo da pasta local em que está trabalhando (certifique-se de não compactar a pasta pai em si, isso criará uma pasta extra no arquivo zip)
2. Carregue para 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.

Estado de visualização vs. edição
Ao adicionar um widget a um painel, você pode especificar se seu widget manipulará a renderização do estado de edição e visualização. Se seu widget manipular apenas o estado de edição, App Builder renderizará o valor da célula quando estiver no estado de exibição.

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

Para fazer isso, você precisa alternar a linha para o estado de edição, se ainda não estiver. 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
Grandes recursos como o JQuery UI levam muito tempo para baixar e instalar. Para fins de desempenho, é recomendável que apenas bibliotecas leves ou bibliotecas que usam App Builder dependências são implementadas. Alguns erros foram relatados quando as dependências carregam muito lentamente.

Trabalhando com dados binários
Algumas células em App Builder pode 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 imagem. Veja a biblioteca Image Resizer no App Builder coleção para código de exemplo.

row.ViewModel
A versão atual de App Builder expõe um parâmetro chamado ViewModel na API de linha. Isso fornece acesso ao App Builder dados de back-end e não será garantido que funcionem durante a atualização App Builder. Não é recomendado escrever código que dependa dessa propriedade.

Widgets do site

Os widgets também podem ser "nível do site". Isso é definido no nível do widget e eles são usados via Centro 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, o que significa que a página não esperará para se renderizar 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 do site em App Builder

1. Vá para App Workbench > Look & Feel > 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: Dial Widget
5. Clique em Procurar e localize o arquivo .zip do Widget contendo 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 todos os 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 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 callbacks que são executados quando o local 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

App Builder suporta atalhos de teclado, com o qual algumas bibliotecas de widgets podem entrar em conflito.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 dado 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 ligações de teclado, 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>

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

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