Partager via

Présentation et configuration du modèle de transformation de page de publication (à compter de la version de juin 2019)

Les pages de publication sont toujours basées sur une mise en page et une page master. Ces deux pages combinées aux champs contenant des données constituent la page qu’un utilisateur voit dans le navigateur. Lors de la transformation des pages de publication, il est donc obligatoire de mapper les mises en page utilisées dans un modèle de transformation de page de publication. Le composant de transformation de page de publication aura un mappage de mise en page « par défaut » pour toutes les mises en page prêtes à l’emploi. Par conséquent, si votre portail utilise ces mises en page prêtes à l’emploi, vous êtes couvert. La réalité est que la plupart des portails utilisent des mises en page personnalisées (et des pages master personnalisées) et qu’il est donc nécessaire de disposer de mappages de mise en page pour ces mises en page personnalisées. Les mises en page personnalisées peuvent être gérées de deux manières :

  • L’option recommandée est de fournir vous-même un fichier de mappage de mise en page personnalisée, ce qui vous donne un contrôle total sur les champs traduits en composants WebPart et l’emplacement où ils résident sur la page moderne, les champs qui deviennent des métadonnées, etc.
  • Si aucun mappage de mise en page n’est trouvé pour la page que vous transformez, nous allons générer un mappage à la volée et l’utiliser. L’inconvénient de cette approche est que tout le contenu se retrouve dans la même section et la même colonne de la page moderne.

Génération d’un fichier de mappage de mise en page

Si vous utilisez des mises en page personnalisées, il est recommandé d’utiliser un fichier de mappage de mise en page personnalisé afin de pouvoir obtenir des pages modernes plus précises. Heureusement, vous n’avez pas besoin de créer à la main ces fichiers de disposition personnalisés. Il existe une API .Net et la prise en charge de PowerShell PnP pour en générer un.

Utiliser PowerShell

À l’aide de l’applet de Export-PnPPageMapping commande, vous pouvez :

  • Exportez le fichier de mappage intégré (-BuiltInPageLayoutMapping paramètre) : ce fichier sera utilisé pour les mises en page prêtes à l’emploi. Si vous spécifiez un mappage personnalisé pour une mise en page prête à l’emploi dans votre propre fichier de mappage, ce mappage prend la préférence par rapport au mappage OOB
  • Analysez les mises en page dans le portail connecté et exportez-les sous la forme d’un fichier de mappage (-CustomPageLayoutMapping paramètre) : toutes les mises en page personnalisées trouvées sont analysées et exportées. Si vous souhaitez également analyser vos mises en page OOB, utilisez le -AnalyzeOOBPageLayouts paramètre .
# Connect to your "classic" portal
Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/classicportal -Interactive

# Analyze and export the page layout mapping files
Export-PnPPageMapping -BuiltInPageLayoutMapping -CustomPageLayoutMapping -Folder c:\temp

Utilisation de .Net

Dans .Net, vous devez utiliser la PageLayoutAnalyser classe pour analyser les mises en page. Les deux extraits de code ci-dessous montrent comment analyser toutes les mises en page ou les mises en page utilisées par certaines pages de publication.

string siteUrl = "https://contoso.sharepoint.com/sites/classicportal";
AuthenticationManager am = new AuthenticationManager("<Azure AD client id>", "joe@contoso.onmicrosoft.com", "Pwd as SecureString");
using (var cc = am.GetSharePointOnlineAuthenticatedContextTenant(siteUrl))
{
    var analyzer = new PageLayoutAnalyser(cc);
    // Analyze all found page layouts
    analyzer.AnalyseAll();  
    analyzer.GenerateMappingFile("c:\\temp", "custompagelayoutmapping.xml");
}

string siteUrl = "https://contoso.sharepoint.com/sites/classicportal";
AuthenticationManager am = new AuthenticationManager("<Azure AD client id>", "joe@contoso.onmicrosoft.com", "Pwd as SecureString");
using (var cc = am.GetSharePointOnlineAuthenticatedContextTenant(siteUrl))
{
    var analyzer = new PageLayoutAnalyser(cc);
    // Analyze all the unique page layouts for publishing pages starting with an "a"
    var pages = cc.Web.GetPagesFromList("Pages", "a");
    foreach (var page in pages)
    {
        analyzer.AnalysePageLayoutFromPublishingPage(page);
    }

    analyzer.GenerateMappingFile("c:\\temp", "custompagelayoutmapping.xml");
}

Explication du modèle de mappage de mise en page

Lorsque vous ouvrez un fichier de mappage de mise en page, les éléments de niveau supérieur suivants sont présents :

  • AddOns : en tant qu’utilisateur de la transformation de page, vous pouvez avoir besoin d’appliquer une logique personnalisée pour répondre à vos besoins, par exemple, vous devez transformer une propriété donnée de manière à ce qu’elle puisse fonctionner avec votre composant WebPart SPFX personnalisé. Le framework prend en charge cela en vous permettant d’ajouter vos assemblys avec des fonctions... En les définissant simplement dans la section AddOn, puis en référençant vos fonctions personnalisées ultérieurement en les préfixant avec le nom donné, la transformation de page de publication utilise votre code personnalisé.

  • PageLayouts : cet élément contient des informations pour chaque mise en page que vous prévoyez d’utiliser. Pour chaque mise en page, vous trouverez une définition de l’en-tête, du composant WebPart, des métadonnées, des zones de composants WebPart et des composants WebPart fixes.

De plus amples informations vous seront fournies dans les prochains chapitres.

