Escriba código para formularios de Microsoft Dynamics 365

 

Publicado: enero de 2017

Se aplica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

La programación de formularios proporciona métodos para interactuar con los formularios de entidad usando JavaScript, que se ejecuta para los eventos que se producen en el formulario.

En este tema

Cuándo se debe usar la programación de formularios

Factores a tener en cuenta al utilizar la programación de formularios

Administrar dependencias de biblioteca

Escriba scripts de formularios que funcionen correctamente

Distintas presentaciones de los formularios

Herramientas de desarrollo

Cuándo se debe usar la programación de formularios

Microsoft Dynamics 365 ofrece diversas opciones para controlar los procesos de negocio. La programación de formularios es una opción. Pero recuerde que tiene otra opción: reglas de negocio. Las reglas de negocio permiten a alguien que no conozca JavaScript y no sea programador aplicar la lógica de los procesos de negocio en un formulario. Consulte el tema del manual de personalización: TechNet: Creación y edición de reglas de negocio para obtener más información.

La ventaja principal de la programación de formularios y de las reglas de negocio es que son inmediatas. No requieren el envío de datos al servidor y, por tanto, proporcionan el mejor rendimiento para muchos escenarios. Puesto que permiten la interacción humana, también son las opciones más flexibles.

Si bien las reglas de negocio tienen la ventaja de que puede crearlas y mantenerlas alguien que no sea programador, tienen ciertas limitaciones y no están destinadas a sustituir los scripts de formularios. La programación de formularios le permite realizar tareas que todavía no se pueden realizar mediante reglas de negocio.

Las tareas que se suelen realizar mediante la programación de formularios incluyen las siguientes:

• Validación de datos: Siempre que sea posible, debe realizar la validación de datos mientras estos se están editando. La definición del campo de formulario realizará las validaciones de datos más comunes automáticamente. Por ejemplo, un campo Single Line of Text con el formato de una dirección de correo electrónico no permitirá introducir a un valor no válido.

  Use la programación de formularios para realizar la validación de datos adicional específica de su organización. Por ejemplo, su organización puede tener reglas específicas acerca del formato que deben tener los números de teléfono o una longitud mínima para el campo Subject de una actividad de servicio.

• Automatización: Puede conseguir mejoras significativas de productividad si usa el scripting de formularios para automatizar tareas comunes. Puede establecer valores de campos que dependen de los datos especificados en un formulario, lo que ayudará a los usuarios a ahorrar un tiempo considerable al especificar los datos. La programación de formularios resulta muy útil para la automatización porque permite al usuario comprobar que un proceso estándar es válido en un caso específico. Los usuarios pueden realizar los ajustes necesarios antes de guardar un registro.

• Mejora y cumplimiento de procesos: Puede personalizar los datos que se mostrarán e el formulario o el diseño del formulario para optimizarlo para tareas específicas realizadas por personas de su organización. Puede usar la programación de formularios para mostrar u ocultar elementos específicos de los formularios o abrir los distintos formularios definidos para una entidad. Puede controlar los campos que son necesarios en función de los datos presentes en el formulario o en los registros relacionados.

  Con Microsoft Dynamics CRM 2015 y actualización de Microsoft Dynamics CRM Online 2015 puede escribir código para controlar los flujos de procesos de negocio que aparecen en la parte superior de los formularios.Más información:Escribir scripts para flujos de procesos de negocio.

Factores a tener en cuenta al utilizar la programación de formularios

La lógica aplicada en la programación de formularios solo se puede ejecutar en el explorador de alguien que interactúe desde el formulario de entidad de la aplicación de Microsoft Dynamics 365. Por este motivo, no debe confiar solo en la programación de formularios para iniciar ni para obligar a realizar procesos relacionados con los datos. Los registros se pueden crear o actualizar directamente mediante las API del servicio web o con flujos de trabajo externos al contexto del formulario. La programación de formularios debería complementar la lógica empresarial aplicada mediante complementos y procesos de modo que todos los registros creados o actualizados de cualquier modo cumplan con los mismos procesos.

