Compartilhar via

Entender e configurar o modelo de transformação de página de publicação (a partir de junho de 2019)

  • Artigo

As páginas de publicação são sempre baseadas em um layout de página e uma página mestra. Essas duas páginas combinadas com campos que contêm dados compõem a página que um usuário vê no navegador. Ao transformar páginas de publicação, é necessário mapear os layouts de página usadas em um modelo de transformação de página de publicação. O componente de transformação de página de publicação terá um mapeamento de layout de página 'padrão' para todos os layouts de página fora da caixa, portanto, se o portal estiver usando esses layouts de página fora da caixa, você será abordado. A realidade é que a maioria dos portais usa layouts de página personalizados (e páginas mestras personalizadas) e, para isso, há a necessidade de mapeamentos de layout de página para esses layouts de página personalizados. Layouts de página personalizados podem ser tratados de duas maneiras:

  • A opção preferida é que você forneça um arquivo de mapeamento de layout de página personalizado, isso fornece controle total sobre quais campos são traduzidos para web parts e onde eles residem na página moderna, quais campos se tornam metadados e muito mais.
  • Se não houver nenhum mapeamento de layout de página encontrado para a página que você está transformando, geraremos um mapeamento na hora e usaremos isso. A desvantagem dessa abordagem é que todo o conteúdo acabará na mesma seção e coluna da página moderna.

Gerando um arquivo de mapeamento de layout de página

Se você estiver usando layouts de página personalizados, é recomendável usar um arquivo de mapeamento de layout de página personalizado para que você possa obter páginas modernas mais precisas. Felizmente você não precisa criar esses arquivos de layout personalizados, há um suporte à API do .Net e ao PowerShell PnP para gerar um.

Usando o PowerShell

Usando o Export-PnPPageMapping cmdlet que você pode:

  • Exporte o arquivo de mapeamento interno (-BuiltInPageLayoutMapping parâmetro): esse arquivo será usado para os layouts de página fora da caixa. Se você especificar um mapeamento personalizado para um layout de página fora da caixa em seu próprio arquivo de mapeamento, esse mapeamento terá preferência sobre o mapeamento OOB
  • Analise os layouts de página no portal conectado e exporte-os como um arquivo de mapeamento (-CustomPageLayoutMapping parâmetro): todos os layouts de página personalizados encontrados são analisados e exportados. Se você também quiser analisar os layouts da página OOB, use o -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

Usando o .Net

No .Net, você precisa usar a PageLayoutAnalyser classe para analisar layouts de página. Abaixo, dois snippets mostram como analisar todos os layouts de página ou os layouts de página usados por determinadas páginas de publicação.

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

O modelo de mapeamento de layout de página explicado

Quando você abre um arquivo de mapeamento de layout de página, os seguintes elementos de nível superior estão presentes:

  • AddOns: como usuário da transformação de página, você pode ter a necessária para aplicar a lógica personalizada para perceber suas necessidades, por exemplo, você precisa transformar uma determinada propriedade de uma maneira que ela possa funcionar com sua Web Part SPFX personalizada. A estrutura dá suporte a isso permitindo que você adicione seus assemblies com funções... simplesmente defini-los na seção AddOn e, em seguida, referenciar suas funções personalizadas posteriormente prefixando-as com o nome determinado fará com que a transformação da página de publicação use seu código personalizado.

  • PageLayouts: esse elemento contém informações para cada layout de página que você planeja usar. Para cada layout de página, você encontrará uma definição do cabeçalho, web part, metadados, zonas da Web Part e web parts fixas.

Os próximos capítulos oferecerão mais detalhes.

Definição de PageLayout no modelo de layout de página

Vamos analisar como um mapeamento de layout de página é configurado no modelo de mapeamento de layout de página, que é melhor feito com base em uma definição de exemplo:

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

Observação

É recomendável que você use o esquema pagelayoutmapping.xsd durante a edição desses arquivos. Os arquivos fornecidos à transformação de página serão validados em relação a esse esquema e a transformação falhará quando o arquivo de mapeamento de layout de página fornecido for inválido.

Elemento PageLayout

