Compartir vía

Escritura del primer script de cliente

¿Listo para escribir su primer script de cliente para ver las cosas en acción? Comencemos. Mantengámoslo simple.

Objetivo

Después de completar este tutorial, sabe cómo usar código JavaScript en aplicaciones controladas por modelos. Este proceso implica los siguientes pasos generales:

  • Localizar o crear una solución para agregar su trabajo
  • Escribir el código JavaScript para solucionar un problema del negocio
  • Cargar su código como recurso web
  • Asociar su recurso web a un formulario
  • Configurar eventos de formulario y campo
  • Probar su código

Paso 1: Localizar o crear una solución

Use soluciones para transportar personalizaciones de un entorno a otro. Escriba y pruebe el código JavaScript en un entorno de desarrollo como parte de una solución no administrada. Cuando termine de probar, exporte la solución como solución administrada e impórtela o instálela en el entorno de producción.

Es posible que una solución existente ya esté disponible para su uso. La aplicación basada en modelos que desea personalizar con su script ya debería formar parte de una solución. Puede editar esa solución o crear una solución que dependa de otra solución existente.

Para crear una nueva solución

  1. Vaya a Power Apps.

  2. En el panel de navegación izquierdo, seleccione Soluciones y luego seleccione Nueva solución.

  3. En el cuadro de diálogo flotante, escriba un nombre para mostrar, un nombre y un publicador.

    La mayoría de las empresas tienen un publicador existente que siempre usan. Use ese publicador. Si es la primera persona, cree su propio publicador.

    Seleccione Nuevo publicador para abrir el cuadro de diálogo Nuevo publicador . En este tutorial, use un publicador con esta definición:

    Formulario para crear un nuevo editor con información para editor de ejemplo

    Observe el valor de Prefijo. Este valor debe identificar a su empresa. En este caso, use example.

    Esta solución es la que se usa en este tutorial.

    Formulario de solución para la solución de script de primer cliente

  4. Busque o agregue una aplicación basada en modelo a su solución.

    Una nueva solución no incluye ninguna aplicación controlada por modelos. Debe agregar una aplicación basada en modelos existente o crear una nueva.

    Nota

    Para este tutorial, asegúrese de que la aplicación incluya la tabla Cuenta. Los scripts e instrucciones siguientes esperan campos que se encuentran en un formulario para la tabla Cuenta.

    Opción A: Agregar una aplicación basada en modelo existente a su solución

    1. En su solución, seleccione Agregar existente>Aplicación>Aplicación basada en modelo.

    Agregar aplicación existente basada en modelo

    1. Seleccione una aplicación existente y seleccione Agregar.

    Opción B: Crear una nueva aplicación basada en modelo en su solución

    En la solución, seleccione Nueva>>aplicación controlada por modelos de aplicación.

    Consulte el tutorial Crear la primera aplicación basada en modelo. Cree una aplicación que incluya la tabla Cuenta.

Paso 2: Escribir su código JavaScript

El primer paso es identificar el problema empresarial que desea solucionar mediante scripting de cliente. Al identificar el problema, escriba el código de JavaScript que contiene la lógica de negocios personalizada que soluciona el problema empresarial.

Las aplicaciones controladas por modelos no proporcionan un editor de JavaScript. Use 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.

En este tutorial se usa el código JavaScript siguiente:

// A namespace defined for the sample code
// As a best practice, you should always define 
// a unique namespace for your libraries
var Example = window.Example || {};
(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(Example);

Copie este código en un archivo de texto y guárdelo como Example-form-script.js.

Explicación detallada del código

Veamos el código detalladamente:

  • Defina el espacio de nombres: el código comienza definiendo un espacio de nombres de su script personalizado. Como procedimiento recomendado, cree siempre bibliotecas javaScript con espacio de nombres para evitar que las funciones se invalidan en otra biblioteca.

    var Example = window.Example || {};

    En este caso, puede usar todas las funciones definidas en esta biblioteca como Example.[functionName]. Elija un espacio de nombres que coincida con el nombre del publicador de soluciones.

  • Definir variables globales: en la sección siguiente se definen algunas variables globales que se van a usar en el script. Puede acceder a la información de contexto globalmente 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!";

  • Función para ejecutarse en el evento OnLoad: esta sección contiene la función que se ejecuta cuando se carga el formulario de cuenta. Por ejemplo, cuando se crea un nuevo registro de cuenta o al abrir un registro de cuenta existente.

    La función Example.formOnLoad utiliza el parámetro executionContext para obtener el objeto formContext. Cuando adjunte el código mediante el evento de formulario más adelante, seleccione la opción para pasar el contexto de ejecución a esta función.

    Esta función muestra una notificación de nivel de formulario mediante el método formContext.ui.setFormNotification .

    Por último, esta función usa el JavaScript setTimeOut para retardar la ejecución del método formContext.ui.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);        
}

  • Función que se ejecuta en el evento OnChange: asocie la Example.attributeOnChange función a la columna Nombre de cuenta en el formulario de cuenta para que se ejecute solo cuando se cambia el valor del nombre de cuenta.

    Esta función realiza una búsqueda que no distingue entre mayúsculas y minúsculas de Contoso en el name de la cuenta y, si está presente, establece automáticamente valores para las columnas websiteurl, telephone1 y description 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.");
    }
}

  • Función que se ejecuta en el evento OnSave: la Example.formOnSave función muestra un cuadro de diálogo de alerta mediante el método Xrm.Navigation.openAlertDialog . Este cuadro de diálogo muestra un mensaje con un botón Aceptar: El usuario puede cerrar la alerta seleccionando Aceptar.

    Nota

    Esta función no usa el contexto de ejecución porque los métodos Xrm.Navigation no lo requieren.

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

