Freigeben über

Grundlegendes und Konfigurieren des Transformationsmodells für Veröffentlichungsseiten (ab Juni 2019)

  • Artikel

Veröffentlichungsseiten basieren immer auf einem Seitenlayout und einer Gestaltungsvorlage. Diese beiden Seiten in Kombination mit Feldern, die Daten enthalten, bilden die Seite, die einem Benutzer im Browser angezeigt wird. Beim Transformieren von Veröffentlichungsseiten ist es daher obligatorisch, die verwendeten Seitenlayouts einem Veröffentlichungsseitentransformationsmodell zuzuordnen. Die Transformationskomponente für Veröffentlichungsseiten verfügt über eine "Standard"-Seitenlayoutzuordnung für alle standardmäßigen Seitenlayouts. Wenn Ihr Portal also die standardmäßigen Seitenlayouts verwendet, werden Sie behandelt. Die Realität ist, dass die meisten Portale benutzerdefinierte Seitenlayouts (und benutzerdefinierte Gestaltungsvorlagen) verwenden und daher Seitenlayoutzuordnungen für diese benutzerdefinierten Seitenlayouts erforderlich sind. Benutzerdefinierte Seitenlayouts können auf zwei Arten behandelt werden:

  • Die bevorzugte Option ist, dass Sie selbst eine benutzerdefinierte Seitenlayout-Zuordnungsdatei bereitstellen. Dadurch erhalten Sie die vollständige Kontrolle darüber, welche Felder in Webparts übersetzt werden und wo sie sich auf der modernen Seite befinden, welche Felder zu Metadaten werden und vieles mehr.
  • Wenn für die seite, die Sie transformieren, keine Seitenlayoutzuordnung gefunden wurde, generieren wir eine Zuordnung im Betrieb und verwenden diese. Der Nachteil dieses Ansatzes besteht darin, dass alle Inhalte im selben Abschnitt und in derselben Spalte der modernen Seite enden.

Generieren einer Seitenlayoutzuordnungsdatei

Wenn Sie benutzerdefinierte Seitenlayouts verwenden, empfiehlt es sich, eine benutzerdefinierte Seitenlayout-Zuordnungsdatei zu verwenden, damit Sie präzisere moderne Seiten erhalten können. Glücklicherweise müssen Sie diese benutzerdefinierten Layoutdateien nicht manuell erstellen, es gibt eine .NET-API und PnP-PowerShell-Unterstützung für die Generierung einer.

Verwendung von PowerShell

Mit dem Export-PnPPageMapping Cmdlet haben Sie folgende Möglichkeiten:

  • Exportieren Sie die integrierte Zuordnungsdatei (-BuiltInPageLayoutMapping Parameter): Diese Datei wird für die vordefinierten Seitenlayouts verwendet. Wenn Sie eine benutzerdefinierte Zuordnung für ein standardmäßiges Seitenlayout in Ihrer eigenen Zuordnungsdatei angeben, wird diese Zuordnung gegenüber der OOB-Zuordnung bevorzugt.
  • Analysieren Sie die Seitenlayouts im verbundenen Portal, und exportieren Sie diese als Zuordnungsdatei (-CustomPageLayoutMapping Parameter): Alle gefundenen benutzerdefinierten Seitenlayouts werden analysiert und exportiert. Wenn Sie auch Ihre OOB-Seitenlayouts analysieren möchten, verwenden Sie den -AnalyzeOOBPageLayouts -Parameter.
# 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

Verwenden von .NET

In .NET müssen Sie die PageLayoutAnalyser -Klasse verwenden, um Seitenlayouts zu analysieren. Die folgenden zwei Codeausschnitte zeigen, wie Sie entweder alle Seitenlayouts oder die seitenlayouts analysieren, die von bestimmten Veröffentlichungsseiten verwendet werden.

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");
}

Erläuterung des Seitenlayoutzuordnungsmodells

