Tutorial: Escribir el primer script de cliente

Listo para escribir su primer script de cliente para ver las cosas en acción. Empecemos; lo haremos sencillo.

Objetivo

Después de finalizar este tutorial, sabrá cómo utilizar el código JavaScript en aplicaciones basadas en modelos, lo que implica los pasos siguientes a un nivel alto:

• Escriba el código JavaScript para solucionar un problema del negocio
• Cargue el código JavaScript como un recurso web en aplicaciones basadas en modelos
• Asocie las funciones de JavaScript en el recurso web a los distintos eventos del lado del cliente en aplicaciones basadas en modelos.

Llamaremos su atención sobre hechos importantes durante el tutorial y proporcionaremos referencias a métodos reales según corresponda.

Paso 1: Escribir el código JavaScript personalizado

El primer paso es identificar el problema del negocio que intenta abordar usando el scripting del cliente. Una vez que lo haya identificado, debe escribir el código JavaScript que contiene la lógica de negocios personalizada que trata su problema del negocio.

Las aplicaciones basadas en modelo no proporcionan un editor de JavaScript. Por lo tanto, puede usar una herramienta de creación externa que proporciona características específicamente para la edición de archivos JavaScript, como Notepad++, Visual Studio Code o Microsoft Visual Studio.

Puede revisar el código de muestra completo que se usa en el tutorial más adelante en este artículo.

Veamos el código detalladamente:

Explicación detallada del código

• Defina el espacio de nombres: el código comienza definiendo un espacio de nombres de su script personalizado. Como práctica recomendada, siempre debe crear bibliotecas JavaScript del espacio de nombres para evitar que sus funciones sean reemplazadas por funciones de otra biblioteca.

  var Sdk = window.Sdk || {};
  

  En este caso, todas las funciones definidas en esta biblioteca se pueden usar como Sdk.[functionName].

• Definir variables globales: la siguiente sección define algunas variables globales que se usan en el script. Ahora no es necesario pasar por el contexto del formulario para obtener el nombre de usuario. La información de contexto está ahora disponible de forma global mediante el método Xrm.Utility.getGlobalContext.

  // Define some global variables
  var myUniqueId = "_myUniqueId"; // Define an ID for the notification
  var currentUserName = Xrm.Utility.getGlobalContext().userSettings.userName; // get current user name
  var message = currentUserName + ": Your JavaScript code in action!";
  

• Código que se ejecuta en el evento OnLoad: esta sección contiene el código que se ejecutará cuando se cargue el formulario de cuenta. Por ejemplo, cuando se crea un nuevo registro de cuenta o al abrir un registro de cuenta existente.

  El código utiliza el objeto executionContext para obtener el objeto formContext. Cuando conectemos más adelante nuestro código al evento de formulario, no olvidaremos seleccionar la opción de pasar el contexto de ejecución a esta función. A continuación, mostramos una notificación de nivel de formulario mediante el método setFormNotification. A continuación, usamos el método setTimeOut para retardar la ejecución del método clearFormNotification para eliminar la notificación después de 5 segundos.

  // Code to run in the form OnLoad event
  this.formOnLoad = function (executionContext) {
      var formContext = executionContext.getFormContext();
  
      // display the form level notification as an INFO
      formContext.ui.setFormNotification(message, "INFO", myUniqueId);
  
      // Wait for 5 seconds before clearing the notification
      window.setTimeout(function () { formContext.ui.clearFormNotification(myUniqueId); }, 5000);        
  }
  

