Mise en service des composants SharePoint avec votre package de solutions

Dans certains cas, vous devrez configurer une bibliothèque de documents ou une liste SharePoint, ainsi que votre package de solution côté client, afin que cette liste ou bibliothèque soit disponible pour les composants côté client, comme les composants WebPart. La chaîne d’outils de l’infrastructure SharePoint vous permet de créer un package et de déployer des éléments SharePoint avec votre package de solution côté client. Ces éléments sont ensuite mis en service lorsque la solution côté client est installée sur un site.

Vous trouverez également des informations sur les options de mise en service dans ce webcast PnP SharePoint sur la chaîne YouTube de SharePoint PnP :



Mettre en service des éléments avec du code JavaScript

Même si vous pouvez créer des éléments SharePoint avec du code JavaScript dans votre composant, comme des composants WebPart, cette possibilité est limitée selon le contexte de l’utilisateur actuel du composant. Si l’utilisateur ne dispose pas des autorisations nécessaires pour créer ou modifier des éléments SharePoint, le code JavaScript ne configurera pas ces éléments. Dans ce cas, pour mettre en service des éléments SharePoint dans un contexte élevé, vous devez créer un package et déployer des éléments avec votre package de solution.

Mettre en service des éléments SharePoint dans votre solution

Les composants SharePoint suivants peuvent être mis en service avec votre package de solution côté client :

  • Champs
  • Types de contenu
  • Répertorier les instances
  • Instances de liste avec schéma personnalisé

Champs

Un champ, ou colonne de site, représente un attribut ou un élément de métadonnées que l’utilisateur souhaite gérer pour les éléments de la liste ou pour le type de contenu auquel il a ajouté la colonne. Il s’agit d’une définition de colonne ou modèle réutilisable que vous pouvez affecter à plusieurs listes dans différents sites SharePoint. Les colonnes de site évitent les remaniements et vous garantissent une cohérence des métadonnées dans les sites et les listes.

Par exemple, supposons que vous définissez une colonne de site nommée Client. Les utilisateurs peuvent ajouter cette colonne à leurs listes et la référencer dans leurs types de contenu. Cela garantit que la colonne a les mêmes attributs partout où elle apparaît, au moins au début.

Vous pouvez consulter le schéma et les attributs dans la documentation Field, élément (Field) pour définir un nouveau champ dans votre solution.

Voici l’exemple d’un nouveau champ DateHeure :

<Field ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}"
            Name="DateOpened"
            DisplayName="Date Opened"
            Type="DateTime"
            Format="DateOnly"
            Required="FALSE"
            Group="Financial Columns">
        <Default>[today]</Default>
    </Field>

Types de contenu

Un type de contenu est un ensemble de métadonnées (colonnes), un comportement ou un autre paramètre réutilisable pour une catégorie d’éléments ou de documents dans une bibliothèque de documents ou liste SharePoint. Les types de contenu permettent de gérer les paramètres pour une catégorie d’informations de manière centralisée et de sorte à pouvoir les réutiliser.

Par exemple, imaginons une situation de gestion dans laquelle vous disposez de trois types de documents différents : notes de frais, commandes achat et factures. Les trois types de documents présentent des caractéristiques communes. D’un côté, ce sont tous des documents financiers et ils contiennent des données dont des valeurs monétaires. De l’autre, chaque type de document a ses propres exigences des données, son propre modèle de document et son propre flux de travail. Une solution à ce problème de gestion consiste à créer quatre types de contenu. Le premier type de contenu, Document financier, peut encapsuler les exigences des données communes à tous les documents financiers dans l’organisation. Les trois autres, Note de frais, Commande achat et Facture, peuvent hériter des éléments communs de Document financier. En outre, ils peuvent définir des caractéristiques propres à chaque type, telles qu’un ensemble de métadonnées particulier, un modèle de document à utiliser lors de la création d’un élément et un flux de travail spécifique pour le traitement d’un élément.

Par exemple, imaginons une situation de gestion dans laquelle vous disposez de trois types de documents différents : notes de frais, commandes achat et factures. Les trois types de documents présentent des caractéristiques communes. D’un côté, ce sont tous des documents financiers et ils contiennent des données dont des valeurs monétaires. De l’autre, chaque type de document a ses propres exigences des données, son propre modèle de document et son propre flux de travail. Une solution à ce problème de gestion consiste à créer quatre types de contenu. Le premier type de contenu, Document financier, peut encapsuler les exigences des données communes à tous les documents financiers dans l’organisation. Les trois autres, Note de frais, Commande achat et Facture, peuvent hériter des éléments communs de Document financier. En outre, ils peuvent définir des caractéristiques propres à chaque type, telles qu’un ensemble de métadonnées particulier, un modèle de document à utiliser lors de la création d’un élément et un flux de travail spécifique pour le traitement d’un élément.

