Crie códigos para os formulários do Microsoft Dynamics 365

 

Publicado: janeiro de 2017

Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

A programação de formulário fornece maneiras de interagir com formulários de entidade usando o JavaScript que é executado para eventos que ocorrem no formulário.

Neste tópico

Quando usar a programação de formulário

Fatores que devem ser considerados ao usar a programação de formulário

Gerenciar dependências da biblioteca

Scripts de formulário de gravação em funcionam corretamente

Apresentações de formulário diferentes

Ferramentas de desenvolvimento

Quando usar a programação de formulário

O Microsoft Dynamics 365 fornece várias opções para controlar os processos empresariais. A programação de formulário é uma opção. Mas lembre-se de que você tem outra opção: regras comerciais. As regras de negócios oferecem um método para quem não conhece o JavaScript e não é um desenvolvedor para aplicar a lógica de negócios em um formulário. Consulte o tópico do guia de personalização: TechNet: criar e editar regras de negócios para obter mais informações.

A principal vantagem da programação de formulário e regras de negócios é que é imediata. Não exigem que os dados sejam enviados para o servidor e, portanto, não fornecerem o melhor desempenho para vários cenários. Como eles permitem a interação humana, eles também são a opção mais flexível.

Enquanto as regras de negócios têm uma vantagens porque podem ser criadas e mantidas por um usuário que não é um desenvolvedor, com determinadas limitações e não é destinada a substituir scripts de formulário. A programação de formulário permite obter coisas que ainda não podem ser executadas com regras de negócios.

As tarefas geralmente executadas com a programação de formulário incluem:

• Validação de Dados: sempre que possível, você deve executar uma validação de dados enquanto os dados estão sendo editados. A definição do campo Formulário executará a validação dos dados mais comuns para você. Por exemplo, um campo Single Line of Text formatado para um endereço de email não permitirá que um valor inválido seja inserido.

  Use a programação de formulário para validação adicional de dados que são exclusivas para sua organização. Por exemplo, sua organização pode ter regras específicas sobre como os números de telefone devem ser formatados ou o tamanho mínimo do campo Subject em uma atividade de serviço.

• Automação: você pode obter melhorias significativas de produtividade ao usar script de formulários para automatizar tarefas comuns. Você pode definir os valores de campos que dependem dos dados inseridos em um formulário, que ajudarão a economizar tempo considerável dos usuários ao inserir dados. Usar a programação de formulário para automação é valioso porque permite ao usuário verificar que um processo padrão é válido em uma ocorrência específica. Os usuários podem realizar ajustes necessários antes de salvar um registro.

• Melhoria e imposição do processo: você pode personalizar quais dados exibir no formulário ou o layout no formulário para otimizá-lo para tarefas específicas realizadas por pessoas de sua organização. Você pode usar a programação de formulário para mostrar ou ocultar elementos de formulário específicos ou abrir formulários diferentes que foram definidos para uma entidade. É possível controlar quais campos são obrigatórios com base nos dados presentes no formulário ou em registros relacionados.

  Com o Atualização do Microsoft Dynamics CRM 2015 e Microsoft Dynamics CRM Online 2015 você pode escrever código para controlar os fluxos de processo empresarial que aparecem na parte superior dos formulários.Para obter mais informações:Criar scripts para fluxos de processos de negócios.

Fatores que devem ser considerados ao usar a programação de formulário

A lógica aplicada na programação de formulário pode ser executada apenas no navegador de um usuário interagindo dentro do formulário de entidade do aplicativo Microsoft Dynamics 365. Dessa forma, você não precisa confiar apenas na programação de formulário para iniciar ou impor processos relacionados aos seus dados. Os registros podem ser criados ou atualizado diretamente com os APIs do serviço Web ou com fluxos de trabalho fora do contexto do formulário. A programação do formulário deve complementar a lógica de negócios aplicada usando plug-ins e processos de forma que todos os registros criados ou atualizados de alguma forma sigam as mesmas com processos.