Définition pageLayout dans le modèle de mise en page

Analysons comment un mappage de mise en page est configuré dans le modèle de mappage de mise en page, ce qui est préférable en fonction d’un exemple de définition :

    <PageLayout Name="MyPageLayout" AlsoAppliesTo="MyOtherPageLayout;MyOtherPageLayout2" AssociatedContentType="CustomPage1" PageLayoutTemplate="AutoDetect" IncludeVerticalColumn="true" PageHeader="Custom">
      <SectionEmphasis VerticalColumnEmphasis="Soft">
        <Section Row="3" Emphasis="Neutral" />
      </SectionEmphasis>
      <Header Type="FullWidthImage" Alignment="Left" ShowPublishedDate="true">
        <Field Name="PublishingRollupImage;PublishingPageImage" HeaderProperty="ImageServerRelativeUrl" Functions="ToImageUrl({@name})" />
        <Field Name="ArticleByLine" HeaderProperty="TopicHeader" Functions=""/>
        <Field Name="PublishingContact" HeaderProperty="Authors" Functions="ToAuthors({PublishingContact})"/>
      </Header>
      <MetaData ShowPageProperties="true" PagePropertiesRow="1" PagePropertiesColumn="4" PagePropertiesOrder="1">
        <Field Name="PublishingContactName;PublishingContactEmail" TargetFieldName="MyPageContact" Functions="" />
        <Field Name="MyCategory" TargetFieldName="Category" Functions="" ShowInPageProperties="true" />
      </MetaData>
      <WebParts>
        <Field Name="PublishingPageImage" TargetWebPart="SharePointPnP.Modernization.WikiImagePart" Row="1" Column="1" Order="1">
          <Property Name="ImageUrl" Type="string" Functions="ToImageUrl({PublishingPageImage})"/>
          <Property Name="AlternativeText" Type="string" Functions="ToImageAltText({PublishingPageImage})" />
        </Field>
        <Field Name="PublishingPageContent" TargetWebPart="SharePointPnP.Modernization.WikiTextPart" Row="1" Column="2" Order="1">
          <Property Name="Text" Type="string" Functions="" />
        </Field>
      </WebParts>
      <WebPartZones>
        <WebPartZone Row="2" Column="1" Order="1" ZoneId="g_0C7F16935FAC4709915E2D77092A90DE" ZoneIndex="0">
          <!-- Optional element, only needed if you want to use custom position of the web parts coming from a web part zone -->
          <WebPartZoneLayout>
            <WebPartOccurrence Type="Microsoft.SharePoint.WebPartPages.ContentEditorWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="3" Column="2"/>
            <WebPartOccurrence Type="Microsoft.SharePoint.WebPartPages.ContentEditorWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="3" Column="1" Order="2"/>
            <WebPartOccurrence Type="Microsoft.SharePoint.WebPartPages.XsltListViewWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="3" Column="1" Order="1"/>
          </WebPartZoneLayout>
        </WebPartZone>
      </WebPartZones>
      <FixedWebParts>
        <WebPart Row="1" Column="2" Order="1" Type="Microsoft.SharePoint.WebPartPages.ContentEditorWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c">
          <Property Name="TITLE" Type="string" Value="Example Embedded Web Content Editor"/>
          <Property Name="CONTENT" Type="string" Value="PnP Rocks!"/>
        </WebPart>
      </FixedWebParts>
    </PageLayout>

Remarque

Il est recommandé d’utiliser le schéma pagelayoutmapping.xsd lors de la modification de ces fichiers. Les fichiers que vous fournissez à la transformation de page sont validés par rapport à ce schéma et la transformation échoue lorsque le fichier de mappage de mise en page fourni n’est pas valide.

Élément PageLayout

Les propriétés suivantes sont utilisées sur l’élément PageLayout :

  • Nom : contient le nom de votre mise en page.
  • AlsoAppliesTo : lorsque ce mappage est utilisé pour plusieurs mises en page, vous pouvez spécifier les noms de ces mises en page supplémentaires sous la forme d’une liste délimitée par des points-virgules dans cet attribut. La propriété Name sera le nom de la première mise en page, alsoAppliesTo contient simplement les autres.
  • AssociatedContentType : nom du type de contenu de page de site moderne que vous souhaitez utiliser. Laissez ce champ vide si vous souhaitez utiliser le type de contenu de page de site par défaut.
  • PageLayoutTemplate : système de disposition à utiliser... par défaut, AutoDetect ce qui devrait fonctionner correctement dans tous les cas, mais éventuellement, vous pouvez également choisir une disposition wiki spécifique.
  • IncludeVerticalColumn : élément facultatif pour spécifier que la page cible créée doit avoir une colonne verticale. Lorsque vous utilisez une colonne verticale, vous ciblez la colonne verticale en tant que colonne supplémentaire. Par conséquent, si vous aviez 3 colonnes avant d’ajouter une colonne verticale, vous en aurez désormais 4 et, par conséquent, vous pouvez définir la valeur de colonne du contenu de la page sur 4 pour la placer dans la colonne verticale.
  • PageHeader : contrôle le type d’en-tête de page qui sera utilisé. La valeur par défaut est Custom , car cela permet un en-tête agréable, mais vous pouvez le basculer vers None sans en-tête ou Default pour l’en-tête de page moderne par défaut.

Élément SectionEmphasis

Les propriétés suivantes sont utilisées sur l’élément facultatif SectionEmphasis :

  • VerticalColumnEmphasis : utilisez cette propriété pour définir l’accentuation de colonne verticale sur None, Neutral, Soft ou Strong

