Personnaliser les enregistrements sous-jacents grille dans les prévisions

En tant que développeur, utilisez cette documentation de référence pour en savoir plus sur les événements et l’objet de contexte afin de personnaliser les enregistrements sous-jacents grille dans vos prévisions. Vous pouvez utiliser l’objet de contexte pour effectuer des personnalisations telles que rendre l’intégralité du grille ou des champs spécifiques en lecture seule, désactiver des champs, afficher des notifications d’erreur, etc.

Exigences de licence et de rôle

Événements pour la grille d’enregistrements sous-jacente

Les événements suivants sont pris en charge dans les prévisions :

• OnRowLoad
• OnSave
• OnChange

Les exemples de scénarios suivants sont créés en fonction des gestionnaires d’événements pris en charge :

• Rendre une grille ne lecture seule uniquement en désactivant tous les champs.
• Toujours n’activer que certains champs selon l’entité.
• Désactiver la modification des champs selon la logique et l’entité.
• Afficher une notification des erreurs selon la valeur.
• Bloquer l’enregistrement automatique selon la valeur estimée avec preventDefault, et ouvrir un événement de fenêtre.

Événement OnRowLoad

L’événement OnRowLoad est déclenché pour chaque enregistrement sous-jacent chargé dans la grille. L’objet de contexte qui est passé au gestionnaire d’événements OnRowLoad contient des API spécifiques à l’enregistrement sous-jacent.

Voici les exemples de scénarios que vous pouvez exécuter à l’aide du gestionnaire OnRowLoad :

• Rendre une grille ne lecture seule uniquement en désactivant tous les champs.
• Toujours n’activer que certains champs selon l’entité.
• Désactiver la modification des champs selon la logique et l’entité.

Événement OnChange

L’événement est déclenché lorsque la valeur d’une cellule dans les enregistrements sous-jacents grille est mise à jour et que la cellule n’est pas focalisée. OnChange

Voici un exemple de scénario que vous pouvez exécuter à l’aide du gestionnaire OnChange :

• Afficher une notification des erreurs selon la valeur.

Événement OnSave

L’événement est déclenché lorsqu’une valeur est modifiée dans une cellule des enregistrements sous-jacents grille et que la cellule n’est pas focalisée. OnSave Cependant, si le gestionnaire OnChange existe pour la même configuration de prévision, le gestionnaire OnSave est appelé après le gestionnaire OnChange.

Le gestionnaire OnSave est appelé avant l’enregistrement réel du champ.

Voici un exemple de scénario que vous pouvez exécuter à l’aide du gestionnaire OnSave :

• Bloquer l’enregistrement automatique selon la valeur estimée avec preventDefault, et ouvrir un événement de fenêtre.

Objet de contexte pour les gestionnaires d’événements dans les enregistrements sous-jacents grille

L’objet de contexte contient un ensemble d’API permettant d’effectuer des opérations spécifiques à un enregistrement sous-jacent dans une prévision. Cet objet de contexte est transmis en tant que paramètre aux gestionnaires d’événements dans la vue des enregistrements sous-jacents grille.

Les API suivantes sont prises en charge :

• méthode context.getFormContext
• context.getWebApiContext()
• context.getEventArgs().preventDefault()

méthode context.getFormContext

Renvoie une référence à un enregistrement sur les enregistrements sous-jacents grille.

context.getFormContext().data.entity

Cela renvoie un objet entité et a les méthodes suivantes :

context.getFormContext().data.entity.attributes.getByName(« Nom d’attribut »)

Cela renvoie un objet attribut et a les méthodes suivantes :

context.getFormContext().data.entity.attributes.getByName(« Nom d’attribut »).controls.get(0)

Cela renvoie un objet contrôle mappant vers l’attriubt et a les méthodes suivantes :

Exemple 1 :

Créons du code JavaScript pour rendre tous les champs des enregistrements sous-jacents grille en LECTURE SEULE. Aussi, nous appellerons la fonction OnRowLoad pour chaque ligne lorsque la grille est chargée et enregistrée avec succès.

function OnRowLoad(executionContext) {
    // Iterating through all attributes and disabling it.
    executionContext.getFormContext().data.entity.attributes.forEach(
        attribute => {
            attribute.controls.get(0).setDisabled(true);
        }
    )
}

Exemple 2 :

Créons un code JavaScript pour désactiver tous les champs à l’exception de quelques-uns pour l’entité Opportunité uniquement. Aussi, nous appellerons la fonction OnRowLoad pour chaque ligne lorsque la grille est chargée et enregistrée avec succès.

function OnRowLoad(executionContext) {

    // Get the logical name of the loaded entity as part of underlying records grid.
    var entityName = executionContext.getFormContext().data.entity.getEntityName();

    if (entityName === "opportunity") {

        // Defining the attributes list from opportunity that has to be enabled if loaded as part of view.
        var OPTY_ENABLE_ATTRS_LIST = ["name", "msdyn_forecastcategory", "actualvalue", "actualclosedate", "estimatedvalue", "estimatedclosedate"];

        executionContext.getFormContext().data.entity.attributes.forEach(
            attribute => {
                // Disabling all attributes other than OPTY_ENABLE_ATTRS_LIST
                if (!OPTY_ENABLE_ATTRS_LIST.includes(attribute.getName())) {
                    attribute.controls.get(0).setDisabled(true);
                }
            }
        )        
    }
}

Exemple 3 :

Créons du code JavaScript pour gérer différentes entités pour la configuration de prévision chargée.

Pour une entité d’opportunité, le script désactivera les éléments suivants :