As regras comerciais podem ser definidas para execução no escopo da entidade para que a mesma lógica seja aplicada no mesmo servidor independente da origem da ação.Para obter mais informações:Criar ou editar regras de negócios

Enquanto a programação de formulário fornece recursos fornecer ocultar campos de formulário para que os usuários possam exibir ou atualizar alguns dados da entidade, não representa uma solução completa dos requisitos de aplicação da segurança. Um usuário pode ver os dados de entidade que não estão visíveis no formulário com uma variedade de métodos, como Localização Avançada.Para obter mais informações:O modelo de segurança do Microsoft Dynamics 365

Gerenciar dependências da biblioteca

Como otimização de desempenho, os formulários Microsoft Dynamics 365 carregam recursos da Web JavaScript de maneira assíncrona e em paralelo. Isso significava que a ordem em que as bibliotecas são configuradas para um formulário não garante que uma biblioteca será totalmente baixada e inicializada antes de outra biblioteca tentar usar um dos objetos definidos nela.

Se você tiver um código que dependa de outra biblioteca para ser totalmente baixado e inicializado, a abordagem mais simples será combinar as bibliotecas em um único recurso da Web JavaScript com o código abaixo do código da biblioteca. Uma abordagem mais sofisticada é usar bibliotecas como head.js ou require.js para controlar o modo como as bibliotecas separadas serão carregadas.

Scripts de formulário de gravação em funcionam corretamente

Quando você grava scripts para formulários, use as seguintes práticas para ajudá-lo a obter o melhor desempenho:

• Evite incluir bibliotecas de recursos da Web de Javascript desnecessárias
  Quanto mais scripts você adiciona ao formulário, mais tempo levará para baixá-los. Os scripts geralmente são armazenados em cache no navegador depois de serem carregados pela primeira vez, mas o desempenho na primeira vez que um formulário é exibido geralmente cria uma boa impressão.

  Para um exemplo em particular, não inclua o jQuery em seus scripts de formulários apenas porque você deseja usar o XMLHttpRequests. Enquanto o jQuery tenha a função $.ajax que muitas pessoas estão familiarizadas para executar essas solicitações, é preferência do desenvolvedor, não necessidade. É possível executar estas solicitações usando o objeto XMLHttpRequest nativo encontrado em todos os navegadores com suporte do Microsoft Dynamics 365.Para obter mais informações:Uso do jQuery

• Evite carregar todos os scripts no evento Onload
  Se você tiver um código que oferece suporte apenas para eventos do OnChange para campos ou o evento OnSave, certifique-se de definir a biblioteca de scripts com o manipulador de eventos para esses eventos ao invés do evento OnLoad. Dessa forma, carregar essas bibliotecas pode atrasar e aumentar o desempenho ao carregar formulários.

  Não é recomendável usar o método addOnChange no manipulador de eventos OnLoad apenas como uma questão de conveniência. Embora isso possa reduzir o número de etapas necessárias para adicionar manipuladores de eventos, faz com que o formulário carregue mais lentamente.

• Use para guias ocultas para atrasar o carregamento de recursos da Web
  Quando os recursos da Web ou IFRAMES são incluídos nas seções em uma guia recolhida, eles não serão carregados se a guia for recolhida. Serão carregados quando a guia for expandida. Quando o estado da guia muda, o evento TabStateChange ocorre. Um código necessário para oferecer suporte aos recursos da Web ou IFRAMEs nas guias recolhidas pode usar manipuladores de eventos para o evento TabStateChange e reduzir o código que pode ocorrer no evento OnLoad.

• Definir opções de visibilidade padrão
  Evite usar scripts de formulário no evento OnLoad que ocultam elementos do formulário. Em vez disso, defina as opções de visibilidade padrão para elementos do formulário que possam estar ocultos e não estar visíveis por padrão ao carregar formulários. Em seguida, use scripts no evento OnLoad para mostrar os elementos de formulário que deseja exibir.