Wenn Sie eine Seitenlayoutzuordnungsdatei öffnen, sind die folgenden Elemente der obersten Ebene vorhanden:

  • AddOns: Als Benutzer der Seitentransformation müssen Sie möglicherweise benutzerdefinierte Logik anwenden, um Ihre Anforderungen zu erfüllen, z. B. müssen Sie eine bestimmte Eigenschaft so transformieren, dass sie mit Ihrem benutzerdefinierten SPFX-Webpart funktioniert. Das Framework unterstützt dies, indem es Ihnen ermöglicht, Ihre Assemblys mit Funktionen hinzuzufügen... Wenn Sie sie einfach im Abschnitt AddOn definieren und später auf Ihre benutzerdefinierten Funktionen verweisen, indem Sie ihnen den angegebenen Namen voranstellen, verwendet die Transformation der Veröffentlichungsseite Ihren benutzerdefinierten Code.

  • PageLayouts: Dieses Element enthält Informationen für jedes Seitenlayout, das Sie verwenden möchten. Für jedes Seitenlayout finden Sie eine Definition der Kopfzeile, des Webparts, der Metadaten, der Webpartzonen und der festen Webparts.

Weitere Informationen finden Sie in den nachfolgenden Kapiteln.

PageLayout-Definition im Seitenlayoutmodell

Analysieren wir, wie eine Seitenlayoutzuordnung im Seitenlayoutzuordnungsmodell konfiguriert wird, was am besten auf der Grundlage einer Beispieldefinition erfolgt:

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

Hinweis

Es wird empfohlen, beim Bearbeiten dieser Dateien das Pagelayoutmapping.xsd-Schema zu verwenden. Dateien, die Sie für die Seitentransformation bereitstellen, werden anhand dieses Schemas überprüft, und die Transformation schlägt fehl, wenn die bereitgestellte Seitenlayoutzuordnungsdatei ungültig ist.

PageLayout-Element

Die folgenden Eigenschaften werden für das PageLayout-Element verwendet:

  • Name: Enthält den Namen Ihres Seitenlayouts.
  • Auch GiltTo: Wenn diese Zuordnung für mehrere Seitenlayouts verwendet wird, können Sie die Namen dieser zusätzlichen Seitenlayouts als durch Semikolons getrennte Liste in diesem Attribut angeben. Die Name-Eigenschaft ist der Name des ersten Seitenlayouts, die AlsoAppliesTo enthält nur die zusätzlichen.
  • AssociatedContentType: Der Name des modernen Websiteseiteninhaltstyps, den Sie verwenden möchten. Lassen Sie dieses Feld leer, wenn Sie den Standardinhaltstyp der Websiteseite verwenden möchten.
  • PageLayoutTemplate: das zu verwendende Layoutsystem... Standardwerte, die AutoDetect in allen Fällen einwandfrei funktionieren sollten, aber optional können Sie auch ein bestimmtes Wiki-Layout auswählen.
  • IncludeVerticalColumn: Optionales Element, um anzugeben, dass die erstellte Zielseite eine vertikale Spalte aufweisen sollte. Wenn Sie eine vertikale Spalte verwenden, verwenden Sie die vertikale Spalte als zusätzliche Spalte. Wenn Sie also vor dem Hinzufügen einer vertikalen Spalte 3 Spalten hatten, verfügen Sie jetzt über 4 Spalten, und Daher können Sie den Spaltenwert des Seiteninhalts auf 4 festlegen, um ihn in der vertikalen Spalte zu platzieren.
  • PageHeader: Steuert den Typ des Seitenkopfs, der verwendet wird. Der Standardwert ist auf Custom festgelegt, da dies eine schöne Kopfzeile ermöglicht, aber Sie können ihn None für keine Kopfzeile oder Default für den modernen Standardseitenheader ändern.

SectionEmphasis-Element

Die folgenden Eigenschaften werden für das optionale SectionEmphasis-Element verwendet:

  • VerticalColumnEmphasis: Verwenden Sie diese Eigenschaft, um die vertikale Spaltenbetonung auf None, Neutral, Soft oder Strong festzulegen.