As seguintes propriedades são usadas no elemento PageLayout:

  • Nome: contém o nome do layout da página.
  • AlsoAppliesTo: quando esse mapeamento será usado para vários layouts de página, você pode especificar os nomes desses layouts de página adicionais como uma lista delimitada por ponto semi-cólon neste atributo. A propriedade Name será o nome do layout da primeira página, o AlsoAppliesTo contém apenas os adicionais.
  • AssociatedContentType: o nome do tipo de conteúdo de página de site moderno que você deseja usar. Deixe isso em branco se quiser usar o tipo de conteúdo da página do site padrão.
  • PageLayoutTemplate: o sistema de layout a ser usado... padrões para os AutoDetect quais deve funcionar bem em todos os casos, mas opcionalmente você também pode escolher um layout de wiki específico.
  • IncludeVerticalColumn: elemento opcional para especificar a página de destino criada deve ter uma coluna vertical. Ao usar uma coluna vertical, você direciona a coluna vertical como uma coluna extra, portanto, se você antes de adicionar uma coluna vertical tiver três colunas, agora você terá 4 e, como tal, poderá definir o valor da coluna do conteúdo da página como 4 para colocá-la na coluna vertical.
  • PageHeader: controla o tipo de cabeçalho de página que será usado. Padrão para Custom como isso permite um cabeçalho agradável, mas você pode alterná-lo para None sem cabeçalho ou Default para o cabeçalho de página moderno padrão.

Elemento SectionEmphasis

As seguintes propriedades são usadas no elemento SectionEmphasis opcional:

  • VerticalColumnEmphasis: use essa propriedade para definir a ênfase da coluna vertical como None, Neutral, Soft ou Strong

Para cada seção, opcionalmente, você pode especificar uma ênfase de seção por meio do elemento Seção:

  • Linha: indica o número da linha desta seção, a primeira seção terá o número 1
  • Ênfase: define a ênfase da seção como Nenhum, Neutro, Macio ou Forte

Elemento Header

As seguintes propriedades são usadas no elemento Cabeçalho:

  • Tipo: é padrão FullWidthImage permitir que o cabeçalho mostre a imagem do cabeçalho em largura total. As opções alternativas são ColorBlock, CutInShape e NoImage. Observe que esse atributo só é relevante quando o atributo PageHeader foi definido como Custom.
  • Alinhamento: controla como o conteúdo do cabeçalho da página está alinhado. O padrão é Left, a opção alternativa é Center.
  • ShowPublishedDate: define se a data da publicação da página é mostrada. O padrão é true

Para cada campo que você deseja usar no cabeçalho moderno, você precisará adicionar um elemento Field especificando:

  • Nome: o nome dos campos na página de publicação clássica. Por exemplo, adicionar PublishingRollupImage;PublishingPageImage como valor significará que o PublishingRollupImage será tomado se ele for preenchido, se não for preenchido, o PublishingPageImage será julgado. Você pode adicionar quantas substituições precisar
  • HeaderProperty: o nome da propriedade de cabeçalho a ser definida
  • Funções: se definido como vazio, o valor de campo da página de publicação clássica será tomado como está, no entanto, se você especificar uma função aqui, a saída dessa função será usada. Se você especificou vários campos (portanto, usando a opção de substituição de campo), precisará especificar o campo a ser usado na função como {@name}

Ao construir um cabeçalho de página moderno, há 4 propriedades de cabeçalho de página que você pode preencher com dados provenientes da página de publicação:

  • ImageServerRelativeUrl: se o cabeçalho precisar mostrar uma imagem, este campo precisará definir um caminho de imagem relativa do servidor para uma imagem que vive na mesma coleção de sites da página. Por padrão, o campo de página PublishingRollupImage de publicação clássica é usado, mas como isso contém uma marca Img, o conteúdo do campo é limpo por meio da ToImageUrl função.
  • TopicHeader: por padrão, o campo de página ArticleByLine de publicação clássico é usado como cabeçalho de tópico para o cabeçalho de página moderno
  • Autores: a configuração dos autores permite que você mostre o contato principal para esta página no cabeçalho da página. Por padrão, o campo de página PublishingContact de publicação clássico é usado, mas como esse é um campo de usuário, o conteúdo do campo é transformado por meio da ToAuthors função.
  • AlternativeText: não mapeado por padrão, mas você pode adicionar um mapeamento personalizado para preencher a propriedade de texto alternativa de cabeçalho moderno, se desejar