Pour chaque section, vous pouvez éventuellement spécifier un accent sur la section via l’élément Section :

  • Ligne : indique le numéro de ligne de cette section, la première section aura le numéro 1
  • Accentuation : définit l’accentuation de la section sur None, Neutral, Soft ou Strong

Élément Header

Les propriétés suivantes sont utilisées sur l’élément Header :

  • Type : autorise par défaut l’en-tête FullWidthImage à afficher l’image d’en-tête en pleine largeur. Les autres options sont ColorBlock, CutInShape et NoImage. Notez que cet attribut n’est pertinent que lorsque l’attribut PageHeader a la valeur Custom.
  • Alignement : contrôle la façon dont le contenu de l’en-tête de page est aligné. La valeur par défaut est Left, l’autre option est Center.
  • ShowPublishedDate : définit si la date de publication de la page est affichée. La valeur par défaut est true.

Pour chaque champ que vous souhaitez utiliser dans l’en-tête moderne, vous devez ajouter un élément Field spécifiant :

  • Nom : nom du ou des champs dans la page de publication classique. Par exemple, l’ajout PublishingRollupImage;PublishingPageImage comme valeur signifie que le PublishingRollupImage sera pris s’il a été rempli, s’il n’est pas rempli, le PublishingPageImage sera essayé. Vous pouvez ajouter autant de remplacements que nécessaire
  • HeaderProperty : nom de la propriété d’en-tête à définir
  • Fonctions : si la valeur est vide, la valeur du champ de la page de publication classique est prise telle quelle. Toutefois, si vous spécifiez une fonction ici, la sortie de cette fonction est utilisée. Si vous avez spécifié plusieurs champs (donc à l’aide de l’option de remplacement de champ), vous devez spécifier le champ à utiliser dans la fonction en tant que {@name}

Lors de la construction d’un en-tête de page moderne, il existe 4 propriétés d’en-tête de page que vous pouvez remplir avec les données provenant de la page de publication :

  • ImageServerRelativeUrl : si votre en-tête doit afficher une image, ce champ doit définir un chemin d’accès relatif à l’image du serveur pour une image vivant dans la même collection de sites que la page. Par défaut, le champ de page PublishingRollupImage de publication classique est utilisé, mais comme il contient une balise Img, le contenu du champ est nettoyé via la ToImageUrl fonction .
  • TopicHeader : par défaut, le champ de page ArticleByLine de publication classique est utilisé comme en-tête de rubrique pour l’en-tête de page moderne
  • Auteurs : la définition des auteurs vous permet d’afficher le contact main de cette page dans l’en-tête de page. Par défaut, le champ de page PublishingContact de publication classique est utilisé, mais comme il s’agit d’un champ utilisateur, le contenu du champ est transformé via la ToAuthors fonction .
  • AlternativeText : non mappé par défaut, mais vous pouvez ajouter un mappage personnalisé pour remplir la propriété de texte alternative de l’en-tête moderne si vous le souhaitez

Si, par exemple, vous ne souhaitez pas définir d’en-tête de rubrique, vous pouvez simplement supprimer ou commenter l’élément Field correspondant.

Options d’image d’en-tête de page

Le mappage par défaut prend l’image définie dans le PublishingRollupImage champ comme en-tête de page, mais vous pouvez éventuellement choisir un autre champ d’image de publication ou spécifier une valeur codée en dur d’une image vivant dans le site source ou le site cible. L’exemple ci-dessous montre un en-tête avec une image statique :

<Header Type="FullWidthImage" Alignment="Left" ShowPublishedDate="true">
  <!-- Note that static values do require specifying them between '' -->
  <Field Name="PublishingRollupImage" HeaderProperty="ImageServerRelativeUrl" Functions="StaticString('/sites/classicportal/images/myimage.jpg')" />
  <Field Name="ArticleByLine" HeaderProperty="TopicHeader" Functions=""/>
  <Field Name="PublishingContact" HeaderProperty="Authors" Functions="ToAuthors({PublishingContact})"/>
</Header>

Élément MetaData

L’élément de métadonnées définit les champs de page de publication classiques qui doivent être pris en charge en tant que métadonnées pour la page moderne. Comme parfois, vous souhaitez que les métadonnées soient également représentées à l’aide du composant WebPart Propriétés de la page OOB, vous indiquez que via ces attributs facultatifs :

  • ShowPageProperties : le composant WebPart propriétés de page sera-t-il ajouté à la page moderne résultante
  • PagePropertiesRow : ligne qui contiendra le composant WebPart propriétés de la page
  • PagePropertiesColumn : colonne qui contiendra le composant WebPart propriétés de page
  • PagePropertiesOrder : l’ordre du composant WebPart propriétés de page dans la ligne/colonne définie

Pour chaque champ que vous souhaitez prendre en charge, vous devez ajouter un élément Field spécifiant :

  • Nom : nom du ou des champs dans la page de publication classique. Par exemple, l’ajout PublishingContactName;PublishingContactEmail comme valeur signifie que le PublishingContactName sera pris s’il a été rempli, s’il n’est pas rempli, le PublishingContactEmail sera essayé. Vous pouvez ajouter autant de remplacements que nécessaire
  • TargetFieldName : nom du champ dans la page moderne cible
  • Fonctions : si la valeur est vide, la valeur du champ de la page de publication classique est prise telle quelle. Toutefois, si vous spécifiez une fonction ici, la sortie de cette fonction est utilisée. Si vous avez spécifié plusieurs champs (donc à l’aide de l’option de remplacement de champ), vous devez spécifier le champ à utiliser dans la fonction en tant que {@name}
  • ShowInPageProperties : si la valeur est true et si le composant WebPart propriétés de la page a été activé, ce champ est affiché dans le composant WebPart propriétés de la page