Für jeden Abschnitt können Sie optional über das Section-Element eine Abschnittsbetonung angeben:

  • Zeile: gibt die Zeilennummer dieses Abschnitts an, der erste Abschnitt hat die Zahl 1.
  • Hervorhebung: Legt die Betonung des Abschnitts auf "Keine", "Neutral", "Weich" oder "Stark" fest.

Header-Element

Die folgenden Eigenschaften werden für das Header-Element verwendet:

  • Typ: Standardmäßig FullWidthImage kann der Header das Headerbild in voller Breite anzeigen. Alternative Optionen sind ColorBlock, CutInShape und NoImage. Beachten Sie, dass dieses Attribut nur relevant ist, wenn das PageHeader-Attribut auf Customfestgelegt wurde.
  • Ausrichtung: Steuert, wie der Seitenkopfinhalt ausgerichtet wird. Der Standardwert ist Left, die alternative Option ist Center.
  • ShowPublishedDate: Definiert, ob das Datum der Seitenveröffentlichung angezeigt wird. Standardwert ist true.

Für jedes Feld, das Sie in der modernen Kopfzeile verwenden möchten, müssen Sie ein Field-Element hinzufügen, das Folgendes angibt:

  • Name: Der Name der Felder auf der klassischen Veröffentlichungsseite. Wenn Sie z. B. als Wert hinzufügen PublishingRollupImage;PublishingPageImage , bedeutet dies, dass verwendet PublishingRollupImage wird, wenn es aufgefüllt wurde, und wenn nicht aufgefüllt wird, wird versucht PublishingPageImage . Sie können beliebig viele Außerkraftsetzungen hinzufügen.
  • HeaderProperty: Der Name der festzulegenden Headereigenschaft.
  • Funktionen: Wenn auf leer festgelegt ist, wird der Feldwert von der klassischen Veröffentlichungsseite unverändert übernommen. Wenn Sie hier jedoch eine Funktion angeben, wird die Ausgabe dieser Funktion verwendet. Wenn Sie mehrere Felder angegeben haben (also die Feldüberschreibungsoption), müssen Sie das Feld angeben, das in der Funktion als verwendet werden soll. {@name}

Beim Erstellen einer modernen Seitenkopfzeile gibt es vier Seitenkopfeigenschaften, die Sie mit Daten auffüllen können, die von der Veröffentlichungsseite stammen:

  • ImageServerRelativeUrl: Wenn ihr Header ein Bild anzeigen muss, muss dieses Feld einen relativen Serverbildpfad für ein Bild definieren, das sich in derselben Websitesammlung wie die Seite befindet. Standardmäßig wird das klassische Veröffentlichungsseitenfeld PublishingRollupImage verwendet, aber da dieses ein Img-Tag enthält, wird der Feldinhalt über die ToImageUrl -Funktion bereinigt.
  • TopicHeader: Standardmäßig wird das klassische Veröffentlichungsseitenfeld ArticleByLine als Themenkopf für den modernen Seitenkopf verwendet.
  • Autoren: Wenn Sie die Autoren festlegen, können Sie den Hauptkontakt für diese Seite in der Kopfzeile der Seite anzeigen. Standardmäßig wird das klassische Veröffentlichungsseitenfeld PublishingContact verwendet, aber da es sich um ein Benutzerfeld handelt, wird der Feldinhalt über die ToAuthors -Funktion transformiert.
  • AlternativeText: Standardmäßig nicht zugeordnet, aber Sie können eine benutzerdefinierte Zuordnung hinzufügen, um die alternative Texteigenschaft des modernen Headers auszufüllen, falls gewünscht.

Wenn Sie beispielsweise keine Themenüberschrift festlegen möchten, können Sie einfach das entsprechende Field-Element entfernen oder kommentieren.

Bildoptionen für Seitenkopfzeilen

Die Standardzuordnung verwendet das im PublishingRollupImage Feld definierte Bild als Seitenkopf, aber Sie können optional ein anderes Veröffentlichungsbildfeld auswählen oder einen hartcodierten Wert eines Bilds angeben, das sich entweder am Quellstandort oder an der Zielwebsite befindet. Das folgende Beispiel zeigt einen Header mit einem statischen Bild:

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

MetaData-Element