Las reglas de negocio se pueden definir para ejecutarse en el ámbito de la entidad para aplicar la misma lógica en el servidor sin importar dónde se originó la acción.Más información:TechNet: Crear y editar reglas de negocio

Aunque la programación de formularios proporciona la capacidad de ocultar campos de formulario para que los usuarios no puedan visualizar o actualizar algunos datos de entidad, no representa una solución completa para imponer requisitos de seguridad. El usuario puede ver los datos de la entidad que no están visibles en el formulario mediante diversos métodos, como la Búsqueda avanzada.Más información:El modelo de seguridad de Microsoft Dynamics 365

Administrar dependencias de biblioteca

Como optimización del rendimiento, los formularios de Microsoft Dynamics 365 cargan los recursos web JavaScript asincrónicamente y en paralelo. Esto significa que el orden en que las bibliotecas se configuran para un formulario no garantiza que una biblioteca se descargue y inicialice completamente antes de que otra biblioteca pueda intentar usar uno de los objetos definidos en ella.

Si tiene código que depende de que otra biblioteca se descargue y inicialice completamente, el enfoque más directo es combinar las dos bibliotecas en un solo recurso web JavaScript con el código debajo del código de la biblioteca. Un enfoque más avanzado es usar bibliotecas como head.js o require.js para controlar el modo en que las bibliotecas separadas se cargan.

Escriba scripts de formularios que funcionen correctamente

Cuando escriba scripts para formularios, use las directrices siguientes para obtener el máximo rendimiento:

• Evite incluir bibliotecas de recursos web de JavaScript que no necesite
  Cuantos más scripts agregue al formulario, más tiempo tardará en descargarlos. Por lo general, los scripts se almacenan en caché en el explorador después de cargarse la primera vez, pero el rendimiento la primera vez que se ve un formulario suele crear una impresión considerable.

  Como ejemplo específico, no incluya jQuery en sus scripts de formularios simplemente porque desea usar XMLHttpRequests. Aunque jQuery tiene la función $.ajax con la que un gran número de personas están familiarizadas para realizar estas solicitudes, es una preferencia del programador, no una necesidad. Es posible realizar estas solicitudes mediante el objeto XMLHttpRequest nativo de los exploradores admitidos por Microsoft Dynamics 365.Más información:Uso de jQuery

• Evite cargar todos los scripts en el evento Onload
  Si tiene código que únicamente admite los eventos OnChange para campos o el evento OnSave, asegúrese de definir la biblioteca de scripts con el controlador de eventos para dichos eventos en lugar del evento OnLoad. De esta manera, la carga de estas bibliotecas se puede aplazar y aumentar el rendimiento cuando el formulario se carga.

  No se recomienda el uso del método addOnChange en el controlador de eventos OnLoad simplemente por comodidad. Mientras esto puede reducir el número de pasos necesarios para agregar los controladores de eventos, hace que el formulario se cargue más lentamente.

• Use las fichas contraídas para aplazar la carga de recursos web
  Cuando se incluyen recursos web o IFRAMES en las secciones de una pestaña contraída, estos no se cargarán si la pestaña está contraída. Se cargarán cuando se expanda la ficha. Cuando cambia el estado de la pestaña, se produce el evento TabStateChange. Cualquier código necesario para admitir recursos web o IFRAMES en pestañas contraídas puede usar controladores de eventos para el evento TabStateChange y reducir el código que, de otro modo, debería encontrarse en el evento OnLoad.

• Defina las opciones predeterminadas de visibilidad
  Evite usar scripts de formularios en el evento OnLoad que oculten elementos de formulario. En su lugar, defina las opciones predeterminadas de visibilidad de los elementos de formulario que podrían ocultarse para que no sean visibles de forma predeterminada cuando se cargue el formulario. A continuación, use los scripts en el evento OnLoad para mostrar los elementos de formulario que desee mostrar.

