Compartir a través de

Descripción y configuración del modelo de transformación de página de publicación (a partir de la versión de junio de 2019)

  • Artículo

Las páginas de publicación siempre se basan en un diseño de página y una página maestra. Esas dos páginas combinadas con campos que contienen datos constituyen la página que un usuario ve en el explorador. Al transformar páginas de publicación, es obligatorio asignar los diseños de página usados a un modelo de transformación de página de publicación. El componente de transformación de página de publicación tendrá una asignación de diseño de página "predeterminada" para todos los diseños de página fuera de serie, por lo que si el portal usa los diseños de página que están fuera de la caja, está cubierto. La realidad es que la mayoría de los portales usan diseños de página personalizados (y páginas maestras personalizadas) y, por lo tanto, hay una necesidad de asignaciones de diseño de página para esos diseños de página personalizados. Los diseños de página personalizados se pueden controlar de dos maneras:

  • La opción preferida es que proporcione un archivo de asignación de diseño de página personalizado, esto le proporciona control total sobre qué campos se traducen a elementos web y dónde residen en la página moderna, qué campos se convierten en metadatos y mucho más.
  • Si no se encuentra ninguna asignación de diseño de página para la página que va a transformar, generaremos una asignación sobre la marcha y la usaremos. La desventaja de este enfoque es que todo el contenido terminará en la misma sección y columna de la página moderna.

Generación de un archivo de asignación de diseño de página

Si usa diseños de página personalizados, se recomienda usar un archivo de asignación de diseño de página personalizado para que pueda obtener páginas modernas más precisas. Afortunadamente no es necesario crear manualmente estos archivos de diseño personalizados, hay una API de .Net y compatibilidad con PowerShell de PnP para generar uno.

Con PowerShell

Con el Export-PnPPageMapping cmdlet puede:

  • Exporte el archivo de asignación integrado (-BuiltInPageLayoutMapping parámetro): este archivo se usará para los diseños de página de fábrica. Si especifica una asignación personalizada para un diseño de página estándar en su propio archivo de asignación, esa asignación tendrá preferencia sobre la asignación de OOB.
  • Analice los diseños de página en el portal conectado y exportelos como un archivo de asignación (-CustomPageLayoutMapping parámetro): todos los diseños de página personalizados encontrados se analizan y exportan. Si también desea analizar los diseños de página de OOB, use el -AnalyzeOOBPageLayouts parámetro .
# 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

Uso de .Net

En .Net, debe usar la PageLayoutAnalyser clase para analizar los diseños de página. A continuación, dos fragmentos de código muestran cómo analizar todos los diseños de página o los diseños de página usados por determinadas páginas de publicación.

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

El modelo de asignación de diseño de página explicado

Al abrir un archivo de asignación de diseño de página, están presentes los siguientes elementos de nivel superior:

  • AddOns: como usuario de transformación de página, es posible que tenga la necesidad de aplicar lógica personalizada para darse cuenta de sus necesidades, por ejemplo, debe transformar una propiedad determinada de forma que pueda funcionar con el elemento web SPFX personalizado. El marco admite esto al permitirle agregar los ensamblados con funciones... simplemente definirlas en la sección AddOn y, a continuación, hacer referencia a las funciones personalizadas más adelante mediante el prefijo con el nombre dado hará que la transformación de página de publicación use el código personalizado.

  • PageLayouts: este elemento contiene información para cada diseño de página que va a usar. Para cada diseño de página, encontrará una definición del encabezado, elemento web, metadatos, zonas de elementos web y elementos web fijos.

En los próximos capítulos ofreceremos más detalles.

Definición de PageLayout en el modelo de diseño de página

Vamos a analizar cómo se configura una asignación de diseño de página en el modelo de asignación de diseño de página, que se realiza mejor en función de una definición de ejemplo:

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

Nota:

Se recomienda usar el esquema pagelayoutmapping.xsd al editar estos archivos. Los archivos que proporcione a la transformación de página se validarán con ese esquema y la transformación producirá un error cuando el archivo de asignación de diseño de página proporcionado no sea válido.

Elemento PageLayout

