Compartilhar via

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

As páginas de publicação baseiam-se sempre num esquema de página e numa página master. Estas duas páginas combinadas com campos que contêm dados compõem a página que um utilizador vê no browser. Ao transformar páginas de publicação, é obrigatório mapear os esquemas de página utilizados para um modelo de transformação de página de publicação. O componente de transformação da página de publicação terá um mapeamento de esquema de página "predefinido" para todos os esquemas de páginas de caixa, por isso, se o portal estiver a utilizar os esquemas de página fora da caixa que está coberto. A realidade é que a maioria dos portais utiliza esquemas de página personalizados (e páginas de master personalizadas) e, para isso, precisa de mapeamentos de esquemas de página para esses esquemas de página personalizados. Os esquemas de página personalizados podem ser processados de duas formas:

  • A opção preferencial é fornecer um ficheiro de mapeamento de esquema de página personalizado, o que lhe dá controlo total sobre que campos são traduzidos para peças Web e onde residem na página moderna, em que campos se tornam metadados e muito mais.
  • Se não for encontrado nenhum mapeamento de esquema de página para a página que está a transformar, iremos gerar um mapeamento de imediato e utilizá-lo. A desvantagem desta abordagem é que todos os conteúdos acabarão na mesma secção e coluna da página moderna.

Gerar um ficheiro de mapeamento de esquema de página

Se estiver a utilizar esquemas de página personalizados, recomenda-se que utilize um ficheiro de mapeamento de esquema de página personalizado para que possa obter páginas modernas mais precisas. Felizmente, não tem de criar à mão estes ficheiros de esquema personalizados, existe um suporte para a API .Net e o PowerShell PnP para gerar um.

Usando o PowerShell

Com o Export-PnPPageMapping cmdlet, pode:

  • Exportar o ficheiro de mapeamento incorporado (-BuiltInPageLayoutMapping parâmetro): este ficheiro será utilizado para os esquemas de página inicial. Se especificar um mapeamento personalizado para um esquema de página inicial no seu próprio ficheiro de mapeamento, esse mapeamento terá preferência sobre o mapeamento OOB
  • Analise os esquemas de página no portal ligado e exporte-os como um ficheiro de mapeamento (-CustomPageLayoutMapping parâmetro): todos os esquemas de página personalizados encontrados são analisados e exportados. Se também quiser analisar os esquemas de página OOB, utilize 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

Utilizar o .Net

No .Net, tem de utilizar a PageLayoutAnalyser classe para analisar esquemas de página. Abaixo, dois fragmentos mostram como analisar todos os esquemas de página ou os esquemas de página utilizados 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");
}

Explicação do modelo de mapeamento do esquema de página

Quando abre um ficheiro de mapeamento de esquema de página, estão presentes os seguintes elementos de nível superior:

  • AddOns: como utilizador da transformação de página, poderá ter a necessidade de aplicar lógica personalizada para perceber as suas necessidades, por exemplo, tem de transformar uma determinada propriedade de uma forma que possa funcionar com a sua peça Web SPFX personalizada. A arquitetura suporta esta opção ao permitir-lhe adicionar as assemblagens com funções... simplesmente defini-las na secção AddOn e, em seguida, referenciar as suas funções personalizadas mais tarde ao prefixá-las com o nome especificado fará com que a transformação da página de publicação utilize o seu código personalizado.

  • PageLayouts: este elemento contém informações para cada esquema de página que planeia utilizar. Para cada esquema de página, encontrará uma definição do cabeçalho, peça Web, metadados, zonas de peças Web e peças Web fixas.

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

Definição pageLayout no modelo de esquema de página

Vamos analisar a forma como um mapeamento de esquema de página é configurado no modelo de mapeamento de esquema de página, o que é melhor feito com base numa 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

Recomenda-se que utilize o esquema pagelayoutmapping.xsd ao editar estes ficheiros. Os ficheiros que fornecer à transformação de página serão validados relativamente a esse esquema e a transformação falhará quando o ficheiro de mapeamento do esquema de página fornecido for inválido.

Elemento PageLayout