Das Metadatenelement definiert, welche der klassischen Veröffentlichungsseitenfelder als Metadaten für die moderne Seite übernommen werden müssen. Da Sie manchmal möchten, dass die Metadaten auch mithilfe des OOB-Seiteneigenschaften-Webparts dargestellt werden sollen, geben Sie an, dass Sie über diese optionalen Attribute folgendes angeben:

  • ShowPageProperties: Wird das Seiteneigenschaften-Webpart auf der resultierenden modernen Seite hinzugefügt?
  • PagePropertiesRow: Zeile, die das Seiteneigenschaften-Webpart enthält
  • PagePropertiesColumn: Spalte, die das Seiteneigenschaften-Webpart enthält
  • PagePropertiesOrder: Die Reihenfolge des Seiteneigenschaften-Webparts in der definierten Zeile/Spalte

Für jedes Feld, das Sie übernehmen möchten, müssen Sie ein Field-Element hinzufügen, das Folgendes angibt:

  • Name: Der Name der Felder auf der klassischen Veröffentlichungsseite. Wenn Sie z. B. als Wert hinzufügen PublishingContactName;PublishingContactEmail , bedeutet dies, dass verwendet PublishingContactName wird, wenn es aufgefüllt wurde, und wenn nicht aufgefüllt wird, wird versucht PublishingContactEmail . Sie können beliebig viele Außerkraftsetzungen hinzufügen.
  • TargetFieldName: Der Name des Felds auf der modernen Zielseite
  • Funktionen: Wenn auf leer festgelegt ist, wird der Feldwert von der klassischen Veröffentlichungsseite unverändert übernommen. Wenn Sie hier jedoch eine Funktion angeben, wird die Ausgabe dieser Funktion verwendet. Wenn Sie mehrere Felder angegeben haben (also die Feldüberschreibungsoption), müssen Sie das Feld angeben, das in der Funktion als verwendet werden soll. {@name}
  • ShowInPageProperties: Wenn auf TRUE festgelegt ist und das Anzeigen des Seiteneigenschaften-Webparts aktiviert ist, wird dieses Feld im Seiteneigenschaften-Webpart angezeigt.

Hinweis

  • Die Unterstützung von Funktionen ist für Taxonomiefelder nicht verfügbar.

WebParts-Element

Jedes Feld auf der klassischen Veröffentlichungsseite, das zu einem visuellen Element auf der Zielseite werden muss (z. B. ein Webpart oder Text), muss im Webpartabschnitt definiert werden:

  • Name: Der Name des Felds auf der klassischen Veröffentlichungsseite.
  • TargetWebPart: Der Typ des Zielwebparts, das dieses Feld auf der modernen Seite visualisiert. Unterstützte Zielwebparts sind SharePointPnP.Modernization.WikiTextPart, SharePointPnP.Modernization.WikiImagePart und Microsoft.SharePoint.Publishing.WebControls.SummaryLinkWebPart, Microsoft.SharePoint.Publishing, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c.
  • Zeile: Die Zeile, in der sie das Zielwebpart einfügen möchten. Muss 1 oder höher sein.
  • Spalte: Die Spalte, in der sie das Zielwebpart einfügen möchten. Muss 1, 2 oder 3 sein.
  • Reihenfolge: Die Reihenfolge des Zielwebparts in der definierten Zeile/Spalte.

Abhängig vom ausgewählten TargetWebPart müssen Sie die Webparteigenschaften angeben, die die während der Transformation erforderlichen Daten enthalten. Jede Eigenschaft verfügt über die folgenden Eigenschaften:

  • Name: Name der Eigenschaft. Diese Eigenschaftennamen müssen mit eigenschaften übereinstimmen, die im Seitentransformationsmodell verwendet werden.
  • Typ: Typ der Eigenschaft. Diese Eigenschaftentypen müssen mit eigenschaften übereinstimmen, die im Seitentransformationsmodell verwendet werden.
  • Funktionen: Wenn der Wert auf leer festgelegt ist, ist der Eigenschaftswert der Wert des Felds auf der klassischen Quellveröffentlichungsseite. Sie können eine Funktion verwenden, um zuerst den Feldinhalt zu transformieren oder Daten aus einem anderen Feld der klassischen Veröffentlichungsseite zu verwenden.