Vous pouvez consulter le schéma et les attributs dans la documentation ContentType, élément (ContentType) pour définir un nouveau type de contenu dans votre solution.

Voici un exemple de type de contenu :

<ContentType ID="0x010042D0C1C200A14B6887742B6344675C8B" 
    Name="Cost Center" 
    Group="Financial Content Types" 
    Description="Financial Content Type">
    <FieldRefs>
        <FieldRef ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}" />
        <FieldRef ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}" /> 
    </FieldRefs>
</ContentType> 

Répertorier les instances

Les listes sont une fonctionnalité sous-jacente clé d’un site SharePoint. Elles permettent aux équipes de collecter, suivre et partager des informations. De nombreuses applications se basent sur les listes créées au niveau du site pour le stockage des données afin d’implémenter leur comportement. Une instance de liste est une liste SharePoint prédéfinie qui a un identificateur connu. Vous pouvez personnaliser et ajouter des éléments à ces listes, créer des listes supplémentaires à partir de modèles de liste qui sont déjà disponibles et créer des listes personnalisées composées uniquement des paramètres et des colonnes que vous choisissez.

Microsoft Office SharePoint Online propose plusieurs modèles de liste, comme la liste des contacts, le calendrier, la liste des tâches et bien plus encore. Vous pouvez utiliser ces modèles afin de créer de nouvelles instances de liste pour vos composants WebPart ou d’autres composants. Par exemple, vous pouvez définir une instance de liste Documents financiers basée sur le modèle de bibliothèque de documents pour stocker des documents associés à votre composant WebPart.

Vous pouvez consulter le schéma et les attributs dans la documentation ListInstance, élément (List Instance) pour définir une instance de liste dans votre solution.

Voici un exemple de définition d’instance de liste :

<ListInstance 
    FeatureId="00bfea71-e717-4e80-aa17-d0c71b360101"
    Title="Finance Records" 
    Description="Finance documents"
    TemplateType="101"
    Url="Lists/FinanceRecords">
</ListInstance>

Instances de liste avec schéma personnalisé

Vous pouvez utiliser une définition de schéma de liste personnalisée afin de définir les champs, les types de contenu et les affichages utilisés dans votre instance de liste. Pour référencer un schéma personnalisé pour l’instance de liste, utilisez l’attribut CustomSchema dans l’élément ListInstance.

Par exemple, vous pouvez définir une instance de liste Documents financiers avec un type de contenu Document financier pouvant encapsuler les exigences en matière de données qui sont communes à tous les documents financiers de l’organisation.

Voici un exemple de définition d’une instance de liste qui utilise un schéma personnalisé :

<ListInstance 
    CustomSchema="schema.xml"
    FeatureId="00bfea71-de22-43b2-a848-c05709900100"
    Title="Cost Centers" 
    Description="Cost Centers"
    TemplateType="100"
    Url="Lists/CostCenters">
</ListInstance>

Voici la définition de schéma personnalisé qui définit un type de contenu pour l’instance de liste définie précédemment :

<List xmlns:ows="Microsoft SharePoint" Title="Basic List" EnableContentTypes="TRUE" FolderCreation="FALSE" Direction="$Resources:Direction;" Url="Lists/Basic List" BaseType="0" xmlns="http://schemas.microsoft.com/sharepoint/">
  <MetaData>
    <ContentTypes>
      <ContentTypeRef ID="0x010042D0C1C200A14B6887742B6344675C8B" />
    </ContentTypes>
    <Fields></Fields>
    <Views>
      <View BaseViewID="1" Type="HTML" WebPartZoneID="Main" DisplayName="$Resources:core,objectiv_schema_mwsidcamlidC24;" DefaultView="TRUE" MobileView="TRUE" MobileDefaultView="TRUE" SetupPath="pages\viewpage.aspx" ImageUrl="/_layouts/images/generic.png" Url="AllItems.aspx">
        <XslLink Default="TRUE">main.xsl</XslLink>
        <JSLink>clienttemplates.js</JSLink>
        <RowLimit Paged="TRUE">30</RowLimit>
        <Toolbar Type="Standard" />
        <ViewFields>
          <FieldRef Name="LinkTitle"></FieldRef>
          <FieldRef Name="SPFxAmount"></FieldRef>
          <FieldRef Name="SPFxCostCenter"></FieldRef>
        </ViewFields>
        <Query>
          <OrderBy>
            <FieldRef Name="ID" />
          </OrderBy>
        </Query>
      </View>
    </Views>
    <Forms>
      <Form Type="DisplayForm" Url="DispForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
      <Form Type="EditForm" Url="EditForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
      <Form Type="NewForm" Url="NewForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
    </Forms>
  </MetaData>