• Código para ejecutar en el evento OnChange: el código de esta sección se asociará con la columna Nombre de la cuenta columna en el formulario de la cuenta para que se ejecute solo cuando cambia el valor del nombre de la cuenta.

  El código realiza una búsqueda que no distingue entre mayúsculas y minúsculas de "Contoso" en el nombre de la cuenta y, si está presente, establece automáticamente valores para algunas columnas del formulario de cuenta.

  // Code to run in the column OnChange event 
  this.attributeOnChange = function (executionContext) {
      var formContext = executionContext.getFormContext();
  
      // Automatically set some column values if the account name contains "Contoso"
      var accountName = formContext.getAttribute("name").getValue();
      if (accountName.toLowerCase().search("contoso") != -1) {
          formContext.getAttribute("websiteurl").setValue("https://www.contoso.com");
          formContext.getAttribute("telephone1").setValue("425-555-0100");
          formContext.getAttribute("description").setValue("Website URL, Phone and Description set using custom script.");
      }
  }
  

• Código que se ejecuta en el evento OnSave: el código de esta sección muestra un cuadro de diálogo de alerta mediante el método openAlertDialog. Este cuadro de diálogo muestra un mensaje con el botón Aceptar; el usuario puede cerrar la alerta seleccionando Aceptar.

  No estamos pasando el contexto de ejecución en esta función ya que no es necesario para ejecutar Xrm.Utility. .

  // Code to run in the form OnSave event 
  this.formOnSave = function () {
      // Display an alert dialog
      Xrm.Navigation.openAlertDialog({ text: "Record saved." });
  }
  

Paso 2: Agregar el código JavaScript en un recurso web del Script

Paso 3: Asociar recurso web del Script a un formulario

Pruebe el código JavaScript

Se recomienda que actualice su navegador para que los cambios surtan efecto en su instancia de aplicaciones basadas en modelo. Para probar la lógica empresarial personalizada que configuró en este tutorial:

1. Inicie sesión en la instancia de aplicaciones basadas en modelos.

2. Vaya a Cuentas e intente abrir o crear una cuenta nueva. En este caso, se abrirá una cuenta existente para cargar el formulario de cuenta. Verá una notificación con su nombre de usuario que desaparecerá automáticamente en 5 segundos.

   

3. Edite el nombre de la cuenta para agregar "Contoso" en el nombre y pasar a la siguiente columna presionando TAB. Esto activará el evento OnChange y actualizará automáticamente las columnas Teléfono, Sitio web y Descripción con el valor especificado en el código.

   

4. Finalmente, al seleccionar Guardar se activará el evento OnSave y se mostrará el cuadro de diálogo de alerta con un mensaje que configuró en su código. Seleccione Aceptar para cerrar la alerta.

   

Código de muestra completo utilizado en el recorrido

// A namespace defined for the sample code
// As a best practice, you should always define 
// a unique namespace for your libraries
var Sdk = window.Sdk || {};
(function () {
    // Define some global variables
    var myUniqueId = "_myUniqueId"; // Define an ID for the notification
    var currentUserName = Xrm.Utility.getGlobalContext().userSettings.userName; // get current user name
    var message = currentUserName + ": Your JavaScript code in action!";

    // Code to run in the form OnLoad event
    this.formOnLoad = function (executionContext) {
        var formContext = executionContext.getFormContext();

        // display the form level notification as an INFO
        formContext.ui.setFormNotification(message, "INFO", myUniqueId);

        // Wait for 5 seconds before clearing the notification
        window.setTimeout(function () { formContext.ui.clearFormNotification(myUniqueId); }, 5000);
    }

    // Code to run in the column OnChange event 
    this.attributeOnChange = function (executionContext) {
        var formContext = executionContext.getFormContext();

        // Automatically set some column values if the account name contains "Contoso"
        var accountName = formContext.getAttribute("name").getValue();
        if (accountName.toLowerCase().search("contoso") != -1) {
            formContext.getAttribute("websiteurl").setValue("https://www.contoso.com");
            formContext.getAttribute("telephone1").setValue("425-555-0100");
            formContext.getAttribute("description").setValue("Website URL, Phone and Description set using custom script.");
        }
    }

    // Code to run in the form OnSave event 
    this.formOnSave = function () {
        // Display an alert dialog
        Xrm.Navigation.openAlertDialog({ text: "Record saved." });
    }
}).call(Sdk);