WebPartZones-Element

Wenn das Seitenlayout Webpartzonen enthält, müssen diese hier definiert werden. Dies ist erforderlich, um transformierte Webparts auf der modernen Seite richtig zu positionieren. Folgende Eigenschaften werden verwendet:

  • ZoneId: Der Name der Zone
  • ZoneIndex: Der Index der Zone (ganze Zahl)
  • Zeile: Die Zeile, in der die in dieser Zone gehosteten Webparts eingefügt werden sollen. Muss 1 oder höher sein.
  • Spalte: Die Spalte, in der die in dieser Zone gehosteten Webparts platziert werden sollen. Muss 1, 2 oder 3 sein.
  • Reihenfolge: Reihenfolge in der definierten Zeile/Spalte für die webparts, die in dieser Zone gehostet werden

Manchmal enthalten Veröffentlichungsseiten mehrere Webparts in einer Webpartzone, und Sie möchten jedes Webpart auf der Zielseite anders positionieren. Dazu können Sie das optionale WebPartZoneLayout-Element verwenden:

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

Die obige Definition führt dazu, dass der erste ContentEditorWebPart in Zeile 3, Spalte 2, wechselt. Das zweite ContentEditorWebPart wird in Zeile 3, Spalte 1 mit Der Reihenfolge 2 eingefügt, und das erste XSLTListView-Webpart endet in Zeile 3, Spalte 1 mit Der Reihenfolge 1. Sie können beliebig viele WebPartOccurrence-Elemente definieren. Wenn kein entsprechendes Webpart in der Webpartzone vorhanden ist, wird das WebPartOccurrence-Element ignoriert. Wenn in der Webpartzone ein Webpart vorhanden ist, das nicht als WebPartOccurrence-Element aufgeführt ist, erhält dieses Webpart die Zeilen-, Spalten- und Bestellinformationen aus dem WebPartZone-Element.

FixedWebParts-Element

Manchmal enthalten Seitenlayouts "feste" Webparts. Dies sind Webparts, die innerhalb des Seitenlayouts hartcodiert sind und daher auf allen Seiten vorhanden sind, die das Seitenlayout verwenden. Da es keine API gibt, um diese "festen" Webparts zu erkennen, müssen sie als Teil des Seitenlayoutzuordnungsmodells definiert werden.

Die folgenden Eigenschaften können für ein "festes" Webpart festgelegt werden:

  • Typ: Typ des festen Webparts. Eine Liste der möglichen Typen finden Sie hier .
  • Zeile: Die Zeile, in der Sie das "feste" Webpart einfügen möchten. Muss 1 oder höher sein.
  • Spalte: Die Spalte, in der das "feste" Webpart eingefügt werden soll. Muss 1, 2 oder 3 sein.
  • Reihenfolge: Die Reihenfolge, die relevant ist, wenn mehrere Webparts vorhanden sind, die Sie in derselben Zeile und Spalte einfügen.

Für jedes "feste" Webpart müssen Sie die relevanten Eigenschaften definieren. In der Regel übernehmen Sie diese Eigenschaften, da sie in Ihrem klassischen Seitenlayout definiert sind. Für jede Eigenschaft können die folgenden Attribute festgelegt werden:

  • Eigenschaft: Name der Eigenschaft. Diese Eigenschaftennamen müssen mit eigenschaften übereinstimmen, die im Seitentransformationsmodell verwendet werden.
  • Typ: Typ der Eigenschaft. Diese Eigenschaftentypen müssen mit eigenschaften übereinstimmen, die im Seitentransformationsmodell verwendet werden.
  • Wert: Der Wert, den diese Eigenschaft hat. Vergessen Sie nicht, den Wert in XML zu codieren.

AddOns-Definition im Seitenlayoutmodell