</List>

Créer des éléments SharePoint dans votre solution

Le package de solution utilise des fonctionnalités Microsoft Office SharePoint Online pour créer un package et mettre en service les éléments SharePoint. Une fonctionnalité est un conteneur qui inclut des éléments SharePoint à mettre en service. Une fonctionnalité contient un fichier Feature.xml, ainsi que des fichiers manifeste d’élément. Ces fichiers XML sont également appelés définitions de fonctionnalité.

En général, un package de solution côté client contient une fonctionnalité. Cette fonctionnalité est activée lorsque la solution est installée sur un site. N’oubliez pas que les administrateurs de site installent votre package de solution et non la fonctionnalité.

Une fonctionnalité est principalement construite à l’aide des fichiers XML ci-après.

Fichier manifeste d’élément

Le fichier manifeste d’élément contient les définitions des éléments Microsoft Office SharePoint Online et est exécuté lors de l’activation de la fonctionnalité. Par exemple : les définitions XML permettant de créer un champ ou un type de contenu, ou des instances de liste, sont contenues dans le manifeste d’élément.

Voici un exemple de fichier manifeste d’élément qui définit un nouveau champ Date/Heure.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <Field ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}"
            Name="DateOpened"
            DisplayName="Date Opened"
            Type="DateTime"
            Format="DateOnly"
            Required="FALSE"
            Group="Financial Columns">
        <Default>[today]</Default>
    </Field>
  </Elements>

Fichier d’élément

Par exemple, le schéma d’instance de liste est un fichier d’élément associé à une instance de liste définie dans un manifeste d’élément.

Voici un exemple de schéma d’instance de liste personnalisé :

<List xmlns:ows="Microsoft SharePoint" Title="Basic List" EnableContentTypes="TRUE" FolderCreation="FALSE"
      Direction="$Resources:Direction;" Url="Lists/Basic List" BaseType="0" xmlns="http://schemas.microsoft.com/sharepoint/">
  <MetaData>
    <ContentTypes>
      <ContentTypeRef ID="0x010042D0C1C200A14B6887742B6344675C8B" />
    </ContentTypes>    
  </MetaData>
</List>

Fichier d’actions de mise à niveau

Comme son nom l’indique, il s’agit du fichier qui inclut les actions de mise à niveau lorsque la solution est mise à jour dans le site. Dans le cadre des opérations de mise à niveau, l’action peut également indiquer d’inclure des fichiers manifeste d’élément. Par exemple : si la mise à niveau nécessite l’ajout d’un nouveau champ, la définition du champ sera disponible en tant que manifeste d’élément et sera associée au fichier d’actions de mise à niveau.

Voici un exemple de fichier d’actions de mise à niveau qui applique un fichier manifeste d’élément pendant la mise à niveau :

<ApplyElementManifests>
      <ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
</ApplyElementManifests>

Configurer la fonctionnalité SharePoint

Pour inclure les fichiers XML, vous devez d’abord définir la configuration de la fonctionnalité dans le fichier de configuration package-solution.json sous le dossier config dans votre projet. Le fichier package-solution.json contient les informations de métadonnées clés sur votre package de solution côté client. Il est référencé lorsque vous exécutez la tâche gulp package-solution qui rassemble votre solution dans un fichier .sppkg.

{
  "solution": {
    "name": "hello-world-client-side-solution",
    "id": "26364618-3056-4b45-98c1-39450adc5723",
    "version": "1.1.0.0",
    "features": [{
      "title": "hello-world-client-side-solution",
      "description": "hello-world-client-side-solution",
      "id": "d46cd9d6-87fc-473b-a4c0-db9ad9162b64",
      "version": "1.1.0.0",
      "assets": {        
        "elementManifests": [
          "elements.xml"
        ],
        "elementFiles":[
          "schema.xml"
        ],
        "upgradeActions":[
            "upgrade-actions-v1.xml"
        ]
      }
    }]
  },  
  "paths": {
    "zippedPackage": "solution/hello-world.sppkg"
  }
}