Se você, por exemplo, não quiser definir um cabeçalho de tópico, poderá simplesmente remover ou comentar o respectivo elemento Field.

Opções de imagem cabeçalho de página

O mapeamento padrão usa a imagem definida no PublishingRollupImage campo como cabeçalho de página, mas opcionalmente você pode escolher outro campo de imagem de publicação ou especificar um valor codificado rígido de uma imagem que vive no site de origem ou no site de destino. O exemplo abaixo mostra um cabeçalho com uma imagem 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

O elemento metadados define qual dos campos clássicos da página de publicação precisa ser tomado como metadados para a página moderna. Como às vezes, você deseja que os metadados também sejam representados usando a Web Part propriedades da página OOB que você indica isso por meio desses atributos opcionais:

  • ShowPageProperties: as propriedades da página da Web part serão adicionadas na página moderna resultante
  • PagePropertiesRow: linha que manterá as propriedades da página Web Part
  • PagePropertiesColumn: coluna que manterá as propriedades da página Web Part
  • PagePropertiesOrder: a ordem da web part de propriedades da página na linha/coluna definida

Para cada campo que você deseja assumir, você precisará adicionar um elemento Field especificando:

  • Nome: o nome dos campos na página de publicação clássica. Por exemplo, adicionar PublishingContactName;PublishingContactEmail como valor significará que o PublishingContactName será tomado se ele for preenchido, se não for preenchido, o PublishingContactEmail será julgado. Você pode adicionar quantas substituições precisar
  • TargetFieldName: o nome do campo na página moderna de destino
  • Funções: se definido como vazio, o valor de campo da página de publicação clássica será tomado como está, no entanto, se você especificar uma função aqui, a saída dessa função será usada. Se você especificou vários campos (portanto, usando a opção de substituição de campo), precisará especificar o campo a ser usado na função como {@name}
  • ShowInPageProperties: se definido como true e se mostrar as propriedades da página, a Web Part foi ativada do que esse campo será mostrado na Web Part de propriedades da página

Observação

  • O suporte a funções não está disponível para campos de taxonomia

Elemento WebParts

Cada campo na página de publicação clássica que precisa se tornar um elemento visual na página de destino (como uma Web Part ou texto) deve ser definido na seção Web Parts:

  • Nome: o nome do campo na página de publicação clássica.
  • TargetWebPart: o tipo da Web Part de destino que visualizará esse campo na página moderna. As web parts de destino com suporte são SharePointPnP.Modernization.WikiTextPart, SharePointPnP.Modernization.WikiImagePart e Microsoft.SharePoint.Publishing.WebControls.SummaryLinkWebPart, Microsoft.SharePoint.Publishing, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c.
  • Linha: a linha em que você deseja colocar a Web Part de destino. Precisa ser 1 ou maior.
  • Coluna: a coluna na qual você deseja colocar a Web Part de destino. Precisa ser 1, 2 ou 3.
  • Ordem: a ordem da web part de destino na linha/coluna definida.

Dependendo do TargetWebPart escolhido, você precisará fornecer as propriedades da Web Part que contêm os dados necessários durante a transformação. Cada propriedade tem as seguintes propriedades:

  • Nome: nome da propriedade. Esses nomes de propriedade precisam corresponder às propriedades usadas no modelo de transformação de página.
  • Tipo: tipo da propriedade. Esses tipos de propriedade precisam corresponder às propriedades usadas no modelo de transformação de página.
  • Funções: se definido como vazio, o valor da propriedade será o valor do campo na página de publicação clássica de origem. Você pode usar uma função para primeiro transformar o conteúdo do campo ou usar dados de outro campo da página de publicação clássica

Elemento WebPartZones