Add-Ons ermöglichen es Ihnen, Ihre benutzerdefinierte Logik in das Seitenlayoutzuordnungsmodell einzufügen, indem Sie die folgenden 2 Schritte ausführen:

  • Erstellen einer benutzerdefinierten Assembly, die Ihre benutzerdefinierten Funktionen hosten
  • Deklarieren dieser benutzerdefinierten Assembly in den AddOns-Elementen

Erstellen Ihrer benutzerdefinierten Funktionen/Selektoren-Assembly

Um Ihre eigenen Funktionen zu erstellen, müssen Sie in Ihrem Projekt auf die SharePoint.Modernization.Framework-Assembly verweisen und dann eine Klasse erstellen, die von der SharePointPnP.Modernization.Framework.Functions.FunctionsBase-Klasse erbt:

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;
            }
        }

    }
}

Deklarieren Ihrer benutzerdefinierten Assembly

Bevor benutzerdefinierte Funktionen verwendet werden können, müssen sie im Modell deklariert werden, indem ein Verweis pro Bibliothek/Klasse zum AddOns-Element hinzugefügt wird:

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

oder (Beachten Sie den vollqualifizierten Pfad)

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

Beachten Sie, dass jede Deklaration einen Namen aufweist, im Beispiel oben ist dies „Custom“.

Verwenden Ihrer benutzerdefinierten Funktionen/Selektoren

Nachdem die Assembly definiert wurde, können Sie Ihre Funktionen und Selektoren verwenden, indem Sie mithilfe des Namens, wie dem Präfix „Custom“ im folgenden Beispiel, auf diese verweisen:

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

Häufig gestellte Fragen zur Seitenlayoutzuordnung

Ich möchte die Informationen zur Erstellung der Quellseite beibehalten.

Verwenden Sie bei Verwendung des PnP-PowerShell-Ansatzes das -KeepPageCreationModificationInformation Cmdlet im ConvertTo-PnPPage Cmdlet. Wenn Sie den .NET-Ansatz verwenden, legen Sie den KeepPageCreationModificationInformation Parameter auf true fest. Wenn Sie diese Option verwenden, erhält die Zielseite die Feldwerte Erstellt, Geändert, Autor und Editor von der Quellseite.

Hinweis

Wenn Sie im Rahmen der Seitentransformation die Seite als Neuigkeiten heraufstufen oder die Seite veröffentlichen, wird das Feld Editor auf das Konto festgelegt, das die Seitentransformation ausführt.

Ich möchte die erstellten Seiten als News bewerben

Die Höherstufung von Seiten, die aus einem Seitenlayout als Nachrichtenseiten erstellt wurden, kann mithilfe des -PostAsNews Parameters im -KeepPageCreationModificationInformation Cmdlet (bei Verwendung des PnP-PowerShell-Ansatzes) oder alternativ durch Festlegen des PostAsNews Parameters auf true (bei Verwendung des .NET-Ansatzes) erfolgen.

Wenn Sie die PostAsNews Option in Verbindung mit der KeepPageCreationModificationInformation Option verwenden, FirstPublishedDateField wird das Feld auf das Änderungsdatum der Quellseite festgelegt. Das FirstPublishedDateField Feld ist der Datumswert, der während des Newsrollups angezeigt wird.

Ich möchte hartcodierten Text auf der erstellten Seite einfügen.

Manchmal enthält ein Seitenlayout Textausschnitte, die nicht transformiert werden, da es sich nicht um Inhalte auf der eigentlichen Seite handelt. Wenn dies der Fall ist, können Sie ein "gefälschtes" Feld definieren, das wie unten dargestellt zugeordnet werden soll:

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

Hinweis

Der in der StaticString-Funktion bereitgestellte HTML-Code muss XML-codiert sein und wie der HTML-Code der Quellseite formatiert sein, da dieser HTML-Code weiterhin in HTML konvertiert wird, der mit dem modernen Text-Editor kompatibel ist.

Ich möchte den Inhalt des Felds präfixieren oder suffixieren