Apresentações de formulário diferentes

Há várias maneiras diferentes dos formulários serem apresentados. Eles afetam o tipo de código ou eventos disponíveis que você pode usar para cada um.

Renderização de formulário herdado

Na Atualização 1 do Microsoft Dynamics CRM Online 2015 e no Dynamics 365 (local), uma nova configuração de sistema: Usar renderização de formulário herdado foi introduzida. Nessas versões, houve aperfeiçoamento na renderização de formulário e alteração na estrutura interna da página. Como resultado, os scripts de formulários que usavam métodos sem suporte não poderão acessar elementos do DOM que foram disponibilizados em versões anteriores. Em caso de novos erros após a atualização para essas versões, você pode tentar aplicar essa configuração para ver se os erros somem. Em caso positivo, verifique se os scripts que causam esses erros estão usando métodos sem suporte.

Você pode definir Usar renderização de formulário herdado para dar tempo para resolver esses problemas; contudo, não terá os aperfeiçoamentos de desempenho oferecidos pela nova infraestrutura de renderização de formulário.

Observação

A configuração Usar renderização de formulário herdado será removida da próxima versão principal. Quando isso ocorrer, todos os scripts de formulários deverão funcionar com a nova renderização de formulário.

Entidades atualizadas

Todas as entidades personalizadas e determinadas entidades do sistema têm uma interface do usuário que inclui usando a barra de comandos e APIs de novo formulário. As entidades do sistema atualizadas são listadas na tabela a seguir:

