Objetos de contexto

Concluído

Ao criar manipuladores de eventos e usar a API de script de cliente, você deve entender os objetos de contexto disponíveis e como usá-los. A finalidade dos objetos de contexto é fornecer informações sobre o contexto em que seu código está sendo executado. Esse contexto garante que você não precise embutir em código as informações em sua lógica. O contexto permite criar funções mais genéricas e torna suas funções menos sensíveis ao layout específico dos componentes da interface de usuário com os quais você está trabalhando.

Contexto de execução

Ao registrar um manipulador de eventos, você pode ter o contexto de execução passado como primeiro parâmetro. Quando você registra o manipulador de eventos usando propriedades do formulário, essa é uma opção que pode ser habilitada. A imagem mostra o registro de um manipulador OnLoad e a habilitação do contexto de execução.

Normalmente, é uma boa ideia sempre ter essa opção selecionada ao registrar um manipulador de eventos usando as propriedades do formulário. Ao registrar um manipulador de eventos usando código, esta opção é selecionada automaticamente.

Sua definição de função que usa o contexto de execução como o primeiro parâmetro seria semelhante a:

O uso mais comum do contexto de execução é recuperar os contextos de formulário e de grade. Outro método útil neste contexto é getEventSource. A origem do evento retorna uma referência ao objeto que disparou o evento. Esse objeto permite que você escreva manipuladores genéricos que interrogam a origem do evento em tempo de execução para descobrir qual controle disparou o evento ocorrido. Esse objeto pode ser útil quando você deseja escrever um único método que pode ser registrado nos eventos em vários controles, em vez de criar um manipulador de eventos separado para cada controle. Por exemplo, no caso de um evento OnChange para vários campos, você poderá usar getEventSource para identificar qual campo disparou o evento e usá-lo adequadamente.

Contexto do formulário

O contexto do formulário da API do Cliente (formContext) faz referência ao formulário ou a um item do formulário, como um controle de visualização rápida ou uma linha em uma grade editável, na qual o código atual é executado. Você pode recuperar o objeto formContext do contexto de execução usando a função getFormContext.

Anteriormente, o item ou formulário era acessado usando o objeto global Xrm.Page. No entanto, na versão mais recente, o objeto Xrm.Page foi preterido. No lugar dele, você deve usar o método getFormContext do objeto de contexto de execução para obter uma referência ao formulário ou item apropriado no formulário. Então, em vez de escrever código como a seguir.

var firstName = Xrm.Page.getAttribute("firstname").getValue();

Em vez disso, você escreveria o código abaixo usando formContext.

var formContext = executionContext.getFormContext();

var firstName = formContext.getAttribute("firstname").getValue();

Você pode saber mais sobre a substituição de Xrm.Page.

O diagrama a seguir é uma visão geral de alto nível das propriedades e dos métodos disponíveis no contexto do formulário:

Objeto de dados

O objeto de dados (formContext.data) deve ser usado em qualquer tabela para manipulação de dados no formulário.

Esta tabela é um resumo de cada um dos objetos e coleções do objeto de dados:

Nome	Descrição
Atributos	Coleção de dados sem entidade no formulário. Os itens nessa coleção são do mesmo tipo de dados que o conjunto de atributos na entidade, mas é importante observar que eles não são atributos da tabela do formulário.
Entidade	Métodos para recuperar informações específicas da linha exibida na página, o método de salvamento e uma coleção de todos os atributos incluídos no formulário. Os dados de atributo são limitados a atributos representados por campos no formulário em comparação com todos os campos disponíveis na configuração da entidade. Para obter mais informações, consulte formContext.data.entity.
Processo	Objetos e métodos para interagir com os dados de fluxo do processo empresarial em um formulário. Para obter mais informações, consulte formContext.data.process.

Objeto de interface do usuário

O objeto de interface do usuário (formContext.ui) fornece métodos para recuperar informações sobre a interface do usuário, além de coleções para vários subcomponentes do formulário ou da grade.

Esta tabela resume cada um dos objetos e coleções do objeto de interface do usuário:

Nome	Descrição
Controles	Coleção de todos os controles na página. Consulte Coleções para obter informações sobre as coleções, os controles e os objetos de controle na coleção.
FormSelector	Métodos para obter informações sobre formulários. Use o método formSelector.getCurrentItem para recuperar informações sobre o formulário em uso no momento. Use a coleção formSelector.items para retornar informações sobre todos os formulários disponíveis para o usuário.
Navegação	Coleção de todos os itens de navegação na página. Consulte item formContext.ui.navigation para obter informações sobre os itens da coleção. A navegação não está disponível para o Microsoft Dynamics 365 para tablets. Para automatizar a navegação geral do aplicativo, tendemos a usar o namespace Xrm.Navigation.
Processo	Objetos e métodos para interagir com o controle de fluxo do processo empresarial em um formulário, como definir sua visibilidade. Para obter mais informações, consulte formContext.ui.process.
QuickForms	Coleção de todos os controles de visualização rápida em um formulário. Para obter mais informações, consulte formContext.ui.quickForms.
Guias	Coleção de todas as guias da página. Consulte formContex.ui.tabs para obter informações sobre os itens na coleção.

É comum usar o objeto de dados em vez do objeto de interface do usuário para obter ou definir um valor de coluna da tabela. O objeto de dados tem apenas um único atributo que representa o valor da coluna da tabela. Já o objeto de interface do usuário tem vários controles para a mesma coluna de tabela no formulário, cada um com uma referência ao atributo. Portanto, é mais fácil trabalhar com o objeto de dados para manipular o valor do atributo e o objeto de interface do usuário para trabalhar com os controles que representam esse atributo no formulário.

O uso de objetos de contexto em seus scripts os torna mais resistente a alterações no formulário e na API do cliente.