Objetos de contexto
Cuando cree controladores de eventos y use la API de scripting del cliente, debe comprender los objetos de contexto disponibles y cómo usarlos. La finalidad de los objetos de contexto es brindarle información sobre el contexto en el que se ejecuta su código. Este contesto garantiza que no tenga que codificar la información en su lógica. El contexto le permite crear funciones más genéricas y hace que sus funciones sean menos sensibles al diseño específico de los componentes de la IU con los que está trabajando.
Contexto de ejecución
Cuando se registra un controlador de eventos, se puede pasar el contexto de ejecución como primer parámetro. Cuando se registra el controlador de eventos con las propiedades del formulario, esta es una opción que se puede habilitar. En la imagen se muestra el registro de un controlador OnLoad y la habilitación del contexto de ejecución.
Por lo general, es una buena idea tener siempre seleccionada esta opción cuando se registra un controlador de eventos usando propiedades de formulario. Cuando se registra un controlador de eventos usando código, esta opción se selecciona automáticamente.
La definición de su función que toma el contexto de ejecución como primer parámetro tendría el siguiente aspecto:
El uso más habitual del contexto de ejecución es recuperar los contextos de formulario y cuadrícula. Otro método útil en este contexto es getEventSource. El origen del evento devuelve una referencia al objeto que ha desencadenado el evento. Este objeto le permite escribir controladores genéricos que interrogan al origen del evento en tiempo de ejecución para averiguar qué control ha desencadenado el evento. Este objeto puede resultar útil si desea escribir un único método que pueda registrarse en eventos de múltiples controles, en lugar de crear un controlador de eventos independiente para cada control. Por ejemplo, si tiene un evento OnChange para varios campos, puede usar getEventSource para identificar qué campo desencadenó el evento y usarlo en consecuencia.
Contexto del formulario
El contexto del formulario de la API de cliente (formContext) proporciona una referencia al formulario o a un elemento de este, como un control de vista rápida o una fila en una cuadrícula editable, con la que se ejecuta el código actual. Puede recuperar el objeto formContext del contexto de ejecución mediante la función getFormContext.
Antes, se podía acceder al elemento o formulario mediante el objeto global Xrm.Page. Sin embargo, en la última versión, el objeto Xrm.Page está en desuso. En su lugar, debe usar el método getFormContext del objeto de contexto de ejecución para obtener una referencia al formulario o elemento apropiado del formulario. Por tanto, en lugar de escribir código como el siguiente:
var firstName = Xrm.Page.getAttribute("firstname").getValue();
En cambio, debería escribir el siguiente código mediante formContext.
var formContext = executionContext.getFormContext();
var firstName = formContext.getAttribute("firstname").getValue();
Puede obtener más información sobre el desuso de Xrm.Page.
El siguiente diagrama ilustra de forma general las propiedades y los métodos que están disponibles en el contexto de formulario:
Objeto de datos
El propósito del objeto de datos (formContext.data) es que las tablas lo usen a fin de administrar los datos en el formulario.
Esta tabla es un resumen de todos los objetos y las colecciones en el objeto de datos:
| Nombre | Descripción |
|---|---|
| Atributos | Recopilación de datos que no son de entidad en el formulario. Los elementos de esta colección son del mismo tipo de datos que la colección de atributos en una entidad, pero es importante tener en cuenta que no son atributos de la tabla de formulario. |
| Entidad | Métodos para recuperar información específica de la fila que se muestra en la página, el método de guardar y una colección de todos los atributos que se incluyen en el formulario. Los datos de atributos se limitan a los atributos que están representados por campos en el formulario frente a todos los campos que están disponibles en la configuración de la entidad. Para obtener más información, consulte formContext.data.entity. |
| Procesar | Objetos y métodos para interactuar con los datos de flujo de proceso de negocio en un formulario. Para obtener más información, consulte formContext.data.process. |
Objeto de IU
El objeto de IU (formContext.ui) proporciona ambos métodos para recuperar información sobre la interfaz de usuario, además de colecciones para varios subcomponentes del formulario o la cuadrícula.
En esta tabla, se resumen todos los objetos y las colecciones del objeto de IU:
| Nombre | Descripción |
|---|---|
| Controles | Colección de todos los controles de la página. Consulte Colecciones para obtener información sobre las colecciones, los controles y los objetos de control de la colección. |
| FormSelector | Métodos para obtener información sobre formularios. Use el método formSelector.getCurrentItem para recuperar información sobre el formulario que está actualmente en uso. Use la colección formSelector.items para devolver información sobre todos los formularios que están disponibles para el usuario. |
| Navegación | Colección de todos los elementos de navegación en la página. Consulte el elemento formContext.ui.navigation para obtener información sobre los elementos de la colección. La navegación no está disponible para Microsoft Dynamics 365 para tabletas. Para automatizar la navegación general de la aplicación, tendemos a usar el espacio de nombres Xrm.Navigation. |
| Procesar | Objetos y métodos para interactuar con el control de flujo de proceso de negocio en un formulario, por ejemplo, para establecer su visibilidad. Para obtener más información, consulte formContext.ui.process. |
| QuickForms | Colección de todos los controles de vista rápida en un formulario. Para obtener más información, consulte formContext.ui.quickForms. |
| Pestañas | Colección de todas las pestañas en la página. Consulte formContex.ui.tabs para obtener información sobre los elementos de la colección. |
Es habitual usar el objeto de datos en lugar del objeto de IU para obtener o establecer un valor de columna de tabla. El objeto de datos tiene un objeto de un solo atributo que representa el valor de la columna de la tabla. Por otro lado, el objeto de IU tiene varios controles para la misma columna de la tabla en el formulario, todos con una referencia al atributo. Por lo tanto, es más sencillo trabajar con el objeto de datos para manipular el valor del atributo, así como que el objeto de la IU trabaje con los controles que representan a ese atributo en el formulario.
El uso de los objetos de contexto en sus scripts los hace más resistentes a los cambios en el formulario y en la API del cliente.