L’objet JSON features contient les métadonnées relatives à la fonctionnalité, comme illustré dans le tableau suivant.

Propriété Description
id Identificateur unique (GUID) de la fonctionnalité
title Titre de la fonctionnalité
description Description de la fonctionnalité
assets Tableau de fichiers XML utilisés dans la fonctionnalité
elementManifests Défini dans la propriété assets ; tableau des fichiers manifeste d’élément
elementFiles Défini dans la propriété assets ; tableau des fichiers d’élément
upgradeActions Défini dans la propriété assets ; tableau des fichiers d’action de mise à niveau

Créer les fichiers XML de fonctionnalité

La chaîne d’outils recherche les fichiers XML tels que définis dans la configuration sous un dossier spécial (sharepoint\assets) dans votre projet de solution côté client.

Fichiers XML de fonctionnalité dans un projet de solution côté client

Les configurations définies dans le fichier package-solution.json permettent de mapper les fichiers XML avec leur fichier XML de fonctionnalité approprié lors de l’exécution de la tâche Gulp package-solution.

Créer un package d’éléments SharePoint

Une fois que vous avez défini votre fonctionnalité dans package-solution.json et que vous avez créé les fichiers XML de fonctionnalité respectifs, vous pouvez utiliser la tâche gulp suivante pour rassembler les éléments SharePoint avec votre package .sppkg.

gulp package-solution

Cette commande permet de créer un package regroupant les manifestes de composant côté client, comme les composants WebPart, ainsi que les fichiers XML de fonctionnalité référencés dans le fichier de configuration package-solution.json.

Notes

Vous pouvez utiliser l’indicateur --ship pour créer un package de versions réduites de vos composants.

Mettre à niveau des éléments SharePoint

Vous pouvez inclure les nouveaux éléments SharePoint ou mettre à jour les éléments SharePoint existants lors de la mise à niveau de votre solution côté client. Comme la mise en service d’éléments SharePoint utilise des fonctionnalités, vous utilisez le fichier XML UpgradeActions des fonctionnalités pour définir la liste des actions de mise à niveau.

Le tableau d’objets JSON upgradeActions dans le fichier package-solution.json fait référence aux fichiers XML de fonctionnalité associés aux actions de mise à niveau de votre fonctionnalité. Au moins un fichier d’action de mise à niveau définit le fichier XML manifeste d’élément qui est exécuté lors de la mise à niveau de la fonctionnalité.

Lors de la mise à niveau d’une solution SharePoint Framework, vous devez également mettre à jour les attributs de version pour la solution et la fonctionnalité, dans lesquelles les actions de mise à niveau ont été incluses. L’incrémentation de version de la solution indique à SharePoint et aux utilisateurs finals qu’une nouvelle version du package est disponible. L’incrémentation de version de l’élément garantit que les tâches définies dans les actions de mise à jour sont traitées dans le cadre de la mise à niveau de la solution.

Voici un exemple de fichier d’action de mise à niveau qui applique un fichier manifeste d’élément pendant la mise à niveau :

<ApplyElementManifests>
      <ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
</ApplyElementManifests>

Voici le fichier element-v2.xml correspondant qui définit un nouveau champ Devise à mettre en service pendant la mise à niveau :

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <Field ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}"
            Name="Amount"
            DisplayName="Amount"
            Type="Currency"
            Decimals="2"
            Min="0"
            Required="FALSE"
            Group="Financial Columns" />
</Elements>

Sous-éléments

Les actions de mise à niveau dans les solutions côté client prennent en charge les sous-éléments ci-après.

AddContentTypeField

Permet d’ajouter un nouveau champ à un type de contenu mis en service existant. Permet de propager la modification du type de contenu de site à toutes les listes et les types de contenu enfant dans le site. Par exemple :

<AddContentTypeField 
     ContentTypeId="0x010100A6F9CE1AFE2A48f0A3E6CB5BB770B0F7" 
     FieldId="{B250DCFD-9310-4e2d-85F2-BE2DA37A57D2}" 
     PushDown="TRUE" />

ApplyElementManifests

Permet d’ajouter un nouvel élément à une fonctionnalité existante. Lorsqu’une fonctionnalité est mise à niveau, ce composant met en service tous les éléments non déclaratifs qui sont référencés dans les manifestes de l’élément spécifié.

VersionRange

Permet de spécifier une plage de versions auxquelles les actions de mise à niveau spécifiées sont appliquées.

Voir aussi