SPFx Series: Extensies

Het belangrijkste verschil tussen een SPFx-webonderdeel en een extensie is dat een webonderdeel een component is waarmee de inhoud van een pagina kan worden bekeken of bewerkt, terwijl een extensie de gebruikersinterface van SharePoint of Microsoft Teams aanpast of uitbreidt.

Een SPFx-webonderdeel is een op maat gebouwd component dat aan een SharePoint-pagina kan worden toegevoegd om extra functionaliteit te bieden. Het kan bijvoorbeeld worden gebruikt om een diagram, een kalender of een lijst met items weer te geven. Webonderdelen worden meestal gebruikt om de inhoud van de pagina te wijzigen of uit te breiden.

Een SPFx-extensie, daarentegen, is een op maat gebouwd stuk code dat draait in de context van SharePoint of Microsoft Teams en kan worden gebruikt om de SharePoint- of Teams-gebruikersinterface aan te passen of uit te breiden. Het kan bijvoorbeeld worden gebruikt om een aangepaste opdracht aan de opdrachtbalken toe te voegen, een aangepaste kop- of voettekst toe te voegen, of de kleuren van de gebruikersinterface aan te passen. Extensies worden gebruikt om de gebruikersinterface van SharePoint of Teams aan te passen en functionaliteit uit te breiden.

Er zijn drie soorten SPFx-extensies:

• Application Customizers: Dit zijn kleine stukjes code die worden uitgevoerd wanneer een pagina wordt geladen in SharePoint of Teams. Ze bieden de mogelijkheid om bijvoorbeeld een kop- of voettekst toe te voegen, of de kleuren van de gebruikersinterface aan te passen.
• Field Customizers: Dit zijn aangepaste velden die kunnen worden toegevoegd aan SharePoint-lijsten en -bibliotheken. Ze bieden extra functionaliteit voor het bekijken en bewerken van lijstitems en documenten.
• Command Sets: Dit zijn opdrachten die kunnen worden toegevoegd aan de opdrachtbalken in SharePoint-lijsten en -bibliotheken. Ze bieden de mogelijkheid om aangepaste acties toe te voegen, zoals het toevoegen van een knop om een document naar een ander formaat te converteren.

Implementatietype

Het implementeren van een extensie omvat een XML, een clientSideInstance.xml of een elements.xml. Je kunt dit XML vinden in de map SharePoint/assets van je oplossing in Visual Studio Code. Deze xml-bestanden zijn opgenomen in de feature van je oplossing (zie features in het bestand package-solution.json).

Het verschil tussen de 2 xml-bestanden ligt in het feit dat de clientSideInstance.xml wordt gebruikt om je extensie tenantbreed te implementeren. Dit gebeurt wanneer je app wordt geïmplementeerd in de app-catalogus. Als een clientSideInstance.xml-bestand wordt gevonden tijdens de implementatie van je app, wordt je extensie geïmplementeerd in de verborgen lijst Tenant Wide Extensions. Dit betekent dat elke keer dat je extensie ergens binnen SharePoint wordt geladen, de configuratie voor deze extensie wordt gelezen uit deze lijst met tenantbrede extensies.

Als we kijken naar de verschillende eigenschappen in een dergelijk xml van een clientSideInstance, kunnen we het volgende onderscheiden:

• Title: Dit is de titel van je aangepaste actie
• Location: Dit bepaalt de locatie waar de client-side component wordt weergegeven. Hier wordt opgegeven dat de component een ListViewCommandSet is die wordt weergegeven in de opdrachtbalk van een SharePoint-lijst.
• ListTemplateId: Deze waarde geeft aan op welke lijstsjabloon de client-side component moet worden toegepast. Lijstsjabloon-ID 100 verwijst naar een aangepaste lijst.
• Location: Dit geeft aan waar de actie wordt weergegeven. In dit geval geeft het aan dat de actie een ClientSideExtension is en dat het een ListViewCommandSet is die moet verschijnen in de CommandBar van een SharePoint-lijst.
• properties: Deze parameter bevat een JSON-object met eigen eigenschappen die worden doorgegeven aan de SPFx-component wanneer deze wordt uitgevoerd. In dit geval worden twee eigenschappen, sampleTextOne en sampleTextTwo, doorgegeven met de waarden “One item is selected in the list.” en “This command is always visible.”.
• ComponentId: Dit is de unieke ID van de Client-Side component die is gekoppeld aan deze aangepaste actie. Dit GUID verwijst naar de SPFx-component (bijvoorbeeld een webonderdeel of extensie) die wordt geladen wanneer de actie wordt uitgevoerd.

<?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>

Wanneer een elements.xml wordt gevonden, wordt dit xml gebruikt voor de implementatie op siteverzamelingsniveau. Met deze implementatie wordt je extensie alleen geconfigureerd op siteverzamelingsniveau. Als we kijken naar het xml van het bestand elements.xml, kunnen we de volgende eigenschappen onderscheiden:

• Title: Dit is de titel van je aangepaste actie
• RegistrationId: Dit specificeert welke lijst(en) of inhoudstypen worden beïnvloed door deze aanpassing. De waarde “100” komt overeen met de ID van de lijstdefinitie. Lijstdefinitie 100 verwijst naar een standaard aangepaste lijst.
• RegistrationType: Deze parameter geeft het type SharePoint-object aan waarop de actie is geregistreerd. De waarde “List” betekent dat de actie voor een lijst van toepassing is.
• Location: Dit geeft aan waar de actie wordt weergegeven. In dit geval geeft het aan dat de actie een ClientSideExtension is en dat het een ListViewCommandSet is die moet verschijnen in de CommandBar van een SharePoint-lijst.
• ClientSideComponentId: Dit is de unieke ID van de Client-Side component die is gekoppeld aan deze aangepaste actie. Dit GUID verwijst naar de SPFx-component (bijvoorbeeld een webonderdeel of extensie) die wordt geladen wanneer de actie wordt uitgevoerd.
• ClientSideComponentProperties: Deze parameter bevat een JSON-object met eigen eigenschappen die worden doorgegeven aan de SPFx-component wanneer deze wordt uitgevoerd. In dit geval worden twee eigenschappen, sampleTextOne en sampleTextTwo, doorgegeven met de waarden “One item is selected in the list.” en “This command is always visible.”.

<?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>

Deze 2 bestanden zijn ingebakken in je app, maar wanneer wordt er beslist welk xml er gebruikt wordt? Dit gebeurt wanneer je app wordt geïmplementeerd in de app-catalogus. Wanneer we dit gaan implementeren, zien we het volgende scherm verschijnen:

Als je “Make this solution available to all sites in the organization” aanvinkt, wordt het bestand clientSideInstance.xml gebruikt en wordt de extensie geïmplementeerd in de lijst met tenantbrede extensies. Als je deze optie niet aanvinkt, wordt het bestand elements.xml gebruikt wanneer je specifiek een app toevoegt aan een siteverzameling.