Distintas presentaciones de los formularios

Existen varias formas de mostrar los formularios. Estas afectan al tipo de código o a los eventos disponibles que se pueden usar para cada una.

Representación de formularios heredados

En Actualización 1 de Microsoft Dynamics CRM Online 2015 y Dynamics 365 (local) se introdujo una nueva configuración del sistema: Usar representación de formularios heredados. Con estas versiones la visualización del formulario se ha mejorado y la estructura interna de la página ha cambiado. Como resultado, los scripts de formulario que usaban métodos no compatibles no podrán obtener acceso a los elementos del DOM que estaban disponibles en versiones anteriores. Si tiene nuevos errores después de actualizar a estas versiones aplique este valor para ver si desaparecen los errores. Si es así, es muy probable que los scripts que causen estos errores usen métodos no compatibles.

Puede establecer Usar representación de formularios heredados para conceder tiempo para resolver estos problemas, aunque no experimentará las mejoras de rendimiento nueva que proporciona la nueva infraestructura de representación de formularios.

Nota

El ajuste Usar representación de formularios heredados desaparecerá en la siguiente versión principal. En ese momento, todos los scripts de formularios deben funcionar con la nueva representación de formularios.

Entidades actualizadas

Todas las entidades predeterminadas y determinadas entidades del sistema tienen una interfaz de usuario actualizada que incluye el uso de la barra de comandos y nuevas API de formulario. Las entidades del sistema actualizadas aparecen en la tabla siguiente:

Cuenta	Cita	Campaña
Actividad de la campaña	Respuesta de campaña	Caso
Competidor	Contacto	Contrato
Línea de contrato (ContractDetail)	Dirección de correo electrónico	Derecho
Plantilla de derecho	Fax	Factura
Producto de la factura (InvoiceDetail)*	Cliente potencial	Carta
Lista de marketing	Oportunidad	Producto de oportunidad
Orden	Producto del pedido (SalesOrderDetail)*	Llamada de teléfono
Puesto	Elemento de lista de precios	Producto
Asociación de producto	Relación de productos (ProductSubstitute)	Cola
Campaña exprés (operación masiva)	Oferta	Producto de oferta (QuoteDetail)*
Cita periódica (RecurringAppointmentMaster)	Documentación de ventas	SLA
Instancia de KPI de SLA	Actividad social	Perfil social
Tarea	Equipo	Usuario

* Estas entidades se actualizaron en Actualización 1 de CRM Online 2016 y Service Pack 1 de Dynamics 365 (local).

Nota

Algunas entidades actualizadas incluyen atributos compuestos. Estas requieren algunas consideraciones especiales.Más información:Escribir scripts para atributos compuestos.

Los formularios de entidad actualizados también pueden incluir un control de colaboración que proporciona acceso a las notas, actividades y las publicaciones si están habilitadas para la entidad. El objeto Xrm.Page no proporciona acceso al control de colaboración. Puede acceder al elemento de la sección que contiene el control de colaboración si desea mostrarlo o ocultarlo mediante scripts.

Métodos de programación de formularios y evento PreSearch para entidades actualizadas

La siguiente tabla muestra los métodos de programación de formularios disponibles únicamente para las entidades actualizadas.