Las siguientes propiedades se usan en el elemento PageLayout:

  • Nombre: contiene el nombre del diseño de página.
  • AlsoAppliesTo: cuando esta asignación se usará para varios diseños de página, puede especificar los nombres de esos diseños de página adicionales como una lista delimitada por puntos y comas en este atributo. La propiedad Name será el nombre del primer diseño de página; AlsoAppliesTo solo contiene los adicionales.
  • AssociatedContentType: el nombre del tipo de contenido de página de sitio moderno que desea usar. Déjelo en blanco si desea usar el tipo de contenido de página de sitio predeterminado.
  • PageLayoutTemplate: el sistema de diseño que se va a usar... el valor predeterminado es el AutoDetect que debería funcionar bien en todos los casos, pero, opcionalmente, también puede elegir un diseño wiki específico.
  • IncludeVerticalColumn: elemento opcional para especificar la página de destino creada debe tener una columna vertical. Al usar una columna vertical, tiene como destino la columna vertical como una columna adicional, por lo que si antes de agregar una columna vertical tenía 3 columnas, ahora tendrá 4 y, como tal, puede establecer el valor de columna del contenido de página en 4 para colocarla en la columna vertical.
  • PageHeader: controla el tipo de encabezado de página que se usará. El valor predeterminado es Custom como que permite un encabezado agradable, pero puede cambiarlo a None para ningún encabezado o Default para el encabezado de página moderno predeterminado.

Elemento SectionEmphasis

Las siguientes propiedades se usan en el elemento SectionEmphasis opcional:

  • VerticalColumnEmphasis: use esta propiedad para establecer el énfasis de columna vertical en None, Neutral, Soft o Strong.

Para cada sección, opcionalmente puede especificar un énfasis de sección a través del elemento Section:

  • Fila: indica el número de fila de esta sección, la primera sección tendrá el número 1.
  • Énfasis: establece el énfasis de sección en Ninguno, Neutro, Suave o Fuerte

Elemento Header

Las propiedades siguientes se usan en el elemento Header:

  • Tipo: el valor predeterminado es permitir que FullWidthImage el encabezado muestre la imagen de encabezado en ancho completo. Las opciones alternativas son ColorBlock, CutInShape y NoImage. Tenga en cuenta que este atributo solo es relevante cuando el atributo PageHeader se estableció en Custom.
  • Alineación: controla cómo se alinea el contenido del encabezado de página. El valor predeterminado es Left, la opción alternativa es Center.
  • ShowPublishedDate: define si se muestra la fecha de publicación de la página. Valores predeterminados de true.

Para cada campo que quiera usar en el encabezado moderno, deberá agregar un elemento Field que especifique:

  • Nombre: nombre de los campos de la página de publicación clásica. Por ejemplo, agregar PublishingRollupImage;PublishingPageImage como valor significará que se tomará si PublishingRollupImage se ha rellenado, si no se ha rellenado PublishingPageImage , se intentará. Puede agregar tantas invalidaciones como necesite.
  • HeaderProperty: nombre de la propiedad de encabezado que se va a establecer
  • Funciones: si se establece en vacío, el valor del campo de la página de publicación clásica se toma tal y como está, pero si especifica una función aquí, se usa la salida de esa función. Si ha especificado varios campos (por lo que debe usar la opción de invalidación de campo), deberá especificar el campo que se usará en la función como {@name}

Al construir un encabezado de página moderno, hay 4 propiedades de encabezado de página que puede rellenar con datos procedentes de la página de publicación:

  • ImageServerRelativeUrl: si el encabezado necesita mostrar una imagen, este campo tendrá que definir una ruta de acceso de imagen relativa al servidor para una imagen que se encuentra en la misma colección de sitios que la página. De forma predeterminada, se usa el campo de página PublishingRollupImage de publicación clásica, pero dado que contiene una etiqueta Img, el contenido del campo se limpia a través de la ToImageUrl función .
  • TopicHeader: de forma predeterminada, el campo de página ArticleByLine de publicación clásica se usa como encabezado de tema para el encabezado de página moderno.
  • Autores: establecer los autores le permite mostrar el contacto principal de esta página en el encabezado de página. De forma predeterminada, se usa el campo de página PublishingContact de publicación clásica, pero dado que es un campo de usuario, el contenido del campo se transforma a través de la ToAuthors función .
  • AlternativeText: no asignado de forma predeterminada, pero puede agregar una asignación personalizada para rellenar la propiedad de texto alternativo de encabezado moderno si lo desea.