As seguintes propriedades são utilizadas no elemento PageLayout:

  • Nome: contém o nome do esquema de página.
  • AlsoAppliesTo: quando este mapeamento será utilizado para vários esquemas de página, pode especificar os nomes desses esquemas de página adicionais como uma lista delimitada por ponto e vírgula neste atributo. A propriedade Nome será o nome do esquema da primeira página, o AlsoAppliesTo contém apenas os outros.
  • AssociatedContentType: o nome do tipo de conteúdo de página de site moderno que pretende utilizar. Deixe esta opção em branco se quiser utilizar o tipo de conteúdo predefinido da página do site.
  • PageLayoutTemplate: o sistema de esquema a utilizar... predefinições para as AutoDetect quais deve funcionar corretamente em todos os casos, mas opcionalmente também pode escolher um esquema wiki específico.
  • IncludeVerticalColumn: o elemento opcional para especificar a página de destino criada deve ter uma coluna vertical. Ao utilizar uma coluna vertical, direciona a coluna vertical como uma coluna extra, por isso, se antes de adicionar uma coluna vertical tiver 3 colunas, terá agora 4 e, como tal, pode 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á utilizado. Por predefinição Custom , tal permite um bom cabeçalho, mas pode alterá-lo para None sem cabeçalho ou Default para o cabeçalho de página moderno predefinido.

SectionEmphasis element (Elemento SectionEmphasis)

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

  • VerticalColumnEmphasis: utilize esta propriedade para definir a ênfase da coluna vertical como Nenhuma, Neutra, Suave ou Forte

Opcionalmente, para cada secção, pode especificar uma ênfase de secção através do elemento Secção:

  • Linha: indica o número da linha desta secção, a primeira secção terá o número 1
  • Ênfase: define a ênfase da secção como Nenhuma, Neutra, Suave ou Forte

Elemento Header

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

  • Tipo: a predefiniçã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. Tenha em atenção que este atributo só é relevante quando o atributo PageHeader foi definido como Custom.
  • Alinhamento: controla a forma como o conteúdo do cabeçalho da página é alinhado. A predefinição é Left, a opção alternativa é Center.
  • ShowPublishedDate: define se a data de publicação da página é apresentada. O padrão é true

Para cada campo que pretende utilizar no cabeçalho moderno, terá de adicionar um elemento Campo 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 tiver sido preenchido, se não for preenchido, será PublishingPageImage tentado. Pode adicionar o número de substituições que precisar
  • HeaderProperty: o nome da propriedade de cabeçalho a definir
  • Funções: se estiver definido como vazio, o valor do campo da página de publicação clássica é tomado como está. No entanto, se especificar uma função aqui, será utilizada a saída dessa função. Se tiver especificado vários campos (por isso, utilizando a opção de substituição de campos), terá de especificar o campo a utilizar na função como {@name}

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

  • ImageServerRelativeUrl: se o cabeçalho precisar de mostrar uma imagem, este campo terá de definir um caminho de imagem relativa do servidor para uma imagem que reside na mesma coleção de sites que a página. Por predefinição, é utilizado o campo da página PublishingRollupImage de publicação clássica, mas uma vez que contém uma etiqueta Img, o conteúdo do campo é limpo através da ToImageUrl função .
  • TopicHeader: por predefinição, o campo da página ArticleByLine de publicação clássica é utilizado como cabeçalho do tópico para o cabeçalho da página moderna
  • Autores: definir os autores permite-lhe mostrar o contacto main desta página no cabeçalho da página. Por predefinição, é utilizado o campo da página PublishingContact de publicação clássica, mas como se trata de um campo de utilizador, o conteúdo do campo é transformado através da ToAuthors função .
  • AlternativeText: Não mapeado por predefinição, mas pode adicionar um mapeamento personalizado para preencher a propriedade de texto alternativo do cabeçalho moderno, se pretender

Se, por exemplo, não quiser definir um cabeçalho de tópico, pode simplesmente remover ou comentar o respetivo elemento Campo.

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