Método	Descripción
Xrm.Page.context.client.getClient	Devuelve un valor que indica el cliente en que se ejecuta el script.
Xrm.Page.context.client.getClientState	Devuelve un valor para indicar el estado del cliente.
Xrm.Page.context.getUserName	Devuelve el nombre del usuario actual.
Xrm.Page.data.entity.getPrimaryAttributeValue	Obtiene una cadena para el valor del atributo principal de la entidad.
Xrm.Page.data.refresh	Actualiza asincrónicamente los datos del formulario sin volver a cargar la página.
Xrm.Page.data.Guardar	Guarda el registro asincrónicamente con la opción de configurar las funciones de devolución de llamada para que se ejecuten una vez finalizada la operación de guardar.
Xrm.Page.data.entity attribute.getIsPartyList	Determina si un atributo de búsqueda representa una búsqueda de tipo partylist.
Xrm.Page.ui control.clearNotification	Elimina un mensaje ya que se muestra para un control.
Xrm.Page.ui control.setNotification	Muestra un mensaje cerca del control para indicar que los datos no son válidos.
Xrm.Page.ui.clearFormNotification	Use este método para quitar notificaciones en el nivel del formulario.
Xrm.Page.ui.setFormNotification	Use este método para mostrar notificaciones en el nivel del formulario.
Xrm.Page.ui control.addCustomFilter	Use fetchXml para agregar filtros adicionales a los resultados mostrados en la búsqueda. Cada filtro se combinará con cualquier filtro agregado anteriormente como una condición ‘Y’.
Xrm.Page.ui control.setShowTime	Especifica si un control de fecha debe mostrar la parte de hora de la fecha.
Xrm.Utility.alertDialog	Muestra un cuadro de diálogo de alerta sin bloqueo con una función de devolución de llamada.
Xrm.Utility.confirmDialog	Muestra un cuadro de diálogo de confirmación sin bloqueo con distintas devoluciones de llamada en función del botón en el que ha hecho clic el usuario.

Evento PreSearch

El nuevo Evento PreSearch se produce justo antes de que se abra el cuadro de diálogo de búsqueda cuando se establece un valor de búsqueda. Este evento no tiene interfaz de usuario para establecer un controlador de eventos en la aplicación; solo puede establecerse usando el método Xrm.Page.ui control.addPreSearch. Use este evento con los métodos addCustomFilter, addCustomView y setDefaultView para controlar las vistas que se abren cuando los usuarios buscan un registro para establecerlo como el valor de un campo de búsqueda.

Entidades que utilizan formularios clásicos

Las entidades del sistema que no se han actualizado utilizan la presentación clásica de formularios. Los formularios de esas entidades continúan usando la cinta si lo hacían en CRM 2011 y no tienen acceso a las API de formulario agregadas en esta versión. Estas entidades aparecen en la tabla siguiente:

Dirección	Artículo	Comentario de artículo	Operación de eliminación en masa	Unidad de negocio
Conexión	Descuento	Lista de descuentos	Ubicación de documentos	Datos adjuntos de correo electrónico
Seguimiento	Objetivo	Métrica del objetivo	Importar archivo de origen	Producto de la factura
Producto del pedido	Lista de precios	Elemento de cola	Producto de oferta	Campo Informe
Consulta de informe	Vista guardada	Servicio	Actividad de servicio	Sitio de SharePoint
Ubicación	Zona de ventas	Unidad	Unidad de venta

Entidades habilitadas de Dynamics 365 para tabletas

Solo determinadas entidades del sistema y entidades personalizadas están disponibles para mostrarlas mediante Microsoft Dynamics 365 para tabletas. Las siguientes entidades del sistema pueden tener formularios editables en Dynamics 365 para tabletas.

Cuenta	Actividad	Cita	Caso
Competidor	Conexión	Contacto	Cliente potencial
Nota	Oportunidad	Producto de oportunidad	Llamada de teléfono
Elemento de cola	Actividad social	Perfil social	Tarea

Debido a que Dynamics 365 para tabletas no se comporta de la misma forma que los formularios de la aplicación web, algunas API no están disponibles. Por ejemplo, en Dynamics 365 para tabletas las pestañas no se pueden expandir o contraer, por lo que no aparece el Evento TabStateChange de pestañas y el método Xrm.Page.ui tab.setDisplayState no se puede usar para expandir o contraer pestañas.Más información:Escribir y depurar scripts para Dynamics 365 para teléfonos y tabletas.

