Comprendre et configurer le modèle de transformation de page de publication (à partir de la version de juin 2019)

Les pages de publication sont toujours basées sur une mise en page et une page maître. Ces deux pages combinées avec des champs contenant des données sont la page qu’un utilisateur voit dans le navigateur. Lors de la transformation de pages de publication, il est obligatoire de ma map 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êts à l’aide. Ainsi, si votre portail utilise ces mises en page prêts à l’aide, vous êtes couvert. En réalité, la plupart des portails utilisent des mises en page personnalisées (et des pages maîtres personnalisées) et qu’il est donc nécessaire d’utiliser des 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 privilégiée consiste à fournir un fichier de mappage de mise en page personnalisé, ce qui vous donne un contrôle total sur les champs convertis en composants Web Part et sur l’endroit où ils résident sur la page moderne, sur les champs qui deviennent des métadonnées et bien plus encore.
  • S’il n’existe aucun mappage de mise en page 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 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 personnaliser ces fichiers de disposition personnalisés, il existe une API .Net et une prise en charge PnP PowerShell pour en générer un.

Utiliser PowerShell

À Export-PnPPageMapping l’aide de la cmdlet, vous pouvez :

  • Exportez le fichier de mappage intégré (paramètre) : ce fichier sera utilisé pour les mises en -BuiltInPageLayoutMapping page standard. Si vous spécifiez un mappage personnalisé pour une mise en page standard dans votre propre fichier de mappage, ce mappage sera préféré au mappage OOB.
  • Analysez les mises en page dans le portail connecté et exportons-les en tant que fichier de mappage (paramètre) : toutes les mises en page personnalisées trouvées sont analysées et -CustomPageLayoutMapping 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 classe PageLayoutAnalyser pour analyser les mises en page. Les 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");
}

Présentation 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 devrez peut-être 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 partie Web SPFX personnalisée. L’infrastructure prend cela en charge en vous permettant d’ajouter vos assemblys avec des fonctions... Si vous les définissez simplement dans la section AddOn, puis que vous référencez vos fonctions personnalisées ultérieurement en les faisant précéder du nom donné, la transformation de page de publication utilisera 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 Web Part, des métadonnées, des zones de composants Web Part et des composants Web Parts fixes.

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

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

Nous allons analyser la façon dont 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>

Notes

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 seront validés par rapport à ce schéma et la transformation échouera 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 :

  • Name: contient le nom de votre mise en page.
  • AlsoAppliesTo: lorsque ce mappage sera utilisé pour plusieurs mises en page, vous pouvez spécifier les noms de ces mises en page supplémentaires en tant que 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 uniquement les autres.
  • AssociatedContentType: nom du type de contenu de page de site moderne que vous souhaitez utiliser. Laissez ce paramètre 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, ce qui devrait fonctionner correctement dans tous les cas, mais vous pouvez également choisir une disposition AutoDetect wiki spécifique.
  • IncludeVerticalColumn: élément facultatif pour spécifier 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. Ainsi, si vous avez 3 colonnes avant d’ajouter une colonne verticale, vous en aurez 4 et, en tant que tel, 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é. Par défaut, comme cela autorise un en-tête agréable, mais vous pouvez le basculer vers aucun en-tête ou pour l’en-tête de page moderne Custom None par Default défaut.

Élément SectionEmphasis

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

  • 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 une accentuation de 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
  • Emphasis: 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: permet par défaut FullWidthImage à l’en-tête d’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 été définie sur Custom .
  • Alignement: contrôle la façon dont le contenu de l’en-tête de page est aligné. La valeur par Left défaut est , l’option alternative 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 :

  • Name: nom du(s) champ(s) dans la page de publication classique. Par exemple, l’ajout en tant que valeur signifie que le sera pris s’il a été rempli, s’il n’est pas rempli, PublishingRollupImage;PublishingPageImage PublishingRollupImage le sera PublishingPageImage 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 (à l’aide de l’option de remplacement de champ), vous devez spécifier le champ à utiliser dans la fonction comme {@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 des données provenant de la page de publication :

  • ImageServerRelativeUrl: si votre en-tête doit afficher une image, ce champ devra définir un chemin d’image relatif de serveur pour une image qui se trouverait dans la même collection de sites que la page. Par défaut, le champ de page de publication classique est utilisé, mais étant donné que celui-ci contient une balise Img, le contenu du champ est nettoyé PublishingRollupImage via la ToImageUrl fonction.
  • TopicHeader : par défaut, le champ de page de publication classique est utilisé comme en-tête de rubrique ArticleByLine pour l’en-tête de page moderne
  • Auteurs: la définition des auteurs vous permet d’afficher le contact principal de cette page dans l’en-tête de page. Par défaut, le champ de page de publication classique est utilisé, mais étant donné PublishingContact qu’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 de remplacement d’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 respectif.

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

Le mappage par défaut prend l’image définie dans le champ en tant qu’en-tête de page, mais vous pouvez éventuellement sélectionner un autre champ d’image de publication ou spécifier une valeur codée en dur d’une image résidant sur le site source ou le PublishingRollupImage 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 quels champs de page de publication classiques doivent être repris en tant que métadonnées pour la page moderne. Comme vous souhaitez parfois que les métadonnées soient également représentées à l’aide du partie Web Propriétés de page OOB, vous indiquez que via ces attributs facultatifs :

  • ShowPageProperties: le partie Web Des propriétés de page sera-t-elle ajoutée sur la page moderne résultante
  • PagePropertiesRow: ligne qui contenira le partie Web De propriétés de page
  • PagePropertiesColumn: colonne qui va contenir le partie Web De propriétés de page
  • PagePropertiesOrder : ordre du partie Web Des propriétés de page dans la ligne/colonne définie

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

  • Name: nom du(s) champ(s) dans la page de publication classique. Par exemple, l’ajout en tant que valeur signifie que le sera pris s’il a été rempli, s’il n’est pas rempli, PublishingContactName;PublishingContactEmail PublishingContactName le sera PublishingContactEmail 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 (à l’aide de l’option de remplacement de champ), vous devez spécifier le champ à utiliser dans la fonction comme {@name}
  • ShowInPageProperties: si la valeur true et si l’affichage du partie Web De propriétés de page a été désactivé que ce champ est affiché dans le partie Web De propriétés de page

Notes

  • La prise en charge des fonctions 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 Web Part ou un texte) doit être défini dans la section des composants Web Parts :

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