O mapeamento predefinido utiliza a imagem definida no PublishingRollupImage campo como cabeçalho de página, mas opcionalmente pode escolher outro campo de imagem de publicação ou especificar um valor codificado rígido de uma imagem que reside 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 de metadados define quais dos campos da página de publicação clássica têm de ser assumidos como metadados para a página moderna. Como por vezes pretende que os metadados também sejam representados com a peça Web Propriedades da Página OOB, indica que através destes atributos opcionais:

  • ShowPageProperties: a peça Web propriedades da página será adicionada na página moderna resultante
  • PagePropertiesRow: linha que irá conter a peça Web propriedades da página
  • PagePropertiesColumn: coluna que irá conter a peça Web propriedades da página
  • PagePropertiesOrder: a ordem da peça Web propriedades da página na linha/coluna definida

Para cada campo que pretende assumir, terá de adicionar um elemento Campo que especifique:

  • 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 tiver sido preenchido, se não for preenchido, será PublishingContactEmail tentado. Pode adicionar o número de substituições que precisar
  • TargetFieldName: o nome do campo na página moderna de destino
  • Funções: se estiver definido como vazio, o valor do campo da página de publicação clássica é tomado como está. No entanto, se especificar uma função aqui, será utilizada a saída dessa função. Se tiver especificado vários campos (por isso, utilizando a opção de substituição de campos), terá de especificar o campo a utilizar na função como {@name}
  • ShowInPageProperties: se estiver definido como verdadeiro e se a peça Web mostrar as propriedades da página tiver sido ativada do que este campo é apresentado na peça Web propriedades da página

Observação

  • O suporte de 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 de se tornar um elemento visual na página de destino (como uma peça Web ou texto) tem de ser definido na secção de peças Web:

  • Nome: o nome do campo na página de publicação clássica.
  • TargetWebPart: o tipo da peça Web de destino que irá visualizar este campo na página moderna. As peças Web de destino suportadas 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 na qual pretende colocar a peça Web de destino. Tem de ser 1 ou superior.
  • Coluna: a coluna na qual pretende colocar a peça Web de destino. Tem de ser 1, 2 ou 3.
  • Ordem: a ordem da peça Web de destino na linha/coluna definida.

Consoante o TargetWebPart escolhido, terá de fornecer as propriedades da peça Web que contêm os dados necessários durante a transformação. Cada propriedade tem as seguintes propriedades:

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

Elemento WebPartZones

Se o esquema de página contiver zonas de peças Web, estas têm de ser definidas aqui. Isto é necessário para posicionar corretamente as peças Web transformadas na página moderna. São utilizadas as seguintes propriedades:

  • ZoneId: o nome da zona
  • ZoneIndex: o índice da zona (número inteiro)
  • Linha: a linha na qual pretende colocar as peças Web alojadas nesta zona. Tem de ser 1 ou superior.
  • Coluna: a coluna na qual pretende colocar as peças Web alojadas nesta zona. Tem de ser 1, 2 ou 3.
  • Ordem: ordem na linha/coluna definida para as peças Web alojadas nesta zona

Por vezes, as páginas de publicação têm várias peças Web numa zona de peças Web e pretende posicionar cada peça Web de forma diferente na página de destino. Pode fazê-lo com 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 a ordem 2 e a primeira peça Web XSLTListView acabará na linha 3, coluna 1 com a ordem 1. Pode definir o número de elementos WebPartOccurrence necessários, se não existir uma peça Web correspondente na zona da peça Web, o elemento WebPartOccurrence será ignorado. Se existir uma peça Web na zona da peça Web que não esteja listada como um elemento WebPartOccurrence, essa peça Web obterá as informações de linha, coluna e ordem do elemento WebPartZone.

FixedWebParts element (Elemento FixedWebParts)

Por vezes, os esquemas de página contêm peças Web "fixas", ou seja, peças Web codificadas no esquema de página, pelo que estão presentes em todas as páginas que utilizam o esquema de página. Uma vez que não existe nenhuma API para detetar estas peças Web "fixas", têm de ser definidas como parte do modelo de mapeamento de esquema de página.