Conta	Compromisso	Campanha
Atividade da Campanha	Resposta de Campanha	Ocorrência
Concorrente	Contato	Contrato
Linha do Contrato (ContractDetail)	Email	Qualificação
Modelo de Direito	Fax	Fatura
Produto da Fatura ((InvoiceDetail) *	Cliente Potencial	Carta
Lista de Marketing	Oportunidade	Produto da Oportunidade
Ordem	Produto do Pedido (SalesOrderDetail) *	Telefonema
Posição	Item da Lista de Preços	Produto
Associação do Produto	Relacionamento de Produtos (ProductSubstitute).	Fila
Campanha Rápida (Operação em Massa)	Cotação	Cotar Produto (QuoteDetail) *
Compromisso Recorrente (RecurringAppointmentMaster)	Especificações	SLA
Instância do KPI de SLA	Atividade Social	Perfil Social
Tarefa	Equipe	Usuário

* Essas entidades foram atualizadas no CRM Online 2016 Atualização 1 e no Dynamics 365 Service Pack 1 (local).

Observação

Algumas entidades atualizadas inclui atributos compostos. Exigem considerações especiais.Para obter mais informações:Scripts de gravação para atributos compostos.

Formulários de entidade atualizados também podem incluir um controle colaboração que forneçam acesso às atividades, anotações e postagens se estiverem habilitadas para a entidade. O objeto Xrm.Page não fornece acesso ao controle de colaboração. Você pode acessar o elemento de seção que contém o controle de colaboração se deseja mostrar ou ocultar usando scripts.

Os métodos de programação de formulário e evento PreSearch para entidades atualizadas

A tabela a seguir lista os métodos de programação de formulário disponíveis somente para entidades atualizadas.

Método	Descrição
Xrm.Page.context.cliente.getClient	Retorna um valor para indicar qual cliente o script está executando.
Xrm.Page.context.cliente.getClientState	Retorna um valor para indicar o estado do cliente.
Xrm.Page.context.getUserName	Retorna o nome do usuário atual.
Xrm.Page.data.entity.getPrimaryAttributeValue	Obtém uma cadeia de caracteres para o valor do atributo principal da entidade.
Xrm.Page.data.refresh	Atualiza de maneira assíncrona os dados do formulário sem recarregar a página.
Xrm.Page.data.Salvar	Salva o registro de maneira assíncrona com a opção para definir funções de retorno de chamadas a serem realizadas depois da operação de salvar ser concluída.
Xrm.Page.data.entity attribute.getIsPartyList	Determina se um atributo de pesquisa representa uma pesquisa de partylist.
Xrm.Page.ui control.clearNotification	Remove uma mensagem já exibida para um controle.
Xrm.Page.ui control.setNotification	Exibe uma mensagem próxima ao controle para indicar que os dados não são válidos.
Xrm.Page.ui.clearFormNotification	Use este método para remover as notificações de nível do formulário.
Xrm.Page.ui.setFormNotification	Use este método para exibir as notificações de nível do formulário.
Xrm.Page.ui control.addCustomFilter	Use o fetchXml para adicionar mais filtros aos resultados exibidos na pesquisa. Cada filtro será combinados com os filtros adicionados anteriormente como uma condição “E.
Xrm.Page.ui control.setShowTime	Especifica se um controle de data deve mostrar a parte de hora da data.
Xrm.Utility.alertDialog	Exibe um diálogo de alerta de não bloqueio com uma função de retorno de chamada.
Xrm.Utility.confirmDialog	Exibe um diálogo de confirmação de não bloqueio com retornos de chamada diferentes dependendo do botão que o usuário clicar.

Evento PreSearch

O novo Evento de pré-pesquisa ocorre logo antes da caixa de diálogo de pesquisa abrir ao definir um valor de pesquisa. Este evento não tem uma interface de usuário para definir um manipulador de eventos no aplicativo; só pode ser definido usando o método Xrm.Page.ui control.addPreSearch. Use este evento com os métodos addCustomFilter, addCustomView e setDefaultView para controlar as exibições abertas quando as pessoas pesquisam um registro para definir como o valor do campo de pesquisa.

Entidades que usam formulários clássicos

Entidades do sistema que não foram atualizadas usam a apresentação de formulário clássica. Os formulários para essas entidades continuam a usar a faixa de opções se fizeram isso no CRM 2011 e não têm acesso aos APIs do formulário adicionados nesta versão. Essas entidades são listadas na tabela a seguir:

Endereço	Artigo	Comentário sobre o Artigo	Operação de Exclusão em Massa	Unidade de Negócios
Conexão	Desconto	Lista de Descontos	Local do Documento	Anexo de Email
Seguir	Meta	Métrica de Meta	Arquivo de Origem da Importação	Produto da Fatura
Produto do Pedido	Lista de Preços	Item da Fila	Produto da Cotação	Campo de Acúmulo
Consulta Acumulada	Exibição Salva	Serviço	Atividade de Serviço	Site do SharePoint
Local	Região	Unidade	Grupo de Unidades

Entidades habilitadas para o Dynamics 365 para tablets

Somente entidades do sistema selecionadas e entidades personalizadas estão disponível para serem exibidas usando o Microsoft Dynamics 365 para Tablets. As seguintes entidades do sistema podem ter formulários editáveis no Dynamics 365 para tablets.

Conta	Atividade	Compromisso	Ocorrência
Concorrente	Conexão	Contato	Cliente Potencial
Anotação	Oportunidade	Produto da Oportunidade	Telefonema
Item da Fila	Atividade Social	Perfil Social	Tarefa

Como o Dynamics 365 para tablets não tem os mesmos comportamentos que formulários no aplicativo web, alguns APIs não estão disponíveis. Por exemplo, as guias Dynamics 365 para tablets não podem ser expandidas ou recolhidas, portanto, o Evento TabStateChange da guia não ocorre e o Xrm.Page.ui tab.setDisplayState não pode ser usado para expandir ou recolher guias.Para obter mais informações:Escrever e depurar scripts para o Dynamics 365 para telefones e tablets.

Ferramentas de desenvolvimento

Use boas ferramentas para melhorar sua experiência ao escrever o JavaScript para formulários Dynamics 365.

Usar boas ferramentas de criação

Como o JavaScript é uma linguagem interpretada, não há necessidade de ferramentas de desenvolvimento especiais. O JavaScript é apenas texto, portanto, pode ser editado no aplicativo em um editor de texto, como o Notepad. Entretanto, você pode obter resultados de produtividade significativos ao usar ferramentas de criação que oferecem recursos para dar suporte especificamente à edição de arquivos JavaScript, assim como Microsoft Visual Studio e Microsoft Visual Studio Express. É possível obter o Visual Studio Community 2013 gratuitamente.

Usar as ferramentas do desenvolvedor do navegador

Todos os navegadores modernos oferecem ferramentas internas para habilitar scripts de depuração. Essas ferramentas também podem ser muito úteis ao escrever scripts para formulários do Dynamics 365. Essas ferramentas do desenvolvedor costumam ser chamadas de ferramentas F12 pois esta é a chave usada para abri-las. Consulte Depuração de Javascript W3Schools para obter informações sobre como usar essas ferramentas.

Use as ferramentas do desenvolvedor para verificar a sintaxe dos scripts a serem carregados como recursos da Web do script. Com essas ferramentas, você também pode compreender melhor o modelo de objeto para programação. Por exemplo, quando você escreve um código para acessar objetos específicos em um formulário, em geral precisa acessá-los pelo nome. Em vez de procurar o nome do objeto no editor de formulários, use o console das ferramentas do desenvolvedor para interrogar o modelo de objeto Xrm.Page para obter os nomes dos atributos ou controles acessados. Por exemplo, para acessar um controle de subgrade específico pelo nome, você pode usar o console de ferramentas do desenvolvedor do navegador para escrever o seguinte código.

Xrm.Page.ui.controls.get(
function(ctrl,i){
 if(ctrl.getControlType() == "subgrid")
  console.log(ctrl.getName()
  );
});

Os nomes de todos os controles de subgrade serão escritos no painel de saída do console. Este script aproveita o recurso para passar uma função de representante anônimo para o método get localizado em coleções, bem como outros métodos encontrados em objetos para filtrar por tipo e retornar o nome de objeto, como Xrm.Page.ui control.getControlType e Xrm.Page.ui control.getName usado neste exemplo.

Importante

Os formulários do Dynamics 365 são compostos de vários quadros. Para que o código funcione no console, você deve selecionar o quadro certo. Para obter os formulários do cliente Web do Dynamics 365, selecione o quadro denominado ClientApiWrapper.aspx. Para obter os novos formulários do cliente do hub de serviço interativo, selecione o quadro denominado engagementhub.aspx.

Veja mais alguns exemplos.

• Mostrar os nomes de todos os atributos em um formulário com seus tipos

  Xrm.Page.getAttribute(
  function (att, i) {
   console.log(att.getName() + " : " + att.getAttributeType())
  });
  

• Mostrar os valores de opção válidos para atributos optionset

  Xrm.Page.getAttribute(
  function (att, i) {
   if (att.getAttributeType() == "optionset") {
    console.log(att.getName())
    var options = att.getOptions();
    var optionsLength = options.length;
    for (var i = 0; i < optionsLength; i++) {
     var option = options[i];
     console.log("   value: " + option.value + " Label: " + option.text)
    }
   }
  });
  

Confira Também

Estender o Microsoft Dynamics 365 no cliente
Abrir formulários, exibições, caixas de diálogo e relatórios com uma URL
Referência rápida do script de formulário
Usar o Javascript com o Microsoft Dynamics 365
Bibliotecas JavaScript para Microsoft Dynamics 365
Personalizar o aplicativo Microsoft Dynamics 365
Usar eventos de formulário e de campo
Use o modelo de objeto Xrm.Page
Escrever e depurar scripts para o Dynamics 365 para telefones e tablets
Scripts de gravação para atributos compostos
Criar scripts para fluxos de processos de negócios
Escrever scripts para subgrades
Usar o contexto de execução e o pipeline de evento de formulário
Usar controles IFRAME e de recursos da Web em um formulário
Introdução à API Web do Microsoft Dynamics 365 (Javascript no cliente)

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais