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. Este contexto le permite crear funciones más genéricas y hace que sus funciones sean menos sensibles a la estructura de diseño específica 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 en el que se produjo el evento. Este objeto le permite escribir controladores genéricos que interrogan al origen del evento en tiempo de ejecución para averiguar en qué control se produjo el evento. Este objeto puede resultar útil cuando escribe un método que tiene previsto registrar en eventos para varios controles en lugar de registrar un controlador de eventos independiente para cada control.
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 del contexto del formulario, el elemento o formulario estaba disponible mediante el objeto global Xrm.Page. Con la última versión, el objeto Xrm.Page está en desuso, y debe usar el método getFormContext del objeto de contexto de ejecución pasado para devolver una referencia al formulario apropiado o a un elemento 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 objeto de datos (formContext.data) está destinado a utilizarse para cualquier tabla y procesar la manipulación de datos dentro del formulario.
Esta tabla es un resumen de cada uno de los objetos y colecciones que contiene 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 | Proporciona 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. |
| Proceso | Proporciona objetos y métodos para interactuar con los datos de flujo del 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 métodos para recuperar información sobre la interfaz de usuario y también colecciones para varios subcomponentes del formulario o cuadrícula.
En esta tabla se resume cada uno de los objetos y colecciones que contiene el objeto de IU.
| Nombre | Descripción |
|---|---|
| Controles | Colección de todos los controles de la página. Vea Colecciones para obtener información sobre las colecciones, los controles y los objetos de control de la colección. |
| FormSelector | 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. |
| Proceso | Proporciona objetos y métodos para interactuar con el control de flujo del proceso de negocio en un formulario, como 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 de la página. Vea 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 si necesita 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. Con el objeto de IU, puede tener varios controles para la misma columna de la tabla en un formulario, cada uno con una referencia al atributo. Por lo tanto, es más sencillo trabajar con el objeto de datos para manipular el atributo, y con el valor y el objeto de la IU si desea trabajar con los controles que representan 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.