Remarque

  • La prise en charge de Functions n’est pas disponible pour les champs de taxonomie

Élément WebParts

Chaque champ de la page de publication classique qui doit devenir un élément visuel sur la page cible (comme un composant WebPart ou du texte) doit être défini dans la section Composants WebPart :

  • Nom : nom du champ dans la page de publication classique.
  • TargetWebPart : type du composant WebPart cible qui visualisera ce champ sur la page moderne. Les composants WebPart cibles pris en charge sont SharePointPnP.Modernization.WikiTextPart, SharePointPnP.Modernization.WikiImagePart et Microsoft.SharePoint.Publishing.WebControls.SummaryLinkWebPart, Microsoft.SharePoint.Publishing, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c.
  • Ligne : ligne dans laquelle vous souhaitez placer le composant WebPart cible. Doit être égal ou supérieur à 1.
  • Colonne : colonne dans laquelle vous souhaitez placer le composant WebPart cible. Doit être 1, 2 ou 3.
  • Order : ordre du composant WebPart cible dans la ligne/colonne définie.

Selon le TargetWebPart choisi, vous devez fournir les propriétés du composant WebPart contenant les données nécessaires pendant la transformation. Chaque propriété a les propriétés suivantes :

  • Nom : nom de la propriété. Ces noms de propriétés doivent correspondre aux propriétés utilisées dans le modèle de transformation de page.
  • Type : type de la propriété. Ces types de propriétés doivent correspondre aux propriétés utilisées dans le modèle de transformation de page.
  • Fonctions : si la valeur est vide, la valeur de la propriété est la valeur du champ dans la page de publication classique source. Vous pouvez utiliser une fonction pour d’abord transformer le contenu du champ ou pour utiliser les données d’un autre champ de la page de publication classique

Élément WebPartZones

Si la mise en page contient des zones de composants WebPart, celles-ci doivent être définies ici. Cela est nécessaire pour positionner correctement les composants WebPart transformés sur la page moderne. Les propriétés suivantes sont utilisées :

  • ZoneId : nom de la zone
  • ZoneIndex : index de la zone (entier)
  • Ligne : ligne dans laquelle vous souhaitez placer les composants WebPart hébergés dans cette zone. Doit être égal ou supérieur à 1.
  • Colonne : colonne dans laquelle vous souhaitez placer les composants WebPart hébergés dans cette zone. Doit être 1, 2 ou 3.
  • Ordre : ordre dans la ligne/colonne définie pour les composants WebPart hébergés dans cette zone

Parfois, les pages de publication ont plusieurs composants WebPart dans une zone de composant WebPart et vous souhaitez positionner chaque composant WebPart différemment sur la page cible. Pour ce faire, utilisez l’élément Facultatif WebPartZoneLayout :

<WebPartZoneLayout>
  <WebPartOccurrence Type="Microsoft.SharePoint.WebPartPages.ContentEditorWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="3" Column="2"/>
  <WebPartOccurrence Type="Microsoft.SharePoint.WebPartPages.ContentEditorWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="3" Column="1" Order="2"/>
  <WebPartOccurrence Type="Microsoft.SharePoint.WebPartPages.XsltListViewWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="3" Column="1" Order="1"/>
</WebPartZoneLayout>

La définition ci-dessus aura pour conséquence que le premier ContentEditorWebPart ira à la ligne 3, colonne 2. Le deuxième ContentEditorWebPart sera placé dans la ligne 3, colonne 1 avec l’ordre 2 et le premier composant WebPart XSLTListView se retrouvera dans la ligne 3, colonne 1 avec l’ordre 1. Vous pouvez définir autant d’éléments WebPartOccurrence que nécessaire. S’il n’existe aucun composant WebPart correspondant dans la zone du composant WebPart, l’élément WebPartOccurrence sera ignoré. S’il existe un composant WebPart dans la zone du composant WebPart qui n’est pas répertorié en tant qu’élément WebPartOccurrence, ce composant WebPart obtient ses informations de ligne, de colonne et d’ordre à partir de l’élément WebPartZone.

Élément FixedWebParts

Parfois, les mises en page contiennent des composants WebPart « fixes », il s’agit de composants WebPart codés en dur à l’intérieur de la mise en page et qui sont donc présents sur toutes les pages qui utilisent la mise en page. Comme il n’existe aucune API pour détecter ces composants WebPart « fixes », ils doivent être définis dans le cadre du modèle de mappage de mise en page.

Les propriétés suivantes peuvent être définies sur un composant WebPart « fixe » :

  • Type : type du composant WebPart fixe. Consultez cette page pour obtenir la liste des types possibles.
  • Ligne : ligne dans laquelle vous souhaitez placer le composant WebPart « fixe ». Doit être égal ou supérieur à 1.
  • Colonne : colonne dans laquelle vous souhaitez placer le composant WebPart « fixe ». Doit être 1, 2 ou 3.
  • Order : l’ordre, pertinent s’il existe plusieurs composants WebPart que vous placez dans la même ligne et la même colonne.