Herramientas de desarrollo

Su experiencia escribiendo JavaScript para formularios de Dynamics 365 será mejor cuando use buenas herramientas.

Uso de buenas herramientas de creación

Dado que JavaScript es un lenguaje interpretado, no se necesitan herramientas de desarrollo especiales.JavaScript es sólo texto por lo que se puede modificar en la aplicación o en un editor de textos como el Bloc de notas. Sin embargo, se pueden lograr mejoras significativas de productividad cuando se usan herramientas de creación que proporcionan características específicamente para la edición de archivos JavaScript, como Microsoft Visual Studio y Microsoft Visual Studio Express. Puede obtener Visual Studio Community 2013 gratis.

Uso de herramientas del desarrollador del explorador

Todos los exploradores modernos proporcionan herramientas integradas que permiten depurar scripts. Estas herramientas también pueden ser enorme ayuda para escribir scripts de formularios de Dynamics 365. Estas herramientas del desarrollador se denominan con frecuencia herramientas F12 porque esa es la tecla usada para abrirlos. Vea Depuración de W3Schools JavaScript para obtener información sobre cómo usar estas herramientas.

Use las herramientas del desarrollador para comprobar la sintaxis de scripts que cargará como recursos web de script. Con estas herramientas también puede comprender mejor el modelo de objetos para el que está programando. Por ejemplo, si está escribiendo código para acceder a objetos específicos en un formulario, normalmente necesita acceder a ellos por nombre. En lugar de consultar el nombre del objeto en el editor de formularios, use la consola de las herramientas del desarrollador para interrogar al modelo de objetos Xrm.Page y obtener los nombres de los atributos o controles a los que obtiene acceso. Por ejemplo, si desea obtener acceso a un determinado control de subcuadrícula por nombre, puede usar la consola de herramientas del desarrollador del explorador para escribir el siguiente código.

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

Los nombres de todos los controles de subcuadrícula se escribirán en el panel de resultados de la consola. Este script aprovecha la capacidad para pasar una función de delegado anónima al método get que se encuentra en colecciones así como otros métodos que se encuentran en objetos para filtrar por tipo y devolver el nombre de objeto, como Xrm.Page.ui control.getControlType y Xrm.Page.ui control.getName usado en este ejemplo.

Importante

Los formulariosDynamics 365 están compuestos por varios marcos. Para que el código funcione en la consola debe seleccionar el cuadro adecuado. Para los formularios de cliente web de Dynamics 365, seleccione el cuadro llamado ClientApiWrapper.aspx. Para los nuevos formularios de cliente centro de servicio interactivo, seleccione el cuadro denominado engagementhub.aspx.

A continuación, encontrará algunos ejemplos más.

• Mostrar los nombres de todos los atributos en un formulario con su tipo

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

• Mostrar los valores de opción válidos para los atributos de 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)
    }
   }
  });
  

Ver también

Amplíe Microsoft Dynamics 365 en el cliente
Abrir formularios, vistas, diálogos e informes con una dirección URL
Referencia de scripting de formularios
Uso de JavaScript con Microsoft Dynamics 365
Bibliotecas de JavaScript para Microsoft Dynamics 365
Personalizar aplicaciones de Microsoft Dynamics 365
Usar formularios y eventos de campo
Use el modelo de objeto Xrm.Page
Escribir y depurar scripts para Dynamics 365 para teléfonos y tabletas
Escribir scripts para atributos compuestos
Escribir scripts para flujos de procesos de negocio
Escribir scripts para subcuadrículas
Usar el contexto de ejecución y la canalización de eventos de formulario
Usar IFRAME y controles de recursos web en un formulario
Introducción a la API web de Microsoft Dynamics 365 (JavaScript del lado cliente)

Microsoft Dynamics 365

© 2017 Microsoft. Todos los derechos reservados. Copyright