Si, por ejemplo, no desea establecer un encabezado de tema, simplemente puede quitar o comentar el elemento Field correspondiente.

Opciones de imagen de encabezado de página

La asignación predeterminada toma la imagen definida en el PublishingRollupImage campo como encabezado de página, pero opcionalmente puede elegir otro campo de imagen de publicación o especificar un valor codificado de forma rígida de una imagen que se encuentra en el sitio de origen o en el sitio de destino. En el ejemplo siguiente se muestra un encabezado con una imagen estática:

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

Elemento MetaData

El elemento metadata define cuál de los campos de la página de publicación clásica debe tomarse como metadatos de la página moderna. Como a veces quiere que los metadatos también se representen mediante el elemento web Propiedades de página OOB, indica que a través de estos atributos opcionales:

  • ShowPageProperties: se agregará el elemento web de propiedades de página en la página moderna resultante.
  • PagePropertiesRow: fila que contendrá el elemento web de propiedades de página
  • PagePropertiesColumn: columna que contendrá el elemento web de propiedades de página
  • PagePropertiesOrder: el orden del elemento web de propiedades de página en la fila o columna definida

Para cada campo que quiera asumir, deberá agregar un elemento Field que especifique lo siguiente:

  • Nombre: nombre de los campos de la página de publicación clásica. Por ejemplo, agregar PublishingContactName;PublishingContactEmail como valor significará que se tomará si PublishingContactName se ha rellenado, si no se ha rellenado PublishingContactEmail , se intentará. Puede agregar tantas invalidaciones como necesite.
  • TargetFieldName: nombre del campo en la página moderna de destino
  • Funciones: si se establece en vacío, el valor del campo de la página de publicación clásica se toma tal y como está, pero si especifica una función aquí, se usa la salida de esa función. Si ha especificado varios campos (por lo que debe usar la opción de invalidación de campo), deberá especificar el campo que se usará en la función como {@name}
  • ShowInPageProperties: si se establece en true y si se ha activado el elemento web de propiedades de página que este campo se muestra en el elemento web de propiedades de página

Nota:

  • La compatibilidad con Functions no está disponible para los campos de taxonomía

Elemento WebParts

Cada campo de la página de publicación clásica que necesita convertirse en un elemento visual en la página de destino (como un elemento web o texto) debe definirse en la sección de elementos web:

  • Nombre: nombre del campo en la página de publicación clásica.
  • TargetWebPart: el tipo del elemento web de destino que visualizará este campo en la página moderna. Los elementos web de destino admitidos son SharePointPnP.Modernization.WikiTextPart, SharePointPnP.Modernization.WikiImagePart y Microsoft.SharePoint.Publishing.WebControls.SummaryLinkWebPart, Microsoft.SharePoint.Publishing, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c.
  • Fila: la fila en la que desea colocar el elemento web de destino. Debe ser 1 o superior.
  • Columna: columna en la que desea colocar el elemento web de destino. Debe ser 1, 2 o 3.
  • Orden: el orden del elemento web de destino en la fila o columna definida.

Dependiendo del TargetWebPart elegido, deberá proporcionar las propiedades del elemento web que contienen los datos necesarios durante la transformación. Cada propiedad tiene las siguientes propiedades:

  • Nombre: nombre de la propiedad. Estos nombres de propiedad deben coincidir con las propiedades usadas en el modelo de transformación de página.
  • Tipo: tipo de la propiedad . Estos tipos de propiedad deben coincidir con las propiedades usadas en el modelo de transformación de página.
  • Funciones: si se establece en vacío, el valor de la propiedad será el valor del campo en la página de publicación clásica de origen. Puede usar una función para transformar primero el contenido del campo o para usar datos de otro campo de la página de publicación clásica.

Elemento WebPartZones

Si el diseño de página contiene zonas de elementos web, estas deben definirse aquí. Esto es necesario para colocar correctamente los elementos web transformados en la página moderna. Se usan las siguientes propiedades:

  • ZoneId: el nombre de la zona
  • ZoneIndex: índice de la zona (entero)
  • Fila: la fila en la que desea colocar los elementos web hospedados en esta zona. Debe ser 1 o superior.
  • Columna: la columna en la que desea colocar los elementos web hospedados en esta zona. Debe ser 1, 2 o 3.
  • Orden: orden en la fila o columna definida para los elementos web hospedados en esta zona

A veces, las páginas de publicación tienen varios elementos web en una zona de elementos web y desea colocar cada elemento web de forma diferente en la página de destino. Para ello, use el elemento WebPartZoneLayout opcional:

<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 definición anterior tendrá como resultado que el primer ContentEditorWebPart irá a la fila 3, columna 2. El segundo elemento ContentEditorWebPart se colocará en la fila 3, la columna 1 con el orden 2 y el primer elemento web XSLTListView terminará en la fila 3, columna 1 con el orden 1. Puede definir tantos elementos WebPartOccurrence como sea necesario, si no hay ningún elemento web correspondiente en la zona de elementos web, se omitirá el elemento WebPartOccurrence. Si hay un elemento web en la zona de elementos web que no aparece como elemento WebPartOccurrence, ese elemento web obtendrá la información de fila, columna y orden del elemento WebPartZone.

Elemento FixedWebParts

A veces, los diseños de página contienen elementos web "fijos", estos son elementos web que están codificados de forma rígida dentro del diseño de página y, por tanto, están presentes en todas las páginas que usan el diseño de página. Como no hay ninguna API para detectar estos elementos web "fijos", deben definirse como parte del modelo de asignación de diseño de página.

Las siguientes propiedades se pueden establecer en un elemento web "fijo":

  • Tipo: tipo del elemento web fijo. Consulte aquí para obtener una lista de los tipos posibles.
  • Fila: la fila en la que desea colocar el elemento web "fijo". Debe ser 1 o superior.
  • Columna: columna en la que desea colocar el elemento web "fijo". Debe ser 1, 2 o 3.
  • Orden: el pedido, pertinente si hay varios elementos web que se colocan en la misma fila y columna.

Para cada elemento web "fijo" debe definir las propiedades pertinentes. Normalmente, tomaría el control de estas propiedades tal y como se definen en el diseño de página clásico. Para cada propiedad, se pueden establecer los siguientes atributos:

  • Propiedad: nombre de la propiedad. Estos nombres de propiedad deben coincidir con las propiedades usadas en el modelo de transformación de página.
  • Tipo: tipo de la propiedad . Estos tipos de propiedad deben coincidir con las propiedades usadas en el modelo de transformación de página.
  • Valor: valor que tiene esta propiedad. No olvide codificar el valor en XML.

Definición de AddOns en el modelo de diseño de página

Los complementos permiten insertar la lógica personalizada en el modelo de asignación de diseño de página siguiendo estos dos pasos:

  • Creación de un ensamblado personalizado que hospede las funciones personalizadas
  • Declarar este conjunto personalizado en los elementos de complementos

Crear el conjunto de selectores o funciones personalizados

Para crear sus propias funciones, necesitará hacer referencia al conjunto SharePoint.Modernization.Framework en su proyecto y, a continuación, crear una clase que herede la clase 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;
            }
        }

    }
}

Declarar el conjunto personalizado

Para que pueden usarse las funciones personalizadas, tienen que declararse en el modelo agregando una referencia a cada biblioteca o clase en el elemento de complementos:

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

o (observe la ruta de acceso completa)

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

Tenga en cuenta que cada declaración tiene un nombre, "Personalizado" en el anterior ejemplo.

Use los selectores o las funciones personalizados

Ahora que se ha definido el conjunto, puede usar las funciones y selectores haciendo referencia a ellos por el nombre como puede ver en el siguiente ejemplo del prefijo "Personalizado":

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