As seguintes propriedades podem ser definidas numa peça Web "fixa":

  • Tipo: tipo da peça Web fixa. Veja aqui uma lista de tipos possíveis.
  • Linha: a linha na qual pretende colocar a peça Web "fixa". Tem de ser 1 ou superior.
  • Coluna: a coluna na qual pretende colocar a peça Web "fixa". Tem de ser 1, 2 ou 3.
  • Encomenda: a ordem, relevante se existirem várias peças Web que colocou na mesma linha e coluna.

Para cada peça Web "fixa", tem de definir as propriedades relevantes. Normalmente, assumiria estas propriedades tal como estão definidas no esquema de página clássico. Para cada propriedade, os seguintes atributos podem ser definidos:

  • Propriedade: nome da propriedade . Estes nomes de propriedades têm de corresponder às propriedades utilizadas no modelo de transformação de página.
  • Tipo: tipo da propriedade . Estes tipos de propriedade têm de corresponder às propriedades utilizadas no modelo de transformação de página.
  • Valor: o valor que esta propriedade tem. Não se esqueça de codificar o valor em XML.

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

Os suplementos permitem-lhe inserir a sua lógica personalizada no modelo de mapeamento de esquema de página ao seguir estes 2 passos:

  • Criar uma assemblagem personalizada que aloja as 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})"/>

FAQ sobre o mapeamento do esquema de página

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

Ao utilizar a abordagem PnP do PowerShell , utilize o -KeepPageCreationModificationInformation cmdlet no ConvertTo-PnPPage cmdlet . Quando estiver a utilizar a abordagem .Net , defina o KeepPageCreationModificationInformation parâmetro como verdadeiro. A utilização desta opção dará à página de destino os valores de campo Criado, Modificado, Autor e Editor a partir da página de origem.

Observação

Quando, como parte da transformação da página, promover a página como notícias ou publicar a página, o campo Editor será definido para a transformação da 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 esquema de página como páginas de notícias pode ser feita através do -PostAsNews parâmetro no -KeepPageCreationModificationInformation cmdlet (quando estiver a utilizar a abordagem PnP do PowerShell) ou, em alternativa, ao definir o PostAsNews parâmetro como verdadeiro (ao utilizar a abordagem .Net).

Quando utilizar a opção PostAsNews em conjunto com a opção, FirstPublishedDateField o KeepPageCreationModificationInformation campo será definido como a data de modificação da página de origem. O FirstPublishedDateField campo é o valor de data apresentado durante o rollup de notícias.

Quero inserir texto codificado na página criada

Por vezes, um esquema de página contém fragmentos de texto que, uma vez que não são conteúdos na página real, não estão a ser transformados. Se for esse o caso, pode 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 tem de ter codificação XML e tem de ser formatado como o HTML da página de origem, uma vez que este HTML continuará a ser convertido em HTML, que está em conformidade com o editor de texto moderno

Quero prefixar ou sufixo o conteúdo do campo

A abordagem utilizada no capítulo anterior permite-lhe adicionar texto extra numa página, mas tem como desvantagem que o texto adicional será adicionado na sua própria parte de texto. Se quiser que o texto adicional seja integrado com o texto real a ser transformado, a abordagem abaixo permite-lhe fazê-lo. Pode colocar o prefixo e/ou o sufixo existente no conteúdo do campo e, opcionalmente, só pode ter o prefixo/sufixo concluído quando o campo contém conteúdo. O parâmetro bool nas Prefixfunções e SuffixPrefixAndSuffix define se o prefixo/sufixo tem de ocorrer quando o conteúdo do campo está vazio: "verdadeiro" significa aplicar a ação mesmo quando o campo está vazio.

Veja Funções e Seletores de Transformação de Páginas 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 geridos com um ou mais termos

Quando tiver um campo de metadados geridos nos metadados da página de origem, poderá querer ter um campo de metadados geridos semelhante para a página de destino. Uma determinada transformação de página tem atualmente uma funcionalidade de mapeamento de metadados geridos que representa um problema. Uma solução possível é preencher o campo de metadados geridos de destino com um termo escolhido ou um conjunto de termos no caso de um campo de metadados geridos com múltiplos valores. Isto pode ser feito com 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>

Veja Funções e Seletores de Transformação de Páginas para obter mais detalhes sobre a DefaultTaxonomyFieldValue função.

