Adicionar uma renderização personalizada do lado do cliente a um Suplemento do SharePoint hospedado pelo SharePoint

Artigo
04/08/2023

Esse é o oitavo de uma série de artigos sobre as noções básicas de desenvolvimento de Suplementos do SharePoint hospedados no próprio SharePoint. Primeiro você deve se familiarizar com os Suplementos do SharePoint e os artigos anteriores dessa série, que você pode encontrar na Introdução à criação de Suplementos do SharePoint hospedados pelo SharePoint.

Observação

Se você trabalhou com esta série sobre suplementos hospedados pelo SharePoint, você terá uma solução do Visual Studio que pode ser usada para continuar com este tópico. Você também pode baixar o repositório em SharePoint_SP-hosted_Add-Ins_Tutorials e abrir o arquivo BeforeClientRenderedControl.sln.

Importante

As personalizações baseadas em JSLink (renderização do lado do cliente) não têm suporte nas experiências modernas. Isso inclui listas e bibliotecas modernas, inclusive suporte para JSLink nas Web Parts da Exibição de Lista das páginas modernas. A renderização do lado do cliente tem suporte nas experiências clássicas do SharePoint Online ou no local.

Você pode usar um pouco JavaScript no lado do cliente para personalizar a renderização de web parts, a maioria dos tipos de campos (colunas) e alguns outros controles ao atribuir um arquivo JavaScript para a propriedade JSLink do controle, como SPField.JSLink. Você também pode adicionar lógica de validação do lado cliente dessa maneira. Neste artigo, você personaliza a renderização de um campo em uma lista do Suplemento do SharePoint para orientação de funcionários usando a renderização no lado do cliente.

Observação

Se o usuário final estiver com o JavaScript desabilitado em seu navegador, o SharePoint retornará para renderização e validação no lado do servidor.
A propriedade JSLink não tem suporte nas listas Pesquisa ou Eventos. Um calendário do SharePoint é uma Lista de Eventos.

Criar e registrar o JavaScript

No Gerenciador de Soluções, clique com o botão direito do mouse no nó Scripts e selecione Adicionar>Novo Item>Web.
Selecione o Arquivo JavaScript e dê o nome itOrientationStageRendering.js.
A renderização personalizada do campo deve ocorrer automaticamente, assim, use o código a seguir para adicionar um método anônimo no JavaScript que será executado automaticamente quando o arquivo for carregado:
```
(function () {

})();
```
No corpo desse método (entre os caracteres { }), adicione o seguinte código para criar objetos JSON (Javascript Object Notation) no contexto de substituição de renderização, os modelos no contexto e os modelos para os campos.
```
var customRenderingOverride = {};
customRenderingOverride.Templates = {};
customRenderingOverride.Templates.Fields = {
}
```
No corpo do objeto de modelo Campos, adicione o JSON a seguir.
```
"OrientationStage": { "View": renderOrientationStage }
```
- O nome da propriedade OrientationStage identifica o campo que tem a renderização personalizada.
- O valor da propriedade é outro objeto JSON.
- A propriedade View identifica o contexto da página na qual a renderização personalizada é aplicada. Nesse caso, o objeto informa o SharePoint para usar a renderização personalizada na exibição de listas. (Outras opções seriam para os formulários Editar, Novo e Exibir.)
- O valor da propriedade renderOrientationStage é o nome do método de renderização personalizada criado em uma etapa posterior.

A última coisa que o método anônimo deve fazer é informar ao gerenciador de modelos do SharePoint sobre a substituição de renderização. Adicione a seguinte linha ao final do corpo do método.

SPClientTemplates.TemplateManager.RegisterTemplateOverrides(customRenderingOverride);

Agora o método deve ter a aparência a seguir.

(function () {
  var customRenderingOverride = {};
  customRenderingOverride.Templates = {};
  customRenderingOverride.Templates.Fields = {
      "OrientationStage": { "View": renderOrientationStage }
  }

  SPClientTemplates.TemplateManager.RegisterTemplateOverrides(customRenderingOverride);
})();

