Usar as APIs do SharePoint JavaScript para trabalhar com os dados do SharePoint

Artigo
04/08/2023

Esse é o décimo 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 no SharePoint | Próximas etapas.

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 Ins_Tutorials de hosted_Add SharePoint_SP e abrir o arquivo BeforeJSOM.sln.

Apesar de os suplementos do SharePoint hospedados pelo SharePoint não conseguirem ter o código do lado do servidor, você ainda poderá ter a interação de lógica de negócios e tempo de execução com componentes do SharePoint em um suplemento do SharePoint hospedado pelo SharePoint usando JavaScript e a biblioteca de modelos de objeto cliente JavaScript do SharePoint. Vamos chamá-lo de JSOM. Perceba o "M" no final. Não confunda isso com JSON (JavaScript Object Notation). Neste artigo, use o modelo de objeto JavaScript para localizar e remover itens antigos da lista de novos funcionários em Seattle.

Criar o JavaScript e um botão para invocá-lo

Verifique se a etapa a seguir, do primeiro tutorial desta série, foi concluída:

Abra o arquivo /Pages/Default.aspx na raiz do projeto. Entre outras coisas, esse arquivo gerado carrega um ou dois scripts hospedados no SharePoint: sp.runtime.js e sp.js. A marcação para carregar esses arquivos no controle Conteúdo próximo ao topo do arquivo tem a ID PlaceHolderAdditionalPageHead. A marcação varia dependendo da versão das Microsoft Office Developer Tools para Visual Studio que você está usando.

Esta série de tutoriais requer que ambos os arquivos sejam carregados e que isso seja feito com marcas HTML <script> comuns, não com marcas <SharePoint:ScriptLink>. Certifique-se de que as linhas a seguir estejam no controle PlaceHolderAdditionalPageHead, imediatamente acima da linha <meta name="WebPartPageExpansion" content="full" />:
```
<script type="text/javascript" src="/_layouts/15/sp.runtime.js"></script>
<script type="text/javascript" src="/_layouts/15/sp.js"></script>
```
Procure no arquivo qualquer marcação que também carregue um ou o outro desses arquivos e remova a marcação redundante. Salve e feche o arquivo.
No nó Scripts no Gerenciador de Soluções, talvez já haja um arquivo Add-in.js. Se não houver, mas existir um arquivo App.js, clique com o botão direito do mouse em Add.js e renomeie-o para Add-in.js. Se não houver um Add-in.js ou App.js, crie um com estas etapas:
1. Clique com botão direito no nó Scripts e escolha Adicionar>Novo Item>Web.
2. Selecione o arquivo JavaScripte o nomeie Add-in.js.
3. Atualize o código na sua página aspx para referenciar o arquivo JS correto, altere-o de:
```
<script type="text/javascript" src="../Scripts/App.js"></script>
```
  para
```
<script type="text/javascript" src="../Scripts/Add-in.js"></script>
```
Abra Add-in.js e exclua seu conteúdo, se houver algum.
Adicione as seguintes linhas ao arquivo.
```
'use strict';

  var clientContext = SP.ClientContext.get_current();
  var employeeList = clientContext.get_web().get_lists().getByTitle('New Employees In Seattle');
  var completedItems;
```
Observe o seguinte sobre este código:
- A linha 'use strict'; garante que o tempo de execução do JavaScript no navegador lance uma exceção se você usar acidentalmente certas práticas inadequadas em JavaScript.
- A variável clientContext contém um objeto SP.ClientContext que faz referência ao site do SharePoint. Todo o código JSOM começa criando ou obtendo uma referência para um objeto desse tipo.
- A variável employeeList contém uma referência à instância da lista Novos Funcionários em Seattle.
- A variável completedItems contém os itens da lista que o script excluirá: os itens cujo campo OrientationStage esteja definido como Concluído.
Para minimizar mensagens entre o navegador do cliente e o servidor do SharePoint, o JSOM usa um sistema em lotes. Apenas uma função, SP.ClientContext.executeQueryAsync, envia mensagens para o servidor (e recebe respostas).

Chamadas para as APIs JSOM que vêm entre chamadas executeQueryAsync são reunidas e enviadas para o servidor em um lote na próxima vez executeQueryAsync é chamado. No entanto, não é possível chamar um método de um objeto JSOM, a menos que o objeto tenha sido trazido para o cliente em uma chamada anterior do executeQueryAsync.

Seu script chamará o método SP.ListItem.deleteObject de cada item concluído na lista, para que ele precise fazer duas chamadas de executeQueryAsync; uma para obter uma coleção dos itens de lista concluído e, em seguida, um segundo para agrupar as chamadas de deleteObject e enviá-las para o servidor para execução.

Comece criando um método para obter os itens da lista do servidor. Adicione o código a seguir a esse arquivo.
```
function purgeCompletedItems() {

  var camlQuery = new SP.CamlQuery();
  camlQuery.set_viewXml(
    '<View><Query><Where><Eq>' +
      '<FieldRef Name=\'OrientationStage\'/><Value Type=\'Choice\'>Completed</Value>' +
    '</Eq></Where></Query></View>');
  completedItems = employeeList.getItems(camlQuery);
}
```
Quando essas linhas são enviadas para o servidor e executadas lá, elas criam uma coleção de itens de lista, mas o script deve trazer essa coleção para o cliente. Isso é feito com uma chamada para a função SP.ClientContext.load, portanto, adicione a linha a seguir ao final do método.
```
clientContext.load(completedItems);
```
Adicione uma chamada de executeQueryAsync. Esse método tem dois parâmetros, ambos são funções de retorno de chamada. O primeiro será executado se o servidor executar a todos os comandos no lote com êxito. O segundo será executado se o servidor falhar por qualquer motivo. Você cria essas duas funções em etapas posteriores. Adicione a linha a seguir ao final do método.
```
clientContext.executeQueryAsync(deleteCompletedItems, onGetCompletedItemsFail);
```
Por fim, adicione a linha a seguir ao final do método.
```
return false;
```
Ao retornar false para o botão ASP.NET que chamará a função, cancelaremos o comportamento padrão dos botões ASP.NET que é recarregar a página. Um recarregamento da página poderia provocar uma recarga do arquivo Add-in.js. Por sua vez, isso reinicializaria o clientContext objeto.

Se esse recarregamento for concluído entre o momento e que oexecuteQueryAsync envia a solicitação e o momento em que o servidor do SharePoint retorna clientContext a resposta, o objeto original não tem mais a existência para processar a resposta. A função seria interrompida sem o êxito ou falha dos retornos de chamadas executados. (O comportamento exato pode variar dependendo do navegador).
Adicione a seguinte função deleteCompletedItems ao arquivo. Esta é a função que é executada se purgeCompletedItems a função for bem-sucedida. Observe o seguinte sobre este código:
- O método SP.ListItem.get_id retorna a ID do item da lista. Cada item da matriz é um objeto SP.ListItem.
- O método SP.List.getItemById retorna o SP.ListItem objeto com a ID especificada.
- O método SP.ListItem.deleteObject marca o item de lista a ser excluído no servidor quando a chamada para executeQueryAsync é feita. Os itens da lista devem ser copiados da coleção que é enviada do servidor para uma matriz, antes que possam ser excluídas. Se o script chamado métododeleteObject para cada item diretamente no loop while, o JavaScript emitiria um erro informando que o comprimento da coleção está sendo alterado enquanto a enumeração está em andamento.
A mensagem de erro não é literalmente verdadeira porque o item não é excluído de nada até as chamadas deleteObject serem agrupadas e enviadas para o servidor, mas o JSOM foi projetado para imitar a exceção que ocorreria no servidor (onde o código não deve alterar o tamanho da coleção enquanto a coleção está sendo enumerada). No entanto, matrizes têm um tamanho fixo, portanto, chamar deleteObject em um item em uma matriz exclui o item da lista, mas não altera o tamanho da matriz.
```
function deleteCompletedItems() {

  var itemArray = new Array();
  var listItemEnumerator = completedItems.getEnumerator();

  while (listItemEnumerator.moveNext()) {
    var item = listItemEnumerator.get_current();
    itemArray.push(item);
  }

  var i;
  for (i = 0; i < itemArray.length; i++) {
    itemArray[i].deleteObject();
  }

  clientContext.executeQueryAsync(onDeleteCompletedItemsSuccess, onDeleteCompletedItemsFail);
}
```
Adicione a seguinte função onDeleteCompletedItemsSuccess ao arquivo. Esta é a função que é executada se os itens concluídos forem excluídos com êxito (ou se não houver itens concluídos na lista).

A linha location.reload(true); faz com que a página seja recarregada a partir do servidor. Isso é uma comodidade porque a Web Part de exibição de lista na página ainda mostra os itens concluídos até que a página seja atualizada. O arquivo Add-in.js também é recarregado, mas isso não causa um problema porque não o faria de uma maneira que interrompa uma função JavaScript contínua.
```
function onDeleteCompletedItemsSuccess() {
  alert('Completed orientations have been deleted.');
  location.reload(true);
}
```

Adicione ao arquivo as duas funções de retorno de chamada em caso de falha.

// Failure callbacks

function onGetCompletedItemsFail(sender, args) {
  alert('Unable to get completed items. Error:' + args.get_message() + '\n' + args.get_stackTrace());
}

function onDeleteCompletedItemsFail(sender, args) {
  alert('Unable to delete completed items. Error:' + args.get_message() + '\n' + args.get_stackTrace());
}

Abra o arquivo default.aspx e localize o elemento asp:Content com a ID PlaceHolderMain.
Adicione a marcação a seguir entre o elemento WebPartPages:WebPartZone e o primeiro dos dois elementos asp:Hyperlink. O valor do manipulador OnClientClick é return purgeCompletedItems(), em vez de apenas purgeCompletedItems(). O false que é retornado pela função instrui o ASP.NET a não a recarregar a página.
```
<p><asp:Button runat="server" OnClientClick="return purgeCompletedItems()" ID="purgecompleteditemsbutton" Text="Purge Completed Items" /></p>
```
Recrie o projeto no Visual Studio.
Para minimizar a necessidade de definir manualmente o Estágio de Orientação dos itens de lista para Concluído durante o teste do suplemento, abra o arquivo elements.xml da instância de lista NewEmployeesInSeattle (não o elements.xml do modelo da lista NewEmployeeOrientation) e adicione a marcação <Field Name="OrientationStage">Completed</Field> como o último filho a um ou mais dos elementos Row.

Confira a seguir um exemplo de como deve ser a aparência do elemento Rows.
```
<Rows>
  <Row>
    <Field Name="Title">Tom Higginbotham</Field>
    <Field Name="Division">Manufacturing</Field>
    <Field Name="OrientationStage">Completed</Field>
  </Row>
  <Row>
    <Field Name="Title">Satomi Hayakawa</Field>
    <Field Name="OrientationStage">Completed</Field>
  </Row>
  <Row>
    <Field Name="Title">Cassi Hicks</Field>
  </Row>
  <Row>
    <Field Name="Title">Lertchai Treetawatchaiwong</Field>
  </Row>
</Rows>
```

Executar e testar o suplemento

Habilite pop-ups no navegador usado pelo Visual Studio para a depuração.
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 página inicial do suplemento abre e há um ou mais itens na lista com o Estágio de Orientação em Concluído.

Figura 1. Lista antes da limpeza dos itens concluídos
Quando a página inicial do suplemento tiver sido carregada, selecione o botão Limpar Itens Concluídos. Se a operação for concluída (você não recebe uma mensagem de falha), todos os itens Concluídos serão excluídos, e você verá uma janela pop-up que diz que a orientação concluída foi excluída.
Feche a janela pop-up. A página é recarregada, e os itens Concluídos não estarão mais na Web Part de exibição de lista.

Figura 2. Lista após limpeza de itens concluídos
Para encerrar a sessão de depuração, feche a janela do navegador ou interrompa a depuração no Visual Studio. Sempre que você seleciona F5, o Visual Studio retira a versão anterior do suplemento e instala 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ê adicionará JavaScript a uma página no site do suplemento que usa dados do SharePoint no host da Web: Utilizar os dados do host da Web do JavaScript no site do suplemento.

Partilhar via

Usar as APIs do SharePoint JavaScript para trabalhar com os dados do SharePoint

Criar o JavaScript e um botão para invocá-lo

Executar e testar o suplemento

Próximas etapas

Recursos adicionais