Quero adicionar uma peça Web extra na página criada

Quando transforma a sua página de publicação clássica numa página moderna, por vezes quer adicionar uma peça Web moderna adicional na página criada, sem que exista uma versão clássica dessa peça Web na página de publicação clássica. Isto pode ser feito ao ajustar os ficheiros de mapeamento de esquema de página e webpartmapping.xml, conforme mostrado abaixo.

Primeiro, defina a peça Web personalizada no seu ficheiro dewebpartmapping.xml ao adicioná-la ao WebParts elemento no ficheiro, como mostrado nesta peça Web 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 não estiver a definir corretamente a peça Web personalizada no elemento ClientSideWebPart acima, siga estes passos:

  • Navegue para o Estrutura do SharePoint Workbench no seu site (por exemplo, https://contoso.sharepoint.com/sites/myportalsite/_layouts/workbench.aspx)
  • Adicionar a peça Web personalizada ao workbench e configurá-la quando necessário
  • Clique no botão "Dados da peça Web" na barra de ferramentas e, em seguida, no botão "Páginas Modernas"
  • Copie a estrutura de json WebPartData e utilize-a para concluir os passos seguintes:
    • O valor guid controlId é o valor da propriedade id json
    • Elimine as seguintes propriedades json do fragmento copiado: id, instanceIf, title e description. Neste momento, ainda tem o seguinte: {"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 xML esta cadeia, isto irá dar-lhe 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 peças Web nesta cadeia (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;
    • Colar a cadeia resultante na propriedade JsonControlData

Assim que estiver implementado, terá de atualizar o mapeamento do esquema de página ao adicionar um campo na secção Peças Web que será transformado nesta peça Web 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 que especifica o ficheiro dewebpartmapping.xml personalizado como parte da sua transformação (-WebPartMappingFile parâmetro de cmdlet do PowerShell, PublishingPageTransformator construtor ao utilizar .Net).

Estou a utilizar muitas peças Add-In e quero transformá-las em peças Web SPFX personalizadas

O comportamento predefinido da transformação de páginas é simplesmente assumir a parte do suplemento na página moderna, uma vez que os suplementos funcionam em páginas modernas. No entanto, se quiser transformar seletivamente algumas peças de suplemento em peças Web personalizadas baseadas em SPFX, remova algumas das partes do suplemento e mantenha as restantes partes do suplemento, o mapeamento predefinido não será suficiente. No exemplo abaixo, verá que a StaticString função é utilizada para alimentar o título do suplemento como valor do seletor de mapeamento. Assim, com base no título da peça Web, será selecionado um mapeamento. O primeiro suplemento será assumido como suplemento na página moderna, o segundo será transformado numa alternativa personalizada baseada em SPFX e o último será simplesmente removido.

Ao mapear para uma peça Web personalizada baseada em SPFX, pode utilizar qualquer uma das suas propriedades de peças 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 ficheiro de mapeamento. Veja também o capítulo anterior se quiser saber mais sobre como criar um ficheiro 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>

Pode até tornar o mapeamento mais preciso ao ter em conta propriedades de peças de suplemento ao combinar as propriedades da parte do suplemento para gerar uma cadeia de seletor.

<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 pré-visualização da página

Quando uma página tem uma imagem de cabeçalho de página, essa imagem também será utilizada como uma imagem de pré-visualização de página. No entanto, se quiser controlar a imagem de pré-visualização da página, pode preencher o BannerImageUrl campo com a ToPreviewImageUrl função ou ao especificar um valor codificado, conforme mostrado nos 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 numa peça Web QuickLinks moderna (por exemplo, para a transformação de SummaryLinkWebPart), a arquitetura de transformação de páginas utilizará uma configuração base predefinida para a peça Web QuickLinks. No entanto, se quiser uma configuração diferente, pode fazê-lo ao especificar a propriedade QuickLinksJsonProperties. Encapsular as propriedades JSON codificadas numa 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 pode definir, mas também pode definir as opções de que precisa. Desde que o JSON seja válido e a estrutura seja mantida, a configuração personalizada das QuickLinks será recolhida.

  • Last updated on