En fonction du TargetWebPart choisi, vous devez fournir les propriétés du site WebPart qui tiennent compte des données nécessaires pendant la transformation. Chaque propriété possède les propriétés suivantes :

  • Name: Nom de la propriété. Ces noms de propriété 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é sera la valeur du champ dans la page de publication classique source. Vous pouvez utiliser une fonction pour transformer d’abord 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 partie Web, celles-ci doivent être définies ici. Cela est nécessaire pour positionner correctement les composants Web Parts transformés sur la page moderne. Les propriétés suivantes sont utilisées :

  • ZoneId: nom de la zone
  • ZoneIndex: index de la zone (nombre integer)
  • Ligne: ligne dans quelle ligne vous souhaitez placer les composants Web Parts hébergés dans cette zone. Doit être supérieur ou supérieur à 1.
  • Colonne: colonne dans qui vous souhaitez placer les composants Web Parts hébergés dans cette zone. Doit être 1, 2 ou 3.
  • Order: order in the defined row/column for the web parts hosted in this zone

Parfois, les pages de publication ont plusieurs composants Web Part dans une zone de composants Web Part et vous souhaitez positionner chaque composant Web Part 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 a pour conséquence que le premier ContentEditorWebPart passe à la ligne 3, colonne 2. Le deuxième ContentEditorWebPart est placé à la ligne 3, colonne 1 dans l’ordre 2 et le premier élément WebPart XSLTListView se retrouve à la ligne 3, colonne 1 avec l’ordre 1. Vous pouvez définir autant d’éléments WebPartOccurrence que nécessaire, s’il n’y a pas de partie WebPart correspondante dans la zone de webpart, l’élément WebPartOccurrence sera ignoré. S’il existe un élément WebPart dans la zone de parties WebPart qui n’est pas répertorié en tant qu’élément WebPartOccurrence, ce dernier reçoit 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 Web Parts « fixes », qui sont codés en dur dans 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 Web Parts « 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 partie Web « fixe » :

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

Pour chaque partie Web « fixe », vous devez définir les propriétés pertinentes. En règle générale, vous prenez le contrôle de 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éfinies :

  • Propriété: nom de la propriété. Ces noms de propriété 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.
  • Value: la valeur de cette propriété. N’oubliez pas d’encoder la valeur au XML.

Définition des addOns dans le modèle de mise en page

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

  • 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 la page source

Lorsque vous utilisez l’approche PowerShell PnP, utilisez la -KeepPageCreationModificationInformation cmdlet dans la ConvertTo-PnPClientSidePage cmdlet. Lorsque vous utilisez l’approche .Net, définissez le KeepPageCreationModificationInformation paramètre sur true. L’utilisation de cette option donne à la page cible les valeurs de champ Créé, Modifié, Auteur et Éditeur de la page source.

Notes

Lorsque vous, dans le cadre de la transformation de page, faites la promotion de la page en tant qu’actualités ou publiez la page, le champ Éditeur est définie sur le compte exécutant la transformation de page

Je souhaite 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 paramètre sur -PostAsNews -KeepPageCreationModificationInformation l’cmdlet (lorsque vous utilisez l’approche PowerShell PnP)ou en paramétrez le paramètre sur true (lorsque vous utilisez PostAsNews l’approche .Net).

Lorsque vous utilisez PostAsNews l’option conjointement avec l’option, le champ est alors définie sur KeepPageCreationModificationInformation la date de modification de la page FirstPublishedDateField source. Le FirstPublishedDateField champ est la valeur de date affichée pendant le déploiement 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 ne sont pas du contenu de la page réelle et ne sont pas transformés. Si tel est le cas, vous pouvez définir un champ « factice » à maquer 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>

Notes

Le code HTML fourni dans la fonction StaticString doit être codé au format XML et doit être formaté comme le code HTML de la page source, car ce code HTML sera toujours converti au format HTML conforme à l’éditeur de texte moderne.

Je veux préfixer ou suffixer 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 suffixer le contenu de champ existant et éventuellement uniquement le préfixe/suffixe lorsque le champ contient du contenu. Le paramètre bool dans le , et les fonctions définit si le Prefix Suffix préfixe/suffixe doit se produire lorsque le contenu du champ est vide : « true » signifie appliquer l’action même lorsque le champ est PrefixAndSuffix vide.

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

<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 gérées avec un ou plusieurs termes

Lorsque vous avez un champ de métadonnées gérées dans les métadonnées de la page source, vous pouvez avoir un champ de métadonnées gérées similaire pour la page cible. La transformation de page donnée dispose actuellement d’une fonctionnalité de mappage de métadonnées gérées qui pose un problème. Une solution de contournement possible consiste à remplir le champ de métadonnées gérées cible avec un terme choisi ou un ensemble de termes en cas de champ de métadonnées gérées à valeurs multiples. Pour ce faire, utilisez la DefaultTaxonomyFieldValue fonction comme illustré 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, voir Fonctions et sélecteurs de transformation de DefaultTaxonomyFieldValue page.

Je souhaite ajouter un élément Web Part supplémentaire sur la page créée

Lorsque vous transformez votre page de publication classique en une page moderne, vous souhaitez parfois ajouter un autre partie Web Moderne sur la page créée, sans qu’il existe une version classique de ce dernier sur la page de publication classique. Pour ce faire, ajustez vos fichiers webpartmapping.xml et de mappage de mise en page, comme illustré ci-dessous.

Tout d’abord, définissez votre élément Web Part personnalisé dans votre fichierwebpartmapping.xml en lui ajoutant l’élément dans le fichier comme indiqué dans ce fichier Web Part Hello WebParts World SPFX 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 ne définissez pas correctement votre partie WebPart personnalisée dans l’élément ClientSideWebPart ci-dessus, suivez les étapes suivantes :

  • Accédez au SharePoint Framework Workbench dans votre site (par exemple,https://contoso.sharepoint.com/sites/myportalsite/_layouts/workbench.aspx)
  • Ajouter votre élément Web Part personnalisé au workbench et le configurer en cas de besoin
  • Cliquez sur le bouton « Données de partie Web » 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 les points suivants : {"serverProcessedContent":{"htmlStrings":{},"searchablePlainTexts":{},"imageSources":{},"links":{}},"dataVersion":"1.0","properties":{"description":"HelloWorld from Bert","test":"Multi-line text field","test1":true,"test2":"2","test3":true}}
    • Le code XML de cette chaîne vous donnera les informations ci-après : &#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 partie Web 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;
    • Coller la chaîne résultante dans la propriété JsonControlData

Une fois celui-ci 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 partie WebPart personnalisée :

<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 (paramètre de -WebPartMappingFile l’cmdlet PowerShell, constructeur lors de l’utilisation PublishingPageTransformator de .Net).

J’utilise un grand nombre de composants Web Add-In et je souhaite les transformer en composants Web Parts SPFX personnalisés.

Le comportement par défaut de la transformation de page est simplement de prendre le contrôle du partie de module sur la page moderne, car le module de recherche de ce dernier fonctionne sur des pages modernes. Toutefois, si vous souhaitez transformer de manière sélective certains composants de composants de recherche en composants Web Parts personnalisés basés sur SPFX, déposez certains des composants de module de recherche et conservez les autres composants, le mappage par défaut ne sera pas suffisant. Dans l’exemple ci-dessous, vous voyez que la fonction est utilisée pour alimenter le titre du add-in en tant que valeur de StaticString sélecteur de mappage. Ainsi, en fonction du titre du partie Web, un mappage est sélectionné. Le premier add-in sera pris en charge en tant que add-in sur la page moderne, le second sera transformé en une alternative SPFX personnalisée et le dernier sera simplement supprimé.

Lorsque vous mappage vers un élément Web Part personnalisé basé sur SPFX, vous pouvez utiliser n’importe quelle propriété de votre module de développement logiciel (SPFX) 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 de la partie de l’application en combinant les propriétés de ce dernier 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 page

Lorsqu’une page possède une image d’en-tête de page, cette image sera également utilisée comme image d’aperçu de page. Si vous souhaitez toutefois contrôler l’image d’aperçu de page, vous pouvez remplir le champ à l’aide de la fonction ou en spécifiant une valeur codée en dur comme illustré dans les BannerImageUrl ToPreviewImageUrl 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 se traduit par un élément 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 partie WebPart QuickLinks. Toutefois, si vous souhaitez une configuration différente, vous pouvez le faire en spécifiant la propriété QuickLinksJsonProperties. Encapsulez les propriétés JSON codées dans une fonction StaticString, comme illustré 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 JSON de l’exemple montre toutes les options de configuration possibles que vous pouvez définir, mais vous pouvez également simplement définir ceux dont vous avez besoin. Tant que le JSON est valide et que la structure est maintenue, votre configuration QuickLinks personnalisée sera choisie.