Se o layout da página contiver zonas de Web Part, elas deverão ser definidas aqui. Isso é necessário para posicionar corretamente as Web Parts transformadas na página moderna. As seguintes propriedades são usadas:

  • ZoneId: o nome da zona
  • ZoneIndex: o índice da zona (inteiro)
  • Linha: a linha em que você deseja colocar as Web Parts hospedadas nessa zona. Precisa ser 1 ou maior.
  • Coluna: a coluna em que você deseja colocar as web parts hospedadas nessa zona. Precisa ser 1, 2 ou 3.
  • Ordem: ordem na linha/coluna definida para as web parts hospedadas nesta zona

Às vezes, as páginas de publicação têm várias web parts em uma zona da Web Part e você deseja posicionar cada web part de forma diferente na página de destino. Você pode fazer isso usando o elemento Opcional WebPartZoneLayout:

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

A definição acima terá como resultado que o primeiro ContentEditorWebPart irá para a linha 3, coluna 2. O segundo ContentEditorWebPart será colocado na linha 3, coluna 1 com o pedido 2 e a primeira Web Part XSLTListView terminará na linha 3, coluna 1 com a ordem 1. Você pode definir quantos elementos WebPartOccurrence forem necessários, se não houver uma Web Part correspondente na zona da Web Part, o elemento WebPartOccurrence será ignorado. Se houver uma Web Part na zona da Web Part que não esteja listada como um elemento WebPartOccurrence, essa Web Part obterá suas informações de linha, coluna e pedido do elemento WebPartZone.

Elemento FixedWebParts

Às vezes, os layouts de página contêm web parts "fixas", são web parts que são codificadas em código dentro do layout da página e, portanto, elas estão presentes em todas as páginas que usam o layout da página. Como não há API para detectar essas web parts "fixas", elas precisam ser definidas como parte do modelo de mapeamento de layout de página.

As propriedades a seguir podem ser definidas em uma Web Part "fixa":

  • Tipo: tipo da web part fixa. Confira aqui uma lista de tipos possíveis.
  • Linha: a linha em que você deseja colocar a Web Part "fixa". Precisa ser 1 ou maior.
  • Coluna: a coluna na qual você deseja colocar a web part "fixa". Precisa ser 1, 2 ou 3.
  • Ordem: a ordem, relevante se houver várias web parts que você colocou na mesma linha e coluna.

Para cada web part "fixa" você precisa definir as propriedades relevantes. Normalmente, você assumiria essas propriedades conforme elas são definidas no layout da página clássica. Para cada propriedade, os seguintes atributos podem ser definidos:

  • Propriedade: Nome da propriedade. Esses nomes de propriedade precisam corresponder às propriedades usadas no modelo de transformação de página.
  • Tipo: tipo da propriedade. Esses tipos de propriedade precisam corresponder às propriedades usadas no modelo de transformação de página.
  • Valor: o valor que essa propriedade tem. Não se esqueça de codificar o valor XML.

Definição de AddOns no modelo de layout de página

Os complementos permitem inserir sua lógica personalizada no modelo de mapeamento de layout de página seguindo estas duas etapas:

  • Criar um assembly personalizado hospedando suas funções personalizadas
  • Declare este assembly personalizado nos elementos AddOns

Criar seu assembly de funções/seletores personalizado

Para criar suas próprias funções, você precisará fazer referência ao assembly SharePoint.Modernization.Framework no projeto e criar uma classe que herde a classe SharePointPnP.Modernization.Framework.Functions.FunctionsBase:

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

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

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

    }
}

Declarar seu assembly personalizado

Antes de as funções personalizadas poderem ser usadas, elas precisam ser declaradas no modelo, incluindo uma referência por biblioteca/classe no elemento AddOns:

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

ou (observe o caminho qualificado completo)

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

Observe que cada declaração tem um nome "Custom" (personalizado) no exemplo acima.

Usar seus seletores/funções personalizados

Agora que o assembly foi definido, você poderá usar as funções e seletores fazendo referência a eles pelo nome, como você pode ver o prefixo "Custom" no exemplo abaixo:

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

Perguntas frequentes sobre mapeamento de layout de página

Quero manter as informações de criação da página de origem

