Série SPFx : Extensions

La principale différence entre un WebPart SPFx et une extension est qu’un WebPart est un composant qui permet de visualiser ou de modifier le contenu d’une page, tandis qu’une extension personnalise ou étend l’interface utilisateur de SharePoint ou Microsoft Teams.

Un WebPart SPFx est un composant créé sur mesure qui peut être ajouté à une page SharePoint pour fournir des fonctionnalités supplémentaires. Par exemple, il peut être utilisé pour afficher un graphique, un calendrier ou une liste d’éléments. Les WebParts sont généralement utilisés pour modifier ou étendre le contenu de la page.

Une extension SPFx, en revanche, est un morceau de code créé sur mesure qui s’exécute dans le contexte de SharePoint ou Microsoft Teams et peut être utilisé pour personnaliser ou étendre l’interface utilisateur de SharePoint ou Teams. Par exemple, elle peut être utilisée pour ajouter une commande personnalisée aux barres de commandes, ajouter un en-tête ou un pied de page personnalisé, ou personnaliser les couleurs de l’interface utilisateur. Les extensions sont utilisées pour personnaliser l’interface utilisateur de SharePoint ou Teams et étendre les fonctionnalités.

Il existe trois types d’extensions SPFx :

• Personnalisateurs d’application (Application Customizers) : Ce sont de petits morceaux de code qui s’exécutent lorsqu’une page est chargée dans SharePoint ou Teams. Ils offrent la possibilité d’ajouter un en-tête ou un pied de page, par exemple, ou de personnaliser les couleurs de l’interface utilisateur.
• Personnalisateurs de champs (Field Customizers) : Ce sont des champs personnalisés qui peuvent être ajoutés aux listes et bibliothèques SharePoint. Ils fournissent des fonctionnalités supplémentaires pour la visualisation et la modification des éléments de liste et des documents.
• Ensembles de commandes (Command Sets) : Ce sont des commandes qui peuvent être ajoutées aux barres de commandes dans les listes et bibliothèques SharePoint. Ils offrent la possibilité d’ajouter des actions personnalisées, telles que l’ajout d’un bouton pour convertir un document dans un autre format.

Type de déploiement

La mise en œuvre d’une extension implique un XML, un clientSideInstance.xml ou un elements.xml. Vous pouvez trouver ce XML dans le dossier SharePoint/assets de votre solution dans Visual Studio Code. Ces fichiers xml sont inclus dans la fonctionnalité de votre solution (voir les fonctionnalités dans le fichier package-solution.json).

La différence entre les 2 fichiers xml réside dans le fait que le clientSideInstance.xml est utilisé pour déployer votre extension à l’échelle du tenant. Cela se fait lorsque votre application est déployée dans le catalogue d’applications. Si un fichier clientSideInstance.xml est trouvé lors du déploiement de votre application, votre extension sera implémentée dans la liste cachée Tenant Wide Extensions. Cela signifie que chaque fois que votre extension est chargée quelque part dans SharePoint, la configuration de cette extension est lue depuis cette liste Tenant Wide Extensions.

Si nous examinons les différentes propriétés dans un tel xml d’un clientSideInstance, nous pouvons distinguer les suivantes :

• Title : C’est le titre de votre action personnalisée.
• Location : Cela détermine l’emplacement où le composant côté client est affiché. Ici, il spécifie que le composant est un ListViewCommandSet qui s’affiche dans la barre de commandes d’une liste SharePoint.
• ListTemplateId : Cette valeur spécifie à quel template de liste le composant côté client doit être appliqué. L’ID de template de liste 100 fait référence à une liste personnalisée.
• Location : Cela indique où l’action sera affichée. Dans ce cas, cela indique que l’action est une ClientSideExtension et qu’il s’agit d’un ListViewCommandSet qui doit apparaître dans la barre de commandes d’une liste SharePoint.
• properties : Ce paramètre contient un objet JSON avec ses propres propriétés qui sont transmises au composant SPFx lorsqu’il est exécuté. Dans ce cas, deux propriétés, sampleTextOne et sampleTextTwo, sont transmises avec les valeurs « One item is selected in the list. » et « This command is always visible, respectively ».
• ComponentId : C’est l’ID unique du composant côté client associé à cette action personnalisée. Ce GUID fait référence au composant SPFx (par exemple, un WebPart ou une extension) qui est chargé lorsque l’action est effectuée.

<?xml version="1.0" encoding="utf-8"?>
    <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
        <ClientSideComponentInstance
            Title="ListItemDetailsDialog"
            Location="ClientSideExtension.ListViewCommandSet.CommandBar"
            ListTemplateId="100"
            Properties="{&quot;sampleTextOne&quot;:&quot;One item is selected in the list.&quot;, &quot;sampleTextTwo&quot;:&quot;This command is always visible.&quot;}"
            ComponentId="acddd824-662e-47a5-a80e-6586b25c810a"
        />
    </Elements>

Lorsqu’un elements.xml est trouvé, ce xml sera utilisé lors de l’implémentation au niveau de la collection de sites. Avec cette implémentation, votre extension ne sera configurée qu’au niveau de la collection de sites. Si nous examinons le xml du fichier elements.xml, nous pouvons distinguer les propriétés suivantes :

• Title : C’est le titre de votre action personnalisée.
• RegistrationId : Cela spécifie quelles listes ou types de contenu sont affectés par cette personnalisation. La valeur « 100 » correspond à l’ID de la définition de liste. La définition de liste 100 fait référence à une liste personnalisée standard.
• RegistrationType : Ce paramètre spécifie le type d’objet SharePoint sur lequel l’action est enregistrée. La valeur « List » signifie que l’action s’applique à une liste.
• Location : Cela indique où l’action sera affichée. Dans ce cas, cela indique que l’action est une ClientSideExtension et qu’il s’agit d’un ListViewCommandSet qui doit apparaître dans la barre de commandes d’une liste SharePoint.
• ClientSideComponentId : C’est l’ID unique du composant côté client associé à cette action personnalisée. Ce GUID fait référence au composant SPFx (par exemple, un WebPart ou une extension) qui est chargé lorsque l’action est effectuée.
• ClientSideComponentProperties : Ce paramètre contient un objet JSON avec ses propres propriétés qui sont transmises au composant SPFx lorsqu’il est exécuté. Dans ce cas, deux propriétés, sampleTextOne et sampleTextTwo, sont transmises avec les valeurs « One item is selected in the list. » et « This command is always visible, respectively ».

<?xml version="1.0" encoding="utf-8"?>
    <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
        <CustomAction
            Title="ListItemDetailsDialog"
            RegistrationId="100"
            RegistrationType="List"
            Location="ClientSideExtension.ListViewCommandSet.CommandBar"
            ClientSideComponentId="acddd824-662e-47a5-a80e-6586b25c810a"
            ClientSideComponentProperties="{&quot;sampleTextOne&quot;:&quot;One item is selected in the list.&quot;, &quot;sampleTextTwo&quot;:&quot;This command is always visible.&quot;}">
        />
    </Elements>

Ces 2 fichiers sont intégrés dans votre application, mais quand est-il décidé quel xml utiliser ? Cela se produit lorsque votre application est déployée dans le catalogue d’applications. Lorsque nous allons procéder au déploiement, nous voyons apparaître l’écran suivant :

Si vous cochez « Rendre cette solution disponible pour tous les sites de l’organisation », le fichier clientSideInstance.xml sera utilisé et l’extension sera implémentée dans la liste Tenant Wide Extensions. Si vous ne cochez pas cette option, le fichier elements.xml sera utilisé lorsque vous ajouterez spécifiquement une application à une collection de sites.