Der im vorherigen Kapitel verwendete Ansatz ermöglicht es Ihnen, zusätzlichen Text auf einer Seite hinzuzufügen, hat aber den Nachteil, dass der zusätzliche Text im eigenen Textteil hinzugefügt wird. Wenn Sie möchten, dass der zusätzliche Text in den tatsächlich transformierten Text integriert wird, können Sie dies mit dem folgenden Ansatz tun. Sie können vorhandene Feldinhalte entweder präfixieren und/oder suffixieren, und optional können Sie die Präfix-/Suffixierung nur durchführen lassen, wenn das Feld Inhalt enthält. Der bool-Parameter in den PrefixFunktionen , Suffix und PrefixAndSuffix definiert, ob die Präfix-/Suffixierung erfolgen muss, wenn der Feldinhalt leer ist: "true" bedeutet, dass die Aktion angewendet wird, auch wenn das Feld leer ist.

Weitere Informationen zu den folgenden Funktionen finden Sie unter Seitentransformationsfunktionen und Selektoren .

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

Ich möchte ein verwaltetes Metadatenfeld mit einem oder mehreren Begriffen auffüllen.

Wenn Sie über ein verwaltetes Metadatenfeld in den Metadaten der Quellseite verfügen, sollten Sie ein ähnliches feld für verwaltete Metadaten für die Zielseite verwenden. Wenn die Seitentransformation derzeit über eine verwaltete Metadatenzuordnungsfunktion verfügt, stellt dies ein Problem dar. Eine mögliche Problemumgehung besteht darin, das Verwaltete Metadatenfeld des Ziels mit einem ausgewählten Ausdruck oder einer Reihe von Begriffen aufzufüllen, wenn es sich um ein mehrwertiges verwaltetes Metadatenfeld handelt. Dies kann mithilfe der DefaultTaxonomyFieldValue -Funktion erfolgen, wie im folgenden Beispiel gezeigt:

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

Weitere Informationen zur Funktion finden Sie unter DefaultTaxonomyFieldValueSeitentransformationsfunktionen und Selektoren.

Ich möchte der erstellten Seite ein zusätzliches Webpart hinzufügen.

Wenn Sie Ihre klassische Veröffentlichungsseite in eine moderne Seite umwandeln, möchten Sie manchmal auf der erstellten Seite ein zusätzliches modernes Webpart hinzufügen, ohne dass auf der klassischen Veröffentlichungsseite eine klassische Version dieses Webparts vorhanden ist. Dies kann durch Anpassen der webpartmapping.xml- und Seitenlayoutzuordnungsdateien wie unten gezeigt erfolgen.

Definieren Sie zunächst Ihr benutzerdefiniertes Webpart in Ihrer webpartmapping.xml-Datei , indem Sie es dem WebParts -Element in der Datei hinzufügen, wie in diesem SPFX-Standardwebpart Hallo Welt gezeigt:

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