Paso 3: Cargar su código como recurso web

Ahora que el código está listo, cárguelo en la solución.

  1. En la solución, seleccione Nuevo>recurso web.>

    Agregar un nuevo recurso web a su solución

  2. En el cuadro de diálogo Nuevo recurso web , seleccione Elegir archivo y seleccione el Example-form-script.js archivo que guardó anteriormente.

  3. Escriba el nombre para mostrar, el nombre y, opcionalmente, una descripción. Asegúrese de que el Tipo es JavaScript (JS).

    Nuevo cuadro de diálogo de recursos web para crear un script de formulario de ejemplo

    Nota

    • El nombre tiene un prefijo que coincide con el prefijo de personalización del publicador de soluciones. Hay otras maneras de crear recursos web, pero la creación de un recurso web de esta manera garantiza que el recurso web forme parte de la solución.
    • El nombre del recurso web es example_example-form-script.

Paso 4: Asociar su recurso web a un formulario

  1. En su solución, seleccione Objectos>Aplicaciones>Su aplicación y haga clic en Editar.

    Editar la aplicación en la solución

  2. Expanda Cuenta y seleccione el formulario Cuenta. Haga clic en los puntos suspensivos (...) a la derecha del formulario Información y seleccione Editar.

    Editar el formulario de información de la cuenta

  3. En la navegación izquierda, seleccione Bibliotecas de formulario y haga clic en Agregar biblioteca.

    Agregar biblioteca a formulario

  4. En el cuadro de diálogo Agregar biblioteca de JavaScript, busque el recurso web de JavaScript que creó por nombre: Example Script.

    Cuadro de diálogo Agregar biblioteca de JavaScript

  5. Selecciona el recurso web Script de ejemplo y haga clic en Agregar.

Paso 5: Configurar eventos de formulario y campo

  1. Seleccione la pestaña Eventos.

    Controladores de eventos de formulario

Configurar el evento On Load de formulario

  1. Seleccione el controlador de eventos On Load y haga clic en + Controlador de eventos.

    Configurar el controlador On Load de formulario

    Asegúrese de que la siguiente configuración es correcta:

    • El Tipo de evento es On Load.
    • La biblioteca example_example-form-script está seleccionada.
    1. Escriba el nombre de la función en el campo Función. En este caso, escriba Example.formOnLoad.
    2. Seleccione Pasar el contexto de ejecución como primer parámetro.
    3. Haga clic en Listo.

Configurar el evento Al guardar del formulario

  1. Seleccione el controlador de eventos Al guardar y, a continuación, seleccione + Controlador de eventos.

    Configurar el controlador On Save de formulario

    Asegúrese de que la siguiente configuración es correcta:

    • El Tipo de evento es On Save.
    • La biblioteca example_example-form-script está seleccionada.
    1. Escriba el nombre de la función en el campo Función. En este caso, escriba Example.formOnSave.

      Nota

      No es necesario seleccionar Pasar contexto de ejecución como primer parámetro para esta función porque no lo usa.

    2. Seleccione Listo.

Configurar el campo On Change (evento)

  1. Seleccione el campo Nombre de cuenta y la pestaña Eventos.

    Seleccionar eventos de campo Nombre de cuenta

  2. Seleccione el controlador de eventos On Change y haga clic en + Controlador de eventos.

    Configurar controlador OnChange de campo

    Asegúrese de que la siguiente configuración es correcta:

    • El Tipo de evento es On Change.
    • La biblioteca example_example-form-script está seleccionada.
    1. Escriba el nombre de la función en el campo Función. En este caso, Example.attributeOnChange.
    2. Seleccione Pasar el contexto de ejecución como primer parámetro.
    3. Seleccione Listo.

Guardar y publicar sus cambios

Guarde el formulario y haga clic en Publicar.

Paso 6: Probar su código

Actualice el explorador para asegurarse de que los cambios surtan efecto en la instancia de aplicaciones controladas por modelos.

Para probar su código:

  1. Vaya a Power Apps.

  2. En el panel de navegación izquierdo, seleccione Aplicaciones.

  3. Abra la aplicación controlada por modelos que acaba de editar o selecciónela y seleccione Reproducir.

    Abrir la aplicación para probar

Probar función On Load de formulario

  1. Seleccione cualquier registro de cuenta en la lista para abrirlo.

  2. Compruebe que aparezca la notificación.

    Notificación al cargar formulario

  3. Compruebe que la notificación desaparece en 5 segundos.

Probar función On Change de campo

  1. Edite el nombre de la cuenta para incluir "Contoso" en el nombre y pasar a la siguiente columna presionando TAB.

  2. Compruebe los valores esperados establecidos en las columnas Teléfono principal, Sitio web y Descripción

    Valores establecidos al cambiar el campo

Probar función On Save de formulario

  1. Haga clic en Guardar.

  2. Compruebe que el cuadro de diálogo de alerta muestra el mensaje que configuró en el código.

    Cuadro de diálogo de alerta cuando se guarda el formulario

  3. Seleccione Aceptar para cerrar la alerta.

Depuración del código JavaScript para aplicaciones basadas en modelo
Eventos en formularios y cuadrículas en aplicaciones basadas en modelos
Evento de formulario OnLoad
Evento OnSave de formulario (referencia de API de cliente) en aplicaciones basadas en modelos
Evento OnChange de la columna (referencia de la API de cliente)

  • Last updated on