Anatomie d’une extension d’état
Avec l’objet d’extension d’état, vous pouvez étendre des objets d’état existants de la même manière que vous étendez des tables et des pages.
Objet d’extension d’état
Avec l’objet d’extension d’état, vous pouvez étendre des objets d’état existants de la même manière que vous étendez des tables et des pages. Avec les extensions d’état, vous pouvez étendre un état existant en :
ajoutant des colonnes aux éléments de données existants dans le jeu de données de l’état ;
ajoutant de nouveaux éléments de données ;
ajoutant des implémentations de déclencheur ;
effectuant des ajouts à des pages de requête ;
ajoutant d’autres présentations d’état, soit pour refléter les nouveaux champs ajoutés avec une extension, soit simplement pour ajouter de nouvelles présentations d’état sur un jeu de données d’état existant.
Afin de pouvoir étendre un état, la propriété Extensible doit être définie sur true. Il s’agit de la valeur par défaut. Autrement dit, les états par défaut peuvent être étendus, à moins que leur propriété Extensible soit explicitement définie sur false.
Présentation d’extension d’état
Les extensions d’état peuvent avoir une ou plusieurs présentations définies. Pour en savoir plus, consultez Définition de plusieurs présentations d’état. La présentation d’un état existant ne peut pas être étendue, mais de nouvelles présentations peuvent être ajoutées. Pour utiliser un état existant comme point de départ, vous pouvez télécharger la présentation depuis Business Central et l’intégrer au projet d’extension.
Les présentations incluses dans une extension d’état s’affichent dans Business Central en tant que présentations supplémentaires pour l’état. La présentation d’une extension d’état n’est pas utilisée automatiquement lors du déploiement de l’extension. Pour utiliser l’une des nouvelles présentations d’état, accédez à la page Présentations d’état dans Business Central, puis choisissez la présentation de l’état en question comme nouvelle Présentation par défaut.
Prise en charge des extraits
La saisie du raccourci treportext entraîne la création de la présentation de base d’un objet d’extension d’état lorsque vous utilisez l’extension AL Language dans Visual Studio Code.
reportextension Id MyExtension extends MyTargetReport
{
dataset
{
// Add changes to dataitems and columns here
}
requestpage
{
// Add changes to the requestpage here
}
}
Depuis le client Business Central, vous pouvez exporter les résultats de l’état sous forme de données brutes vers un fichier Microsoft Excel. Le fichier comporte toutes les colonnes du jeu de données, mais sans la présentation appliquée. À l’aide du fichier, vérifiez que l’état renvoie les données attendues et que les contrôles de présentation d’état correspondent aux types de valeur du jeu de données. Pour exporter un jeu de données d’état vers Excel, exécutez l’état et cliquez sur Envoyer à > Document Microsoft Excel (données uniquement) sur la page de requête. Pour en savoir plus, consultez Exécuter et imprimer des états dans Business Central.
Limites
Dans l’élément de jeu de données, la syntaxe de modification des données n’est pas prise en charge. Autrement dit, vous ne pouvez ni ajouter de nouveaux déclencheurs aux éléments de données existants, ni modifier les éléments de données existants ou les propriétés de colonne existantes. Dans l’élément requestpage, vous ne pouvez modifier aucune propriété.
L’utilisation du déclencheur OnInitReport n’est pas prise en charge pour les extensions d’état. Les déclencheurs OnPreReport et OnPostReport sont exécutés après les déclencheurs équivalents de l’état d’origine.
Choisir des présentations d’extensions d’état
Lorsqu’une extension est déployée dans un environnement client sous forme d’application Microsoft AppSource ou d’extension par abonné (PTE), toutes les présentations d’état dans l’extension deviennent également disponibles dans l’environnement. Cependant, si vous souhaitez appliquer une présentation d’extension d’état à un état spécifique, vous devez ajouter le code d’installation et de mise à niveau dans l’extension.
Les utilisateurs peuvent choisir une présentation d’extension d’état sur la page Sélection présentation état, qui répertorie toutes les présentations disponibles pour un état donné. La page Sélection présentation état comprend les présentations des extensions d’état afin que l’utilisateur puisse faire son choix parmi toutes les présentations disponibles.
Ajouter des colonnes à des éléments de données existants
Envisagez un scénario dans lequel vous devez ajouter des colonnes à un élément de données existant. L’image suivante représente un exemple d’ajout de colonnes à un élément de données existant :
Une nouvelle commande add est associée à une ancre d’élément de données. Dans la commande, vous pouvez spécifier les éléments de données auxquels vous souhaitez effectuer des ajouts. Vous pouvez effectuer des ajouts non seulement à l’état de base, mais aussi aux éléments de données dans des extensions d’état pour cet état de base. Autrement dit, vous pouvez créer une dépendance à d’autres extensions d’état. Ensuite, vous pouvez ajouter des colonnes à l’élément de données et pour les champs dans la source de l’élément de données, notamment toute extension dont vous pouvez disposer pour cette source.
Par conséquent, si vous disposez d’une table et que vous souhaitez créer un état doté d’une extension d’état reposant sur une colonne ne figurant pas dans la source de données de l’état de base, vous pouvez ajouter cet état à la table de l’état de base au moyen d’une extension de table, puis utiliser cet état dans l’extension d’état.
Vous pouvez également ajouter des colonnes pour des variables dans l’extension d’état et accéder aux variables de l’état de base, si elles s’affichent comme protégées. Ceci dit, la plupart des variables des états de base ne sont pas marquées comme protégées, mais comme privées.
Pour accéder aux variables marquées comme privées dans les états de base, vous devez déposer une demande d’Application AL sur GitHub. Pour en savoir plus, consultez Extension AL Language dans Visual Studio Code pour Dynamics 365 Business Central.
Vous pouvez ajouter des colonnes pour les expressions et les procédures. Les colonnes peuvent être locales et figurer dans le graphique de l’état ; mais encore une fois, elles doivent s’afficher comme protégées.
Les colonnes ont les mêmes propriétés que dans l’état standard, sauf que la version de la 1re vague de lancement 2021 ne prend pas en charge les propriétés Caption, CaptionML et IncludeCaption. Ces propriétés pourraient être prises en charge ultérieurement.
Modifier des éléments de données existants
La modification d’éléments de données existants en général n’est pas prise en charge au moyen d’extensions d’état. À l’heure actuelle, aucun plan n’est en place pour prendre en charge la modification des propriétés des colonnes. Vous pouvez également ajouter une nouvelle colonne, masquer les colonnes d’origine de la présentation, puis transformer la valeur. Aucun plan n’est en place pour prendre en charge la modification des libellés de base et remplacer les déclencheurs existants. Les déclencheurs pourraient être davantage pris en charge dans les versions ultérieures.
Ajouter de nouveaux éléments de données à des éléments de données existants
Parfois, vous pouvez préférer ajouter un ou plusieurs nouveaux éléments de données sans effectuer le moindre ajout à un élément de données existant. Cette action est possible avec Business Central.
L’exemple de code suivant illustre une nouvelle section permettant d’ajouter des éléments de données :
Pour ajouter l’élément de données imbriqué dans la cible, utilisez les valeurs suivantes :
addfirst()
addlast()
Pour ajouter l’élément de données à côté de la cible, utilisez les valeurs suivantes :
addbefore()
addafter()
Cet exemple comprend une valeur addfirst(). Vous pouvez ajouter des éléments de données à l’état de base existant ou à une extension d’état dans le graphique. Les membres sont similaires aux éléments de données d’état standard. Les mêmes propriétés sont disponibles, notamment la possibilité de configurer le lien entre l’élément de données et l’élément de données parent. Les mêmes déclencheurs sont fournis et vous pouvez insérer un élément de données ou un graphique complet d’éléments de données imbriqués à la fois.
Cet exemple illustre l’intégration de deux éléments de données à l’ancre. Les colonnes sont prises en charge de la même manière que dans les éléments de données standard. Business Central ne prend pas en charge l’ajout de nouveaux éléments de données racine. Si vous tentez d’intégrer de nouveaux éléments de données racine à l’un des éléments de données existants, vous obtenez une erreur de compilation, comme indiqué dans la capture d’écran suivante :
Étendre la page de requête
L’extension de la page de requête est prise en charge. La capture d’écran suivante illustre un exemple de page de requête :
Aucune propriété n’est disponible sur la page de requête dans une extension d’état. La section de présentation est similaire à une page standard, car la page de requête est essentiellement une page. Autrement dit, l’extension de page de requête est similaire à une extension de page.
Les sections de présentation sont similaires aux extensions de page :
- addafter()
- addbefore()
- addfirst()
- addlast()
- modify()
- moveafter()
- movebefore()
- movefirst()
- movelast()
Par conséquent, vous pouvez déplacer des champs et en ajouter à la page de requête d’une extension d’état. Ensuite, les champs que vous pouvez ajouter à la page de requête sont similaires à une page de requête d’état standard.
Vous pouvez ajouter les éléments suivants dans une extension d’état ou des membres protégés dans le graphique de dépendance :
Colonnes
Variables
Expressions
Procédures
Les déclencheurs sur la page de requête sont similaires à une page de requête d’état. Autrement dit, des déclencheurs sont disponibles dans le nœud de la page de requête. Des déclencheurs sont également disponibles pour les nouveaux champs et les champs modifiés. Les séquences d’appel fonctionnent de la même manière que les pages standard.
Les déclencheurs appelés par la suite seront appelés après ceux appelés dans l’objet de base, et les autres remplacent ou écrasent essentiellement le reste.
Voici certains déclencheurs disponibles dans le nœud requestpage :
- OnAfterGetCurrRecord
- OnAfterGetRecord
- OnClosePage
- OnDeleteRecord
- OnInsertRecord
- OnModifyRecord
- OnNewRecord
- OnOpenPage
- OnQueryClosePage
Voici certains déclencheurs disponibles pour les nouveaux champs requestpage :
- OnAfterLookup
- OnAssistEdit
- OnControlAddIn
- OnDrillDown
- OnLookup
- OnValidate
Voici certains déclencheurs disponibles pour les champs modifiés de la page de requête :
- OnAfterLookup
- OnAfterValidate
- OnAssistEdit
- OnBeforeValidate
- OnDrillDown
- OnLookup
Ajouter des présentations
Le processus d’ajout d’une présentation dans le cadre d’une extension d’état fonctionne de la même manière que pour un état standard. Vous pouvez ajouter plusieurs présentations dans un objet d’extension d’état. L’ajout d’une présentation à une extension d’état n’est pas obligatoire. Sachez que l’extensibilité de la présentation n’est pas prise en charge. Vous pouvez uniquement remplacer une présentation d’état.
Lorsque vous créez une extension d’état dans Visual Studio Code, vous pouvez souvent utiliser la présentation d’état de base comme point de départ. Pour adopter cette approche, vous devez accéder au client, télécharger la présentation d’état, puis l’ajouter dans votre extension d’état.
Les couches faisant partie de l’extension d’état sont déployées avec l’application parente et s’affichent sous forme de présentations intégrées. Ces nouvelles présentations ne sont pas affectées automatiquement à l’état. Vous devez les sélectionner et les définir manuellement sur la page Présentations état ou vous pouvez écrire un code d’installation pour automatiser cette tâche.
D’autres extensions d’état peuvent étendre le même état et remplacer votre code d’installation. Il est uniquement possible de sélectionner les types de présentation pris en charge par l’état de base.
Que se passe-t-il en cas de désinstallation ?
Lorsque vous désinstallez une extension d’état, la présentation est masquée dans l’interface utilisateur. Plus précisément, lorsque vous désinstallez l’extension d’état, elle n’est plus sélectionnable à cet emplacement précédent. Cependant, les présentations personnalisées restent disponibles. Si vous disposez d’une présentation personnalisée utilisant certaines des colonnes d’une extension d’état et que vous désinstallez l’extension d’état, vous obtenez une erreur d’exécution lors de l’exécution de l’état. Ensuite, vous devez la corriger manuellement dans la présentation.