Adicione o método a seguir ao arquivo. Ele define a cor do valor da coluna Estágio de Orientação como vermelho quando o valor for Not Started e como verde quando o valor for Completed. (ctx é um objeto de contexto do cliente declarado pelo script do SharePoint pronto para uso.)

function renderOrientationStage(ctx) {
  var orientationStageValue = ctx.CurrentItem[ctx.CurrentFieldSchema.Name];
  if (orientationStageValue == "Not Started")  {
      return "<span style='color:red'>" + orientationStageValue + "</span>"
  }
  else if (orientationStageValue == "Completed") {
      return "<span style='color:green'>" + orientationStageValue + "</span>"
  }
  else {
      return orientationStageValue;
  }
}

No Gerenciador de Soluções, expanda Colunas de Site e OrientationStage; em seguida, abra o arquivo elements.xml.
Para informar ao SharePoint para usar seu JavaScript personalizado, adicione o novo atributo JSLink ao elemento Campo e atribua a seguinte URL como seu valor: ~site/Scripts/OrientationStageRendering.js.

Observação

A propriedade JSLink sempre é um arquivo, não um método. Não há como dizer ao SharePoint qual método executar e por isso que o arquivo contém um método que é executado automaticamente.

A marca de início do elemento Campo agora terá a aparência mostrada a seguir.
```
<Field
      ID="{some_guid_here}"
      Name="OrientationStage"
      Title="OrientationStage"
      DisplayName="Orientation Stage"
      Description="The current orientation stage of the employee."
      Type="Choice"
      Required="TRUE"
      Group="Employee Orientation"
      JSLink="~site/Scripts/OrientationStageRendering.js">

```

Abra a página Default.aspx e adicione o código a seguir como o último filho do elemento asp:Content que tem ContentPlaceHolderID definido como PlaceHolderMain.

<p><asp:HyperLink runat="server" NavigateUrl="JavaScript:window.location = _spPageContextInfo.webAbsoluteUrl + '/Lists/NewEmployeesInSeattle/AllItems.aspx';"
      Text="List View Page for New Employees in Seattle" /></p>

Executar e testar o suplemento

Use a tecla F5 para implantar e executar o suplemento. O Visual Studio faz uma instalação temporária do suplemento em seu site de teste do SharePoint e executa o suplemento imediatamente.
A renderização no lado de cliente que você configurou só afeta a renderização de campo na página de exibição de lista e não na exibição da web part da lista que colocamos na página inicial. Isso ocorre porque a web part usa, por padrão, a renderização no lado do servidor. Há maneiras para reverter isso, mas são muito avançadas para este exemplo simples. Portanto, para ver a renderização no lado do cliente em ação, selecione o link na parte inferior da Página de exibição da lista de Novos Funcionários em Seattle.
Quando a página de exibição de lista for aberta, defina o valor Estágio de Orientação de alguns itens como Não Iniciado e defina os outros como Concluído para ver a renderização de cores personalizadas.

Figura 1. Listar com renderização personalizada do lado do cliente
Para encerrar a sessão de depuração, feche a janela do navegador ou interrompa a depuração no Visual Studio. Sempre que você selecionar F5, o Visual Studio retirará a versão anterior do suplemento e instalará a versão mais recente.
Você lidará com esse suplemento e com a solução do Visual Studio em outros artigos, e recomenda-se retirar o suplemento uma última vez quando for deixar de trabalhar com ele por algum tempo. Clique com botão direito do mouse no projeto no Gerenciador de Soluções e escolha Retirar.

Próximas etapas

No próximo artigo desta série, você verá como criar um botão personalizado da faixa de opções no host da Web de um Suplemento do SharePoint.

Compartilhar via

Adicionar uma renderização personalizada do lado do cliente a um Suplemento do SharePoint hospedado pelo SharePoint

Criar e registrar o JavaScript

Executar e testar o suplemento

Próximas etapas

Recursos adicionais