Preguntas más frecuentes sobre la asignación de diseño de página

Quiero mantener la información de creación de páginas de origen

Al usar el enfoque de PowerShell PnP , use el -KeepPageCreationModificationInformation cmdlet en el ConvertTo-PnPPage cmdlet . Cuando use el enfoque de .Net , establezca el KeepPageCreationModificationInformation parámetro en true. Con esta opción, la página de destino proporcionará los valores de campo Creado, Modificado, Autor y Editor de la página de origen.

Nota:

Cuando usted, como parte de la transformación de página, promueva la página como noticias o publique la página, el campo Editor se establecerá en la cuenta que ejecuta la transformación de página.

Quiero promover las páginas creadas como noticias

La promoción de páginas creadas a partir de un diseño de página como páginas de noticias se puede realizar mediante el -PostAsNews parámetro en el -KeepPageCreationModificationInformation cmdlet (cuando se usa el enfoque de PowerShell de PnP) o, alternativamente, estableciendo el PostAsNews parámetro en true (cuando se usa el enfoque de .Net).

Cuando se usa la PostAsNews opción junto con la opción, el FirstPublishedDateFieldKeepPageCreationModificationInformation campo se establecerá en la fecha de modificación de la página de origen. El FirstPublishedDateField campo es el valor de fecha que se muestra durante el paquete acumulativo de noticias.

Quiero insertar texto codificado de forma rígida en la página creada

A veces, un diseño de página contiene fragmentos de texto, que como no son contenido en la página real no se transforman. Si ese es el caso, puede definir un campo "falso" para asignar como se muestra a continuación:

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

Nota:

El CÓDIGO HTML proporcionado en la función StaticString debe estar codificado en XML y debe tener el formato html de la página de origen, ya que este HTML se seguirá convirtiendo en HTML, que es compatible con el editor de texto moderno.

Quiero anteponer o sufijo el contenido del campo

El enfoque usado en el capítulo anterior le permite agregar texto adicional en una página, pero tiene como inconveniente que el texto adicional se agregará en su propia parte de texto. Si desea que el texto adicional se integre con el texto real que se va a transformar, el enfoque siguiente le permite hacerlo. Puede prefijo o sufijo contenido de campo existente y, opcionalmente, solo puede hacer el prefijo o sufijo cuando el campo contiene contenido. El parámetro bool de las Prefixfunciones y PrefixAndSuffixSuffix define si el prefijo o sufijo debe producirse cuando el contenido del campo está vacío: "true" significa aplicar la acción incluso cuando el campo está vacío.

Consulte Funciones y selectores de transformación de página para obtener más información sobre las funciones siguientes.

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

Quiero rellenar un campo de metadatos administrados con uno o varios términos

Si tiene un campo de metadatos administrados en los metadatos de la página de origen, es posible que quiera tener un campo de metadatos administrados similar para la página de destino. Actualmente, una transformación de página determinada tiene una característica de asignación de metadatos administrados, lo que supone un problema. Una posible solución alternativa consiste en rellenar el campo de metadatos administrados de destino con un término elegido o un conjunto de términos en caso de un campo de metadatos administrados de varios valores. Esto se puede hacer con la DefaultTaxonomyFieldValue función como se muestra en el ejemplo siguiente:

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

Consulte Funciones y selectores de transformación de página para obtener más información sobre la DefaultTaxonomyFieldValue función.

Quiero agregar un elemento web adicional a la página creada

Al transformar la página de publicación clásica en una página moderna, a veces quiere agregar un elemento web moderno adicional en la página creada, sin que haya una versión clásica de ese elemento web en la página de publicación clásica. Esto se puede hacer ajustando los archivos de asignación de diseño de página y webpartmapping.xml como se muestra a continuación.

En primer lugar, defina el elemento web personalizado en el archivo webpartmapping.xmlagregándolo al WebParts elemento en el archivo, como se muestra en este elemento web Hola mundo SPFX estándar:

<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 no está definiendo correctamente el elemento web personalizado en el elemento ClientSideWebPart anterior, siga estos pasos:

  • Vaya a SharePoint Framework Workbench en su sitio (por ejemplo, https://contoso.sharepoint.com/sites/myportalsite/_layouts/workbench.aspx)
  • Agregue el elemento web personalizado al área de trabajo y configúrelo cuando sea necesario.
  • Haga clic en el botón "Datos de elementos web" de la barra de herramientas y, a continuación, en el botón "Páginas modernas".
  • Copie la estructura json WebPartData y úsela para completar los pasos siguientes:
    • El valor del guid ControlId es el valor de la propiedad json id.
    • Elimine las siguientes propiedades json del fragmento de código copiado: id, instanceIf, title y description. En este punto, tiene lo siguiente a la izquierda: {"serverProcessedContent":{"htmlStrings":{},"searchablePlainTexts":{},"imageSources":{},"links":{}},"dataVersion":"1.0","properties":{"description":"HelloWorld from Bert","test":"Multi-line text field","test1":true,"test2":"2","test3":true}}
    • El código XML de esta cadena le proporcionará lo siguiente: &#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 es necesario, inserte parámetros de elementos web en esta cadena (por ejemplo, {HelloWorld} en el ejemplo anterior): &#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;
    • Pegue la cadena resultante en la propiedad JsonControlData .

Una vez que esté en su lugar, debe actualizar la asignación de diseño de página agregando un campo en la sección WebParts que se transformará en este elemento web personalizado:

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

Asegúrese de especificar el archivo dewebpartmapping.xml personalizado como parte de la transformación (-WebPartMappingFile parámetro de cmdlet de PowerShell, PublishingPageTransformator constructor al usar .Net).

Estoy usando una gran cantidad de elementos Add-In y quiero transformarlos en elementos web SPFX personalizados

El comportamiento predeterminado de la transformación de página es simplemente tomar el control del elemento de complemento en la página moderna, ya que los complementos funcionan en páginas modernas. Sin embargo, si desea transformar de forma selectiva algunos elementos de complemento en elementos web personalizados basados en SPFX, quite algunos de los elementos de complemento y conserve los restantes, la asignación predeterminada no será suficiente. En el ejemplo siguiente verá que la StaticString función se usa para alimentar el título del complemento como valor del selector de asignación. Por lo tanto, en función del título del elemento web, se seleccionará una asignación. El primer complemento se asumirá como complemento en la página moderna, el segundo se transformará en una alternativa personalizada basada en SPFX y el último simplemente se quitará.

Al asignar a un elemento web personalizado basado en SPFX, puede usar cualquiera de las propiedades del elemento de complemento para configurar la alternativa basada en SPFX (por ejemplo, {HelloWorld} en el ejemplo siguiente), incluso si esas propiedades no aparecen en el nodo Propiedades del archivo de asignación. Consulte también el capítulo anterior si desea obtener más información sobre cómo crear un archivo de asignación personalizado.

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

Incluso puede hacer que la asignación sea más precisa teniendo en cuenta las propiedades del elemento de complemento mediante la combinación de las propiedades del elemento de complemento para generar una cadena de selector.

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

¿Puedo controlar la imagen de vista previa de página?

Cuando una página tiene una imagen de encabezado de página, esa imagen también se usará como imagen de vista previa de página. Sin embargo, si desea controlar la imagen de vista previa de página, puede rellenar el BannerImageUrl campo mediante la ToPreviewImageUrl función o especificando un valor codificado de forma rígida, como se muestra en los ejemplos siguientes.

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

Cuando la transformación da como resultado un elemento web QuickLinks moderno (por ejemplo, para la transformación de SummaryLinkWebPart), el marco de transformación de página usará una configuración base predeterminada para el elemento web QuickLinks. Sin embargo, si quiere una configuración diferente, puede hacerlo especificando la propiedad QuickLinksJsonProperties. Ajuste las propiedades JSON codificadas en una función StaticString como se muestra en este ejemplo:

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

El JSON del ejemplo muestra todas las opciones de configuración posibles que puede establecer, pero también puede definir las que necesita. Siempre que el JSON sea válido y se mantenga la estructura, se recogerá la configuración personalizada de QuickLinks.