Wenn Sie ihr benutzerdefiniertes Webpart im obigen ClientSideWebPart-Element nicht richtig definieren, führen Sie die folgenden Schritte aus:

  • Navigieren Sie zur SharePoint-Framework Workbench auf Ihrer Website (z. B. https://contoso.sharepoint.com/sites/myportalsite/_layouts/workbench.aspx).
  • Fügen Sie Ihr benutzerdefiniertes Webpart zur Workbench hinzu, und konfigurieren Sie es bei Bedarf.
  • Klicken Sie auf die Schaltfläche "Webpartdaten" in der Symbolleiste und dann auf die Schaltfläche "Moderne Seiten".
  • Kopieren Sie die JSON-Struktur WebPartData , und verwenden Sie sie, um die nächsten Schritte auszuführen:
    • Der ControlId-GUID-Wert ist der Wert der json-Eigenschaft id.
    • Löschen Sie die folgenden JSON-Eigenschaften aus dem kopierten Codeausschnitt: id, instanceIf, title und description. An diesem Punkt haben Sie folgendes übrig: {"serverProcessedContent":{"htmlStrings":{},"searchablePlainTexts":{},"imageSources":{},"links":{}},"dataVersion":"1.0","properties":{"description":"HelloWorld from Bert","test":"Multi-line text field","test1":true,"test2":"2","test3":true}}
    • Xml codieren Sie diese Zeichenfolge. Dadurch erhalten Sie Folgendes: &#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;
    • Fügen Sie bei Bedarf Webpartparameter in diese Zeichenfolge ein (z. B. {HelloWorld} im obigen Beispiel): &#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;
    • Fügen Sie die resultierende Zeichenfolge in die JsonControlData-Eigenschaft ein.

Sobald dies eingerichtet ist, müssen Sie ihre Seitenlayoutzuordnung aktualisieren, indem Sie im Abschnitt WebParts ein Feld hinzufügen, das in dieses benutzerdefinierte Webpart transformiert wird:

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

Stellen Sie sicher, dass Sie die benutzerdefinierte webpartmapping.xml-Datei als Teil der Transformation angeben (-WebPartMappingFile PowerShell-Cmdlet-Parameter, PublishingPageTransformator Konstruktor bei Verwendung von .NET).

Ich verwende viele Add-In Teile und möchte diese in benutzerdefinierte SPFX-Webparts transformieren.

Das Standardverhalten der Seitentransformation besteht darin, das Add-In-Part auf der modernen Seite zu übernehmen, während das Add-In auf modernen Seiten funktioniert. Wenn Sie jedoch einige Add-In-Teile selektiv in benutzerdefinierte SPFX-basierte Webparts transformieren möchten, einige Add-In-Teile löschen und die verbleibenden Add-In-Teile beibehalten möchten, reicht die Standardzuordnung nicht aus. Im folgenden Beispiel sehen Sie, dass die StaticString -Funktion verwendet wird, um den Add-In-Titel als Zuordnungsauswahlwert zu feeden. Basierend auf dem Titel des Webparts wird also eine Zuordnung ausgewählt. Das erste Add-In wird als Add-In auf der modernen Seite übernommen, das zweite wird in eine benutzerdefinierte SPFX-basierte Alternative transformiert, und das letzte add-in wird einfach gelöscht.

Bei der Zuordnung zu einem benutzerdefinierten SPFX-basierten Webpart können Sie eine Ihrer Add-In-Part-Eigenschaften verwenden, um die SPFX-basierte Alternative zu konfigurieren (z. B. {HelloWorld} im folgenden Beispiel), auch wenn diese Eigenschaften nicht im Knoten Eigenschaften in der Zuordnungsdatei aufgeführt sind. Weitere Informationen zum Erstellen einer benutzerdefinierten Zuordnungsdatei finden Sie auch im vorherigen Kapitel.

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

Sie können die Zuordnung sogar präziser gestalten, indem Sie Add-In-Part-Eigenschaften berücksichtigen, indem Sie die Add-In-Part-Eigenschaften kombinieren, um eine Selektorzeichenfolge zu generieren.

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

Kann ich das Seitenvorschaubild steuern?

Wenn eine Seite über ein Seitenkopfbild verfügt, wird dieses Bild auch als Seitenvorschaubild verwendet. Wenn Sie jedoch das Seitenvorschaubild steuern möchten, können Sie das BannerImageUrl Feld entweder mithilfe der ToPreviewImageUrl Funktion oder durch Angeben eines hartcodierten Werts auffüllen, wie in den folgenden Beispielen gezeigt.

<!-- 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')" />

Wenn die Transformation zu einem modernen QuickLinks-Webpart führt (z. B. für die Transformation von SummaryLinkWebPart), verwendet das Seitentransformationsframework eine Standardbasiskonfiguration für das QuickLinks-Webpart. Wenn Sie jedoch eine andere Konfiguration wünschen, können Sie dies tun, indem Sie die QuickLinksJsonProperties-Eigenschaft angeben. Umschließen Sie die codierten JSON-Eigenschaften in einer StaticString-Funktion, wie in diesem Beispiel gezeigt:

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

Der JSON-Code im Beispiel zeigt alle möglichen Konfigurationsoptionen, die Sie festlegen können, aber Sie können auch nur die erforderlichen definieren. Solange der JSON-Code gültig ist und die Struktur beibehalten wird, wird Ihre benutzerdefinierte QuickLinks-Konfiguration verwendet.