Pour chaque composant WebPart « fixe », vous devez définir les propriétés appropriées. En règle générale, vous prenez en charge ces propriétés telles qu’elles sont définies dans votre mise en page classique. Pour chaque propriété, les attributs suivants peuvent être définis :

  • Property : nom de la propriété. Ces noms de propriétés doivent correspondre aux propriétés utilisées dans le modèle de transformation de page.
  • Type : type de la propriété. Ces types de propriétés doivent correspondre aux propriétés utilisées dans le modèle de transformation de page.
  • Valeur : valeur de cette propriété. N’oubliez pas d’encoder la valeur au format XML.

Définition de AddOns dans le modèle de mise en page

Les modules complémentaires vous permettent d’insérer votre logique personnalisée dans le modèle de mappage de mise en page en suivant ces 2 étapes :

  • Créer un assembly personnalisé hébergeant vos fonctions personnalisées
  • Déclarer cet assembly personnalisé dans les éléments AddOns

Créer un assembly fonctions/sélecteurs personnalisé

Pour créer vos propres fonctions, référencez l’assembly SharePoint.Modernization.Framework dans votre projet, puis créez une classe qui hérite de la classe SharePointPnP.Modernization.Framework.Functions.FunctionsBase :

using Microsoft.SharePoint.Client;
using SharePointPnP.Modernization.Framework.Functions;
using System;

namespace Contoso.Modernization
{
    public class MyCustomFunctions: FunctionsBase
    {
        public MyCustomFunctions(ClientContext clientContext) : base(clientContext)
        {
        }

        public string MyListAddServerRelativeUrl(Guid listId)
        {
            if (listId == Guid.Empty)
            {
                return "";
            }
            else
            {
                var list = this.clientContext.Web.GetListById(listId);
                list.EnsureProperties(p => p.RootFolder.ServerRelativeUrl);
                return list.RootFolder.ServerRelativeUrl;
            }
        }

    }
}

Déclarer un assembly personnalisé

Avant d’utiliser les fonctions personnalisées, elles doivent être déclarées dans le modèle en ajoutant une référence par bibliothèque/classe dans l’élément AddOns :

<AddOn Name="Custom" Type="Contoso.Modernization.MyCustomFunctions" Assembly="Contoso.Modernization.dll" />

ou (notez le chemin d’accès complet)

<AddOn Name="Custom" Type="Contoso.Modernization.MyCustomFunctions" Assembly="c:\transform\Contoso.Modernization.dll" />

Notez que chaque déclaration porte un nom (« Custom » dans l’exemple ci-dessus).

Utiliser les fonctions/sélecteurs personnalisés

Une fois l’assembly défini, vous pouvez utiliser vos fonctions et sélecteurs en les référençant par leur nom (par exemple, par le préfixe « Custom » dans l’exemple ci-dessous) :

<Property Name="ListId" Type="guid" Functions="{ListServerRelativeUrl} = Custom.MyListAddServerRelativeUrl({ListId})"/>

FAQ sur le mappage de mise en page

Je souhaite conserver les informations de création de page source

Lorsque vous utilisez l’approche PowerShell PnP , utilisez l’applet de -KeepPageCreationModificationInformation commande dans l’applet de ConvertTo-PnPPage commande . Lorsque vous utilisez l’approche .Net , définissez le paramètre sur KeepPageCreationModificationInformation true. L’utilisation de cette option donne à la page cible les valeurs des champs Créé, Modifié, Auteur et Rédacteur de la page source.

Remarque

Lorsque, dans le cadre de la transformation de page, vous promouvez la page en tant qu’actualités ou publiez la page, le champ Rédacteur est défini sur la transformation de page en cours d’exécution du compte

Je veux promouvoir les pages créées en tant qu’actualités

La promotion des pages créées à partir d’une mise en page en tant que pages d’actualités peut être effectuée à l’aide du -PostAsNews paramètre sur l’applet -KeepPageCreationModificationInformation de commande (lorsque vous utilisez l’approche PowerShell PnP) ou en définissant le PostAsNews paramètre sur true (lors de l’utilisation de l’approche .Net).

Lorsque vous utilisez l’option PostAsNews conjointement avec l’option , FirstPublishedDateField le KeepPageCreationModificationInformation champ est défini sur la date de modification de la page source. Le FirstPublishedDateField champ est la valeur de date affichée pendant le cumul des actualités.

Je souhaite insérer du texte codé en dur sur la page créée

Parfois, une mise en page contient des extraits de texte qui, étant donné qu’ils ne sont pas contenus dans la page réelle, ne sont pas transformés. Si c’est le cas, vous pouvez définir un « faux » champ à mapper comme indiqué ci-dessous :

<WebParts>
  ...
  <Field Name="ID" TargetWebPart="SharePointPnP.Modernization.WikiTextPart" Row="1" Column="3">
    <Property Name="Text" Type="string" Functions="StaticString('&lt;H1&gt;This is some extra text&lt;/H1&gt;')" />
  </Field>
  ...
</WebParts>

Remarque

Le code HTML fourni dans la fonction StaticString doit être encodé au format XML et doit être mis en forme comme le code HTML de la page source, car ce code HTML sera toujours converti en CODE HTML qui est conforme à l’éditeur de texte moderne

Je souhaite préfixer ou suffixe le contenu du champ

