Verstehen und Konfigurieren des Seitentransformationsmodells
Das Herzstück der Seitentransformationslösung ist das Modell, das die Transformation speist: Das Modell teilt der Engine mit, welche Webparteigenschaften wichtig sind, ermöglicht es Ihnen, diese Eigenschaften zu bearbeiten und dynamisch eine Zuordnung für Ihr Webpart auszuwählen. Das Seitentransformationsmodell wird in XML ausgedrückt und enthält ein Schema, das verwendet wird, um die Richtigkeit des Modells zu überprüfen.
Wichtig
SharePoint PnP Modernization ist ein Bestandteil des PnP-Framework und wird ständig weiterentwickelt. Sehen Sie sich die Versionshinweise an, um bezüglich der aktuellsten Änderungen auf dem neuesten Stand zu bleiben. Wenn Sie Probleme feststellen, öffnen Sie bitte ein Ticket in der GitHub-Problemliste im PnP-Framework.
Seitentransformation hochgradige Architektur
In der folgenden Abbildung wird die Seitentransformation in vier Schritten erläutert:
- Zu Beginn müssen Sie dem Transformationsmodul mitteilen, wie die Seiten umgewandelt werden sollen. Dies erfolgt durch die Bereitstellung eines Seitentransformationsmodells. Bei diesem Modell handelt es sich um eine XML-Datei, die beschreibt, wie jedes klassische Webpart einem entsprechenden modernen Webpart zugeordnet wird. Das Modell enthält pro klassisches Webpart eine Liste der relevanten Eigenschaften und Zuordnungsinformationen. Weitere Informationen finden Sie im Artikel Verstehen und Konfigurieren des Seitentransformationsmodells. Wenn Sie erfahren möchten, wie sich klassische Webparts von modernen Webparts unterscheiden, lesen Sie den Artikel Erfahrungen mit klassischen und modernen Webparts.
- Im nächsten Schritt wird die Seite analysiert, die Sie umwandeln: Das Transformationsmodul teilt die Seite in eine Sammlung von Webparts auf (Wiki-Text wird in ein oder mehrere Wiki-Textwebparts aufgeteilt) und versucht, das verwendete Layout zu bestimmen.
- Die aus der Analyse in Schritt 2 abgerufenen Informationen reichen häufig jedoch nicht für die Zuordnung des Webparts zu einem modernen Webpart aus. Daher werden diese Informationen in Schritt 3 durch Aufrufen von Funktionen erweitert: Diese Funktionen verwenden die in Schritt 2 abgerufenen Eigenschaften und generieren auf Grundlage der eingegebenen Eigenschaften in Schritt 2 neue Eigenschaften. Nach Schritt 3 haben wir alle erforderlichen Informationen zum Zuordnen des Webparts... außer wir müssen optional den definierten Selektor aufrufen, um zu verstehen, welche Zuordnung wir benötigen, falls ein klassisches Webpart mehreren modernen Konfigurationen zugeordnet werden kann.
- Der letzte Schritt besteht darin, die moderne Seite zu erstellen und zu konfigurieren, gefolgt von dem Hinzufügen der zugeordneten modernen Webparts.
Modellstruktur der Seitentransformation
Beim Öffnen des Seitentransformationsmodells sind die folgenden Elemente der obersten Ebene vorhanden:
BaseWebPart: Dieses Element enthält die Konfiguration, die für alle Webparts gilt, es definiert z. B., dass die Eigenschaft „Title“ für alle Webparts abgerufen wird. Es ist auch der Ort, an dem die Standard-Webpartzuordnung definiert wird: Wenn für ein Webpart keine Zuordnung definiert ist, wird die Engine auf diese Zuordnung zurückgreifen, um das Webpart auf der Zielseite darzustellen.
AddOns: Als Benutzer der Seitentransformation mussten 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 und Selektoren hinzuzufügen...Siekönnen diese einfach im AddOn-Abschnitt definieren und dann auf Ihre benutzerdefinierten Funktionen und Selektoren verweisen, indem diesen das Präfix mit dem Namen vorangestellt wird. Auf diese Weise verwendet die Seitentransformation Ihren benutzerdefinierten Code.
WebParts: Dieses Element enthält Informationen für jedes Webpart, das Sie umwandeln möchten. Für jedes Webpart gibt es eine Definition der zu verwendenden Eigenschaften, der für diese Eigenschaften auszuführenden Funktionen, der möglichen Zuordnungen, die das Ziel der Transformation in Verbindung mit einem Selektor definieren, der dynamisch die erforderliche Zuordnung auswählt.
Weitere Informationen finden Sie in den nachfolgenden Kapiteln.
WebPart-Definition im Seitentransformationsmodell
Im Folgenden wird die Konfiguration eines Webparts im Seitentransformationsmodell erläutert. Dies erfolgt anhand eines vereinfachten Beispiels einer XsltListViewWebPart-Definition:
<!-- XsltListView web part -->
<WebPart Type="Microsoft.SharePoint.WebPartPages.XsltListViewWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c">
<Properties>
<Property Name="XmlDefinitionLink" Type="string" />
<Property Name="ListUrl" Type="string" />
<Property Name="ListId" Type="guid" Functions="{ListWebRelativeUrl} = ListAddWebRelativeUrl({ListId}); {ListServerRelativeUrl} = ListAddServerRelativeUrl({ListId})"/>
<Property Name="Direction" Type="string"/>
<Property Name="GhostedXslLink" Type="string" />
<Property Name="DisableViewSelectorMenu" Type="bool"/>
<Property Name="XmlDefinition" Type="string" Functions="{ListViewId} = ListDetectUsedView({ListId},{XmlDefinition})"/>
<Property Name="SelectParameters" Type="string"/>
</Properties>
<!-- This selector outputs: Library, List -->
<Mappings Selector="ListSelectorListLibrary({ListId})">
<Mapping Name="List" Default="true">
<ClientSideText Text="You can map a source web part ({Title}) to a combination of modern web parts :-)" Order="10" />
<ClientSideWebPart Type="List" Order="20" JsonControlData="{"serverProcessedContent":{"htmlStrings":{},"searchablePlainTexts":{},"imageSources":{},"links":{}},"dataVersion":"1.0","properties":{"isDocumentLibrary":false,"selectedListId":"{ListId}","listTitle":"{Title}","selectedListUrl":"{ListServerRelativeUrl}","webRelativeListUrl":"{ListWebRelativeUrl}","webpartHeightKey":4,"selectedViewId":"{ListViewId}"}}" />
</Mapping>
<Mapping Name="Library" Default="false">
<ClientSideWebPart Type="List" Order="10" JsonControlData="{"serverProcessedContent":{"htmlStrings":{},"searchablePlainTexts":{},"imageSources":{},"links":{}},"dataVersion":"1.0","properties":{"isDocumentLibrary":true,"selectedListId":"{ListId}","listTitle":"{Title}","selectedListUrl":"{ListServerRelativeUrl}","webRelativeListUrl":"{ListWebRelativeUrl}","webpartHeightKey":4,"selectedViewId":"{ListViewId}"}}" />
</Mapping>
</Mappings>
</WebPart>
Properties-Element
Für jedes Webpart definiert das Modell die Eigenschaften, die nützlich sein können, um die modernen Zielwebparts zu konfigurieren. Wenn bestimmte Eigenschaften fehlen, können Sie das Modell entsprechend erweitern. Für einige der Eigenschaften wird ein Functions-Attribut angezeigt: Dieses Attribut enthält eine oder mehrere Funktionen (separate Funktionen über eine ;) die ausgeführt werden, wenn das Quellwebpart einem modernen Zielwebpart zugeordnet wird. Der Aufbau einer Funktion sieht wie folgt aus:
{Output} = FunctionName({Input1}, {Input2})
Eine Funktion kann eine oder mehrere Eingabewerte aufweisen, welche Folgendes sein können:
- In diesem Webpart definierte Eigenschaften (z. B. {ListId})
- In diesem Basiswebpart definierte Eigenschaften (z. B. {Title})
- Eigenschaften, die die Ausgabe der Ausführung vorheriger Funktionen waren (z. B. {ListWebRelativeUrl})
- Die für die Website gültige Standardeigenschaften: {Host}, {Web}, {Site}, {WebId}, {SiteId}
Wenn eine Funktion ausgeführt wird, wird ihre Ausgabe wie folgt aussehen:
- Ein einzelner Zeichenfolgenwert: Dieser Wert ({Output} im vorgestellten Modell) wird der Liste der Webparteigenschaften mit dem Namen „Output“ und dem Wert hinzugefügt, der beim Ausführen von
FunctionNamezurückgegeben wurde. - Eine Liste von Schlüssel-Wert-Paaren (Wörterbuchzeichenfolge,Zeichenfolge<>): In diesem Fall wird jedes zurückgegebene Schlüssel-Wert-Paar der Liste der Webparteigenschaften hinzugefügt.
Wenn die Funktion nicht den Ausgabeparameter definiert, wird der Wert der Webparteigenschaft, der die Funktion definiert, mit dem Ergebnis der Funktion überschrieben.
Schauen wir uns das anhand eines Beispiels an:
<Property Name="ListId" Type="guid" Functions="FormatGuid({ListId})"/>
Annahme: die Webparteigenschaft enthält ursprünglich eine GUID, die wie folgt formatiert ist: {AAFAD7D0-D57A-4BB1-8706-969A608C686B}. Nachdem FormatGuid ausgeführt wurde, wird der Wert auf die Ausgabe von FormatGuid festgelegt (z. B. eine GUID ohne Klammern AAFAD7D0-D57A-4BB1-8706-969A608C686B).
Wenn eine Funktion mehrere Werte zurückgibt, überschreibt jedes zurückgegebene Schlüssel-Wert-Paar, das bereits als Webparteigenschaft vorhanden ist, diesen Eigenschaftswert.
Hinweis
Alle sofort einsatzbereiten Funktionen werden in Funktionen und Selektoren für die Seitentransformation beschrieben.
Mappings-Element
Dieses Element definiert eine oder mehrere mögliche Zielkonfigurationen für das Quellwebpart. Da Sie mehrere Ziele definieren können, muss ein Mechanismus vorhanden sein, mit dem die zu verwendende Zuordnung bestimmt werden kann:
- Wenn das Mapping-Element ein aufgefülltes Selector-Attribut enthält, wird die Ausgabe der Selektorausführung für die Suche nach der richtigen Zuordnung nach Namen verwendet (Beispiel: die Selektorfunktion
ListSelectorListLibrarygibt die Zeichenfolge „Library“ zurück, was bedeutet, dass die Zuordnung mit dem Namen „Library“ verwendet wird). Selektoren können mit Funktionen gleichgesetzt werden, die einen einzelnen Wert zurückgeben. Sie können somit ein beliebiges Webpartattribut als Eingabe für Ihre Selektorfunktion angeben. - Wenn nur eine Zuordnung vorhanden ist, wird diese verwendet, wenn kein Selektorergebnis vorhanden war.
- Wenn kein Selektorergebnis vorhanden ist und mehrere Zuordnungen definiert sind, wird die als Standard gekennzeichnete Zuordnung verwendet.
Hinweis
Alle sofort einsatzbereiten Selektoren werden in Funktionen und Selektoren für die Seitentransformation beschrieben.
Als Nächstes wird das Mapping-Element erläutert.
Mapping-Element
Innerhalb eines Mapping-Elements können Sie ein oder mehrere ClientSideText- oder ClientSideWebPart-Elemente haben, wie im folgenden Codeausschnitt gezeigt. Beachten Sie, dass Sie Funktionen für eine Zuordnung ausführen können. Dies ist praktisch, wenn Sie die Verarbeitung nur durchführen möchten, wenn eine bestimmte Zuordnung ausgewählt wurde.
<Mapping Name="List" Default="true" Functions="{SampleVariable} = SampleFunction({ListId})>
<ClientSideText Text="You can map a source web part ({Title}) to a combination of modern web parts :-)" Order="10" />
<ClientSideWebPart Type="List" Order="20" JsonControlData="{"serverProcessedContent":{"htmlStrings":{},"searchablePlainTexts":{},"imageSources":{},"links":{}},"dataVersion":"1.0","properties":{"isDocumentLibrary":false,"selectedListId":"{ListId}","listTitle":"{Title}","selectedListUrl":"{ListServerRelativeUrl}","webRelativeListUrl":"{ListWebRelativeUrl}","webpartHeightKey":4,"selectedViewId":"{ListViewId}"}}" />
</Mapping>
Im obigen Beispiel wird das XSLTListView-Quellwebpart einem modernen Textpart (ClientSideText) und einem modernen Webpart (ClientSideWebPart) zugeordnet:
- Verwenden Sie das
Order-Attribut, um zu ermitteln, welches Ereignis zuerst eintritt - Für ein
ClientSideWebPartmüssen SieTypedes Webparts angeben. Wenn SieCustomals Typ auswählen, müssen Sie auch dieControlId-Eigenschaft angeben, um das benötigte benutzerdefinierte Webpart zu bestimmen. - Die
Text-,JsonControlData- undControlId-Eigenschaften können Token in Form von {Token} enthalten, die durch die tatsächlichen Werte zur Laufzeit ersetzt werden. Jedes definierte Token muss eine Webparteigenschaft oder ein Funktionsergebnis wie zuvor erläutert sein.
AddOns-Definition im Seitentransformationsmodell
Mit Add-Ons können Sie Ihre benutzerdefinierte Logik in das Zuordnungsmodell einfügen, indem Sie die folgenden zwei Schritte befolgen:
- Erstellen einer benutzerdefinierten Assembly, die Ihre benutzerdefinierten Funktionen/Selektoren hostet
- 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})"/>