• Colonne Nom
• actualRevenue et actualCloseData si la valeur forecastCategory est Meilleur cas, Engagé, Omis ou Pipeline.
• estimatedRevenue et estimatedCloseDate si la valeur forecastCategory est Gagné ou Perdu.

De même, le script désactivera la colonne de nom pour l’entité Compte et désactivera toutes les colonnes pour les autres entités.

Aussi, nous appellerons la fonction OnRowLoad pour chaque ligne lorsque la grille est chargée et enregistrée avec succès.

function OnRowLoad(executionContext) {
		 
    // Get the logical name of the loaded entity as part of underlying records grid.
    var entityName = executionContext.getFormContext().data.entity.getEntityName();
    
    // If loaded logical name of entity in underlying records grid is opportunity.
    if (entityName === "opportunity") {
        
       var allAttrs = executionContext.getFormContext().data.entity.attributes;

       // Disable column name for all records if exists in the view.
       var nameAttr = allAttrs.getByName("name");
       if (nameAttr) {
           nameAttr.controls.get(0).setDisabled(true);
       }

       var fcatAttr = allAttrs.getByName("msdyn_forecastcategory");
       if (fcatAttr) {
           // Disable actualRevenue, actualCloseDate for forecastcategory Bestcase, committed, omitted, or pipeline.
           if (fcatAttr.getValue() <= 100000004 && fcatAttr.getValue() >= 100000001) {
                   var actualRevenueAttr = allAttrs.getByName("actualvalue");
                   var actualCloseDateAttr = allAttrs.getByName("actualclosedate");
                   if (actualRevenueAttr) actualRevenueAttr.controls.get(0).setDisabled(true);
                   if (actualCloseDateAttr) actualCloseDateAttr.controls.get(0).setDisabled(true);
           }
           // Disable estimatedRevenue, estimatedCloseDate for forecastCategory won or lost.
           else if (fcatAttr.getValue() == 100000005 || fcatAttr.getValue() == 100000006) {
                   var estimatedRevenueAttr = allAttrs.getByName("estimatedvalue");
                   var estimatedCloseDateAttr = allAttrs.getByName("estimatedclosedate");
                   if (estimatedRevenueAttr) estimatedRevenueAttr.controls.get(0).setDisabled(true);
                   if (estimatedCloseDateAttr) estimatedCloseDateAttr.controls.get(0).setDisabled(true);
           }
       }
   } 
   
   // Else disable name column, if loaded logical name of entity is Account.
   else if (entityName === "account"){
       var attrNameObj = executionContext.getFormContext().data.entity.attributes.getByName("name");
       if (attrNameObj) {
               attrNameObj.controls.get(0).setDisabled(true);
       }
   } 
   
   // For all other entities
   else {
       executionContext.getFormContext().data.entity.attributes.forEach(
           attribute => {
               attribute.controls.get(0).setDisabled(true);
           }
       )
   }
}

Exemple 4 :

Créons un fichier JavaScript de validation qui bloquera l’enregistrement et affichera une notification d’erreur dans la colonne des revenus estimés lorsque la valeur est inférieure à 10. De plus, nous supprimerons la notification d’erreur et autoriserons l’enregistrement lorsque la valeur de la colonne des revenus estimés est corrigée pour être supérieure ou égale à 10. Ici, la fonction OnChange est invoquée lorsque la valeur d’un champ est mise à jour sur les enregistrements sous-jacents grille d’une prévision.

// OnChange function is invoked when any field's value is updated on the underlying records grid of the forecast
function OnChange(executionContext) {

    let entity = executionContext.getFormContext().data.entity;

    // Verify the logical name of the entity and load as part of the underlying records grid.
    if (entity.getEntityName() === "opportunity") {

        // Verify estimated revenue value
        let estValAttr = entity.attributes.get("estimatedvalue");

        // Verify if this attribute exists within the grid view and changed
        if(estValAttr && estValAttr.getIsDirty()) 
        {
            if(estValAttr.getValue() < 10){

                // This will show an error icon next to the estimated revenue field. On hovering over the icon, the below provided message is displayed.
                // Any save attempts are blocked by the system until all notifications are cleared from the columns.
                estValAttr.controls.get(0).setNotification("Estimated revenue cannot be less than 10");
            }
            else{
                // Clearing notifications to save.
                estValAttr.controls.get(0).clearNotification();
            }
        }
    }
}

context.getWebApiContext()

Cela renvoie un objet webApiContext et a les méthodes suivantes :

context.getEventArgs().preventDefault()

La méthode preventDefault() n’est disponible que dans l’événement OnSave. L’appel de cette méthode dans OnSave empêche l’événement de sauvegarde de continuer.

Exemple :

Créons un exemple de JavaScript pour ouvrir la grille des opportunités, bloquons l’événement d’enregistrement automatique et ouvrons une fenêtre d’alerte si la valeur estimée des revenus est inférieure à 10. De plus, nous autoriserons l’événement d’enregistrement automatique si la valeur estimée des revenus est supérieure ou égale à 10.

// OnSave function will be invoked whenever grid attempts to save changes made to any field. 
function OnSave(executionContext){

    let entity = executionContext.getFormContext().data.entity;

    // Verify the logical name of the entity and load as part of the underlying records grid.
    if (entity.getEntityName() === "opportunity") {

        // Verify estimated revenue value
        var estValAttr = entity.attributes.get("estimatedvalue");

        if(estValAttr && estValAttr.getIsDirty() && estValAttr.getValue() < 10){

            // This call will prevent the save event from proceeding
            executionContext.getEventArgs().preventDefault(); 
            alert("Estimated revenue cannot be less than 10");

        }
    }
}

Informations associées

Personnaliser les enregistrements sous-jacents grille