L’approche utilisée dans le chapitre précédent vous permet d’ajouter du texte supplémentaire sur une page, mais a comme inconvénient que le texte supplémentaire sera ajouté dans sa propre partie de texte. Si vous souhaitez que le texte supplémentaire soit intégré au texte réel en cours de transformation, l’approche ci-dessous vous permet de le faire. Vous pouvez préfixer et/ou suffixe le contenu de champ existant et éventuellement vous pouvez uniquement effectuer le préfixe/suffixe lorsque le champ contient du contenu. Le paramètre bool dans les Prefixfonctions , Suffix et PrefixAndSuffix définit si le préfixe/suffixe doit se produire lorsque le contenu du champ est vide : « true » signifie appliquer l’action même lorsque le champ est vide.

Pour plus d’informations sur les fonctions ci-dessous, consultez Fonctions de transformation de page et sélecteurs .

<WebParts>
...
  <Field Name="PublishingPageContent" TargetWebPart="SharePointPnP.Modernization.WikiTextPart" Row="1" Column="2">
    <Property Name="Text" Type="string" Functions="PrefixAndSuffix('&lt;H1&gt;Prefix some extra text&lt;/H1&gt;','&lt;H1&gt;Suffix some extra text&lt;/H1&gt;',{PublishingPageContent},'false')" />
  </Field>
  ...
  <Field Name="PublishingPageContent" TargetWebPart="SharePointPnP.Modernization.WikiTextPart" Row="1" Column="2">
    <Property Name="Text" Type="string" Functions="Prefix('&lt;H1&gt;Prefix some extra text&lt;/H1&gt;',{PublishingPageContent},'true')" />
  </Field>
  ...
  <Field Name="PublishingPageContent" TargetWebPart="SharePointPnP.Modernization.WikiTextPart" Row="1" Column="2">
    <Property Name="Text" Type="string" Functions="Suffix('&lt;H1&gt;Suffix some extra text&lt;/H1&gt;',{PublishingPageContent},'false')" />
  </Field>
...
</WebParts>

Je souhaite remplir un champ de métadonnées managées avec un ou plusieurs termes

Lorsque vous avez un champ de métadonnées managées dans les métadonnées de la page source, vous souhaiterez peut-être avoir un champ de métadonnées managées similaire pour la page cible. Étant donné que la transformation de page a actuellement une fonctionnalité de mappage de métadonnées managées, cela pose un problème. Une solution de contournement possible consiste à remplir le champ de métadonnées managées cible avec un terme choisi ou un ensemble de termes dans le cas d’un champ de métadonnées managées à valeurs multiples. Cette opération peut être effectuée à l’aide de la DefaultTaxonomyFieldValue fonction, comme indiqué dans l’exemple ci-dessous :

<MetaData ShowPageProperties="true" PagePropertiesRow="1" PagePropertiesColumn="4" PagePropertiesOrder="1">
...
  <Field Name="TaxField2" TargetFieldName="Metadata2" Functions="DefaultTaxonomyFieldValue({TaxField2},'a65537e8-aa27-4b3a-bad6-f0f61f84b9f7|69524923-a5a0-44d1-b5ec-7f7c6d0ec160','true')" ShowInPageProperties="true"/>
...
</MetaData>

Pour plus d’informations sur la fonction, consultez Fonctions et sélecteurs de transformation de page DefaultTaxonomyFieldValue .

Je souhaite ajouter un composant WebPart supplémentaire sur la page créée

Lorsque vous transformez votre page de publication classique en page moderne, vous souhaitez parfois ajouter un composant WebPart moderne supplémentaire sur la page créée, sans qu’il y ait une version classique de ce composant WebPart sur la page de publication classique. Pour ce faire, vous pouvez ajuster vos fichiers de mappage de webpartmapping.xml et de mise en page, comme indiqué ci-dessous.

Définissez d’abord votre composant WebPart personnalisé dans votre fichier webpartmapping.xml en lui ajoutant l’élément WebParts dans le fichier, comme indiqué dans ce composant WebPart SPFX Hello World standard :

<WebParts>
  ...
  <!-- Custom Hello world web part-->
  <WebPart Type="SharePointPnP.Demo.HelloWorld" CrossSiteTransformationSupported="true">
    <Properties>
      <Property Name="HelloWorld" Type="string" />
    </Properties>
   <Mappings>
    <Mapping Default="true" Name="default">
      <ClientSideWebPart Type="Custom" ControlId="157b22d0-8006-4ec7-bf4b-ed62383fea76" Order="10" JsonControlData="&#123;&quot;serverProcessedContent&quot;:&#123;&quot;htmlStrings&quot;:&#123;&#125;,&quot;searchablePlainTexts&quot;:&#123;&#125;,&quot;imageSources&quot;:&#123;&#125;,&quot;links&quot;:&#123;&#125;&#125;,&quot;dataVersion&quot;:&quot;1.0&quot;,&quot;properties&quot;:&#123;&quot;description&quot;:&quot;{HelloWorld}&quot;,&quot;test&quot;:&quot;Multi-line text field&quot;,&quot;test1&quot;:true,&quot;test2&quot;:&quot;2&quot;,&quot;test3&quot;:true&#125;&#125;"/>
    </Mapping>
  </Mappings>
</WebPart>
  ...
</WebParts>

Si vous n’êtes pas en mesure de définir correctement votre composant WebPart personnalisé dans l’élément ClientSideWebPart ci-dessus, procédez comme suit :

  • Accédez au SharePoint Framework Workbench dans votre site (par exemple, https://contoso.sharepoint.com/sites/myportalsite/_layouts/workbench.aspx)
  • Ajouter votre composant WebPart personnalisé au workbench et le configurer si nécessaire
  • Cliquez sur le bouton « Données du composant WebPart » dans la barre d’outils, puis sur le bouton « Pages modernes »
  • Copiez la structure json WebPartData et utilisez-la pour effectuer les étapes suivantes :
    • La valeur guid ControlId est la valeur de la propriété json id
    • Supprimez les propriétés json suivantes de l’extrait de code copié : id, instanceIf, titre et description. À ce stade, il vous reste ce qui suit : {"serverProcessedContent":{"htmlStrings":{},"searchablePlainTexts":{},"imageSources":{},"links":{}},"dataVersion":"1.0","properties":{"description":"HelloWorld from Bert","test":"Multi-line text field","test1":true,"test2":"2","test3":true}}
    • Encodez cette chaîne xml, ce qui vous donnera ceci : &#123;&quot;serverProcessedContent&quot;:&#123;&quot;htmlStrings&quot;:&#123;&#125;,&quot;searchablePlainTexts&quot;:&#123;&#125;,&quot;imageSources&quot;:&#123;&#125;,&quot;links&quot;:&#123;&#125;&#125;,&quot;dataVersion&quot;:&quot;1.0&quot;,&quot;properties&quot;:&#123;&quot;description&quot;:&quot;HelloWorld from Bert&quot;,&quot;test&quot;:&quot;Multi-line text field&quot;,&quot;test1&quot;:true,&quot;test2&quot;:&quot;2&quot;,&quot;test3&quot;:true&#125;&#125;
    • Si nécessaire, insérez des paramètres de composant WebPart dans cette chaîne (par exemple, {HelloWorld} dans l’exemple ci-dessus) : &#123;&quot;serverProcessedContent&quot;:&#123;&quot;htmlStrings&quot;:&#123;&#125;,&quot;searchablePlainTexts&quot;:&#123;&#125;,&quot;imageSources&quot;:&#123;&#125;,&quot;links&quot;:&#123;&#125;&#125;,&quot;dataVersion&quot;:&quot;1.0&quot;,&quot;properties&quot;:&#123;&quot;description&quot;:&quot;{HelloWorld}&quot;,&quot;test&quot;:&quot;Multi-line text field&quot;,&quot;test1&quot;:true,&quot;test2&quot;:&quot;2&quot;,&quot;test3&quot;:true&#125;&#125;
    • Collez la chaîne résultante dans la propriété JsonControlData

Une fois que cela est en place, vous devez mettre à jour votre mappage de mise en page en ajoutant un champ dans la section WebParts qui sera transformé en ce composant WebPart personnalisé :

<WebParts>
  ...
  <!-- Add an extra web part on the page -->
  <Field Name="ID"  TargetWebPart="SharePointPnP.Demo.HelloWorld" Row="4" Column="1" Order="1">
    <Property Name="HelloWorld" Type="string" Functions="StaticString('PnP Rocks!')"/>
  </Field>
  ...
</WebParts>

Veillez à spécifier le fichier webpartmapping.xml personnalisé dans le cadre de votre transformation (-WebPartMappingFile paramètre d’applet de commande PowerShell, PublishingPageTransformator constructeur lors de l’utilisation de .Net).

J’utilise beaucoup de composants Add-In et je souhaite les transformer en composants WebPart SPFX personnalisés

Le comportement par défaut de la transformation de page est simplement prendre le contrôle du composant de complément sur la page moderne, car le complément fonctionne sur les pages modernes. Toutefois, si vous souhaitez transformer de manière sélective certains composants de complément en composants WebPart spFX personnalisés, supprimez certains composants de complément et conservez les composants de complément restants, le mappage par défaut ne sera pas suffisant. Dans l’exemple ci-dessous, vous voyez que la StaticString fonction est utilisée pour alimenter le titre du complément en tant que valeur de sélecteur de mappage. Par conséquent, en fonction du titre du composant WebPart, un mappage sera sélectionné. Le premier complément sera repris en tant que complément sur la page moderne, le second sera transformé en une alternative SPFX personnalisée et le dernier sera simplement supprimé.

Lors du mappage à un composant WebPart SPFX personnalisé, vous pouvez utiliser l’une de vos propriétés de composant de complément pour configurer l’alternative basée sur SPFX (par exemple, {HelloWorld} dans l’exemple ci-dessous), même si ces propriétés ne sont pas répertoriées dans le nœud Propriétés du fichier de mappage. Consultez également le chapitre précédent si vous souhaitez en savoir plus sur la création d’un fichier de mappage personnalisé.

<WebPart Type="Microsoft.SharePoint.WebPartPages.ClientWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" CrossSiteTransformationSupported="true">
  <!-- Note: the add-in can depend on assets that live in the source site, which is not something we can detect -->
  <Properties>
    <Property Name="FeatureId" Type="guid"/>
    <Property Name="ProductWebId" Type="guid"/>
    <Property Name="ProductId" Type="guid"/>
  </Properties>
  <Mappings Selector="StaticString({Title})">
    <Mapping Name="My Custom Report" Default="true">
      <!-- We keep this web part -->
      <ClientSideWebPart Type="ClientWebPart" Order="10" JsonControlData="{}"/>
    </Mapping>
    <Mapping Name="News Ticker" Default="false">
      <!--This web part will be transformed to a custom SPFX based web part -->
      <ClientSideWebPart Type="Custom" ControlId="157b22d0-8006-4ec7-bf4b-ed62383fea76" Order="10" JsonControlData="&#123;&quot;serverProcessedContent&quot;:&#123;&quot;htmlStrings&quot;:&#123;&#125;,&quot;searchablePlainTexts&quot;:&#123;&#125;,&quot;imageSources&quot;:&#123;&#125;,&quot;links&quot;:&#123;&#125;&#125;,&quot;dataVersion&quot;:&quot;1.0&quot;,&quot;properties&quot;:&#123;&quot;description&quot;:&quot;{HelloWorld}&quot;,&quot;test&quot;:&quot;Multi-line text field&quot;,&quot;test1&quot;:true,&quot;test2&quot;:&quot;2&quot;,&quot;test3&quot;:true&#125;&#125;"/>
    </Mapping>
    <Mapping Name="Some other add-in" Default="false">
      <!-- This add-in will not be taken over -->
    </Mapping>
  </Mappings>
</WebPart>

Vous pouvez même rendre le mappage plus précis en prenant en compte les propriétés du composant de complément en combinant les propriétés du composant de complément pour générer une chaîne de sélecteur.

<WebPart Type="Microsoft.SharePoint.WebPartPages.ClientWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" CrossSiteTransformationSupported="true">
  <!-- Note: the add-in can depend on assets that live in the source site, which is not something we can detect -->
  <Properties>
    <Property Name="FeatureId" Type="guid"/>
    <Property Name="ProductWebId" Type="guid"/>
    <Property Name="ProductId" Type="guid"/>
  </Properties>
  <Mappings Selector="ConcatenateWithPipeDelimiter({Title},{effect})">
    <Mapping Name="News Ticker|Slide" Default="true">
      <ClientSideText Text="***TEST.{Title} web part - Slide mapping chosen! Slider theme = {theme}***" Order="10" />
    </Mapping>
    <Mapping Name="News Ticker|Scroll" Default="false">
      <ClientSideText Text="***TEST.{Title} web part - Scroll mapping chosen! Slider theme = {theme}***" Order="10" />
    </Mapping>
  </Mappings>
</WebPart>

Puis-je contrôler l’image d’aperçu de la page

Lorsqu’une page a une image d’en-tête de page, cette image est également utilisée comme image d’aperçu de page. Toutefois, si vous souhaitez contrôler l’image d’aperçu de la page, vous pouvez remplir le champ à l’aide BannerImageUrl de la ToPreviewImageUrl fonction ou en spécifiant une valeur codée en dur, comme indiqué dans les exemples ci-dessous.

<!-- When you do have a publishing image field that will need to be set as preview image -->
<Field Name="PreviewImage" TargetFieldName="BannerImageUrl" Functions="ToPreviewImageUrl({PreviewImage})" />

<!-- When you do have a hard coded preview image already available on the target site. Note that the source field name (PublishingContactEmail in below sample) must exist, although it's not used here  -->
<Field Name="PublishingContactEmail" TargetFieldName="BannerImageUrl" Functions="StaticString('https://contoso.sharepoint.com/_layouts/15/getpreview.ashx?guidSite=88eebac1710b464cb6816639340fac55&amp;guidWeb=277fe40db9d24da5bbc6827714184958&amp;guidFile=91bf17fd54e849149a3ad6b4f006304e&amp;ext=jpg')" />

<!-- When you want to refer a static image living in the source site  -->
<Field Name="PreviewImage" TargetFieldName="BannerImageUrl" Functions="ToPreviewImageUrl('/sites/classicportal/images/myimage.jpg')" />

Lorsque la transformation aboutit à un composant WebPart QuickLinks moderne (par exemple, pour la transformation de SummaryLinkWebPart), l’infrastructure de transformation de page utilise une configuration de base par défaut pour le composant WebPart QuickLinks. Toutefois, si vous souhaitez une autre configuration, vous pouvez le faire en spécifiant la propriété QuickLinksJsonProperties. Encapsulez les propriétés JSON encodées dans une fonction StaticString comme indiqué dans cet exemple :

<WebParts>
  ...
  <Field Name="SummaryLinks" TargetWebPart="Microsoft.SharePoint.Publishing.WebControls.SummaryLinkWebPart, Microsoft.SharePoint.Publishing, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="1" Column="2">
    <!-- No function specified, means the content of the PublishingPageContent field will be assigned to the value of the first listed web part property -->
    <Property Name="SummaryLinkStore" Type="string" />
    <Property Name="Title" Type="string" Functions="EmptyString()"/>
    <Property Name="QuickLinksJsonProperties" Type="string" Functions="StaticString('{&quot;isMigrated&quot;: false, &quot;layoutId&quot;: &quot;Button&quot;, &quot;shouldShowThumbnail&quot;: true, &quot;buttonLayoutOptions&quot;: { &quot;showDescription&quot;: false, &quot;buttonTreatment&quot;: 1, &quot;iconPositionType&quot;: 2, &quot;textAlignmentVertical&quot;: 1, &quot;textAlignmentHorizontal&quot;: 2, &quot;linesOfText&quot;: 2}, &quot;listLayoutOptions&quot;: { &quot;showDescription&quot;: false, &quot;showIcon&quot;: true}, &quot;waffleLayoutOptions&quot;: { &quot;iconSize&quot;: 1, &quot;onlyShowThumbnail&quot;: false}, &quot;hideWebPartWhenEmpty&quot;: true}')" />
  </Field>
  ...
</WebParts>

Le code JSON de l’exemple montre toutes les options de configuration possibles que vous pouvez définir, mais vous pouvez également définir simplement celles dont vous avez besoin. Tant que le json est valide et que la structure est conservée, votre configuration QuickLinks personnalisée est récupérée.

  • Last updated on