Ao usar a abordagem do PowerShell PnP , use o -KeepPageCreationModificationInformation cmdlet no ConvertTo-PnPPage cmdlet. Quando você estiver usando a abordagem .Net , defina o KeepPageCreationModificationInformation parâmetro como true. Usar essa opção fornecerá à página de destino os valores de campo Created, Modified, Author e Editor da página de origem.

Observação

Quando você, como parte da transformação de página, promover a página como notícia ou publicar a página, o campo Editor será definido como a transformação de página em execução da conta

Quero promover as páginas criadas como notícias

A promoção de páginas criadas a partir de um layout de página como páginas de notícias pode ser feita usando o -PostAsNews parâmetro no -KeepPageCreationModificationInformation cmdlet (quando você estiver usando a abordagem do PowerShell PnP) ou, alternativamente, definindo o PostAsNews parâmetro como true (ao usar a abordagem .Net).

Quando você usar a opção PostAsNews em conjunto com a opção, o KeepPageCreationModificationInformationFirstPublishedDateField campo será definido como a data de modificação da página de origem. O FirstPublishedDateField campo é o valor de data mostrado durante a distribuição de notícias.

Quero inserir texto codificado na página criada

Às vezes, um layout de página contém snippets de texto, que, como eles não estão satisfeitos na página real, não estão sendo transformados. Se esse for o caso, você poderá definir um campo "falso" para mapear, como mostrado abaixo:

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

Observação

O HTML fornecido na função StaticString deve ser codificado XML e deve ser formatado como o HTML da página de origem, pois este HTML ainda será convertido em HTML, que está em conformidade com o editor de texto moderno

Quero prefixar ou sufixo do conteúdo do campo

A abordagem usada no capítulo anterior permite adicionar texto extra em uma página, mas tem como desvantagem que o texto extra será adicionado em sua própria parte de texto. Se você quiser que o texto extra seja integrado ao texto real que está sendo transformado, a abordagem abaixo permitirá que você faça isso. Você pode prefixar e/ou sufixo de conteúdo de campo existente e, opcionalmente, só pode fazer a prefixação/sufixo quando o campo contiver conteúdo. O parâmetro bool no Prefix, Suffix e PrefixAndSuffix as funções define se o prefixamento/sufixo precisa acontecer quando o conteúdo do campo está vazio: 'true' significa aplicar a ação mesmo quando o campo está vazio.

Consulte Funções de Transformação de Página e Seletores para obter mais detalhes sobre as funções abaixo.

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

Quero preencher um campo de metadados gerenciados com um ou mais termos

Quando você tem um campo de metadados gerenciados nos metadados da página de origem, talvez você queira ter um campo de metadados gerenciados semelhante para a página de destino. Uma transformação de página atualmente tem um recurso de mapeamento de metadados gerenciados que representa um problema. Uma possível solução alternativa é preencher o campo de metadados gerenciados de destino com um termo escolhido ou um conjunto de termos no caso de um campo de metadados gerenciados de vários valores. Isso pode ser feito usando a DefaultTaxonomyFieldValue função, conforme mostrado no exemplo abaixo:

<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 Funções de Transformação de Página e Seletores para obter mais detalhes sobre a DefaultTaxonomyFieldValue função.

Quero adicionar uma Web Part extra na página criada

Quando você transforma sua página de publicação clássica em uma página moderna, às vezes deseja adicionar uma Web Part moderna adicional na página criada, sem isso há uma versão clássica dessa Web Part na página de publicação clássica. Isso pode ser feito ajustando seus arquivos de mapeamento de layout de webpartmapping.xml e página, conforme mostrado abaixo.

Primeiro defina sua Web Part personalizada em seu arquivo webpartmapping.xmladicionando-o ao WebParts elemento no arquivo, como mostrado nesta web part do SPFX Olá, Mundo padrão:

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

Se você não estiver como definir corretamente sua Web Part personalizada no elemento ClientSideWebPart acima, siga estas etapas:

  • Navegue até o Estrutura do SharePoint Workbench em seu site (por exemplo, https://contoso.sharepoint.com/sites/myportalsite/_layouts/workbench.aspx)
  • Adicione sua Web Part personalizada ao workbench e configure-a quando necessário
  • Clique no botão "Dados da Web Part" na barra de ferramentas e, em seguida, no botão "Páginas Modernas"
  • Copie a estrutura json Do WebPartData e use-a para concluir as próximas etapas:
    • O valor da guia ControlId é o valor da propriedade json id
    • Exclua as seguintes propriedades json do snippet copiado: id, instanceIf, título e descrição. Neste ponto, você tem o seguinte à esquerda: {"serverProcessedContent":{"htmlStrings":{},"searchablePlainTexts":{},"imageSources":{},"links":{}},"dataVersion":"1.0","properties":{"description":"HelloWorld from Bert","test":"Multi-line text field","test1":true,"test2":"2","test3":true}}
    • Codificar essa cadeia de caracteres XML, isso lhe dará o seguinte: &#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;
    • Se necessário, insira parâmetros de Web Part nesta cadeia de caracteres (por exemplo, {HelloWorld} no exemplo acima): &#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;
    • Cole a cadeia de caracteres resultante na propriedade JsonControlData

Depois que isso estiver em vigor, você precisará atualizar o mapeamento do layout da página adicionando um campo na seção WebParts que será transformado nesta Web Part personalizada:

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

Certifique-se de especificar o arquivo dewebpartmapping.xml personalizado como parte da transformação (-WebPartMappingFile parâmetro de cmdlet do PowerShell, PublishingPageTransformator construtor ao usar o .Net).

Estou usando muitas partes Add-In e quero transformá-las em web parts SPFX personalizadas

O comportamento padrão da transformação de página é simplesmente assumir a parte de suplemento na página moderna à medida que os suplementos funcionam em páginas modernas. No entanto, se você quiser transformar seletivamente algumas partes de suplemento em web parts personalizadas baseadas em SPFX, solte algumas das partes de suplemento e mantenha as partes de suplemento restantes, então o mapeamento padrão não será suficiente. No exemplo abaixo, você vê que a StaticString função é usada para alimentar o título de suplemento como valor de seletor de mapeamento. Portanto, com base no título da Web Part, um mapeamento será selecionado. O primeiro suplemento será assumido como suplemento na página moderna, o segundo será transformado em uma alternativa baseada em SPFX personalizada e o último será simplesmente descartado.

Ao mapear para uma Web Part baseada em SPFX personalizada, você pode usar qualquer uma de suas propriedades de parte de suplemento para configurar a alternativa baseada em SPFX (por exemplo, {HelloWorld} no exemplo abaixo), mesmo que essas propriedades não estejam listadas no nó Propriedades no arquivo de mapeamento. Consulte também o capítulo anterior se você quiser saber mais sobre como criar um arquivo de mapeamento 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>

Você pode até mesmo tornar o mapeamento mais preciso tomando as propriedades da parte de suplemento da conta combinando as propriedades da parte de suplemento para gerar uma cadeia de caracteres seletora.

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

Posso controlar a imagem de visualização de página

Quando uma página tiver uma imagem de cabeçalho de página, essa imagem também será usada como uma imagem de visualização de página. No entanto, se você quiser controlar a imagem de visualização da página, poderá preencher o BannerImageUrl campo usando a ToPreviewImageUrl função ou especificando um valor codificado rígido, conforme mostrado em exemplos abaixo.

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

Quando a transformação resulta em uma web part do QuickLinks moderna (por exemplo, para transformação do SummaryLinkWebPart), a estrutura de transformação de página usará uma configuração base padrão para a Web Part do QuickLinks. Se você, no entanto, quiser uma configuração diferente, poderá fazer isso especificando a propriedade QuickLinksJsonProperties. Embrulhe as propriedades JSON codificadas em uma função StaticString, conforme mostrado neste exemplo:

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

O JSON no exemplo mostra todas as opções de configuração possíveis que você pode definir, mas no entanto, você também pode apenas definir as necessárias. Desde que o JSON seja válido e a estrutura seja mantida, sua configuração personalizada de QuickLinks será recolhida.