Trabalhar com dados do host da Web do JavaScript no site do suplemento

Artigo
04/08/2023

Este é o décimo primeiro de uma série de artigos sobre os fundamentos do desenvolvimento de Suplementos do SharePoint hospedados no SharePoint. Primeiro, você deve se familiarizar com os Suplementos do SharePoint e com os artigos anteriores desta série, os quais podem ser encontrados em Comece a criar Suplementos do SharePoint hospedados no 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 BeforeHostWebData.sln.

Por padrão, o SharePoint foi projetado para impedir que o JavaScript em um suplemento obtenha acesso aos dados em outros sites do SharePoint no farm. Isso impede que um script em um suplemento não autorizado obtenha acesso a dados confidenciais. Porém, geralmente um suplemento precisa ter acesso ao host da Web ou a outros sites no mesmo conjunto de sites do host da Web.

Há duas partes para habilitar este cenário em seu suplemento:

Você solicita permissão ao host da Web no arquivo de manifesto do suplemento do seu suplemento. O usuário que instala o suplemento é solicitado a conceder essa permissão, e o suplemento não pode ser instalado se o usuário não o fizer.
Em vez de usar um objeto SP.ClientContext para fazer chamadas JSOM ao host da Web, você usa um objeto SP.AppContextSite. Este objeto permite que o suplemento obtenha um objeto de contexto para sites que não sejam do site do suplemento, mas apenas para sites no mesmo conjunto de sites. (Há também uma maneira de obter acesso a qualquer site na assinatura do Sharepoint Online [ou um Aplicativo Web do SharePoint local], mas esse é um assunto avançado.)

Neste artigo, você usa o JSOM para encontrar as orientações que ainda não foram iniciadas e garantir que elas sejam agendadas em um calendário no host da Web.

Preparar o calendário do host da Web

Abra o host da Web (seu site de teste de desenvolvedor) e verifique se há um calendário nele chamado Cronograma de Orientação de Funcionários e se há um único evento nele: Orientar Cassie Hicks. Se não houver, execute as seguintes etapas:

Na página inicial do site, selecione Conteúdos do Site>, adicione um complemento >Calendário.
Na caixa de diálogo Adicionar Calendário, insira Cronograma de Orientação de Funcionários ao Nome e selecione Criar.
Quando o calendário abrir, coloque o cursor em qualquer data até que o link Adicionar apareça na data e selecione Adicionar.
Na caixa de diálogo Cronograma de Orientação de Funcionários - Novo Item, insira Orientar Cassi Hicks ao Título. Deixe os outros campos em seus padrões e selecione Salvar.

O calendário deve ser semelhante ao seguinte:

Figura 1. Calendário personalizado

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

Abra o arquivo Add-in.js no nó do Scripts no Gerenciador de Soluções.
Adicione as seguintes declarações sob a declaração dos completedItems.
```
var notStartedItems;
var calendarList;
var scheduledItems;
```
- O notStartedItems faz referência aos itens da lista Novos Funcionários em Seattle cujo Estágio de Orientação está Não Iniciado.
- O calendarList faz referência ao calendário criado no host da Web.
- O scheduledItems faz referência a uma coleção de itens no calendário.
Quando um Suplemento do SharePoint é executado, o SharePoint chama sua página inicial e adiciona alguns parâmetros de consulta à URL da página inicial. Um deles é SPHostUrl, que é, obviamente, a URL do host da Web. O suplemento precisa dessas informações para fazer chamadas aos dados do host da Web, portanto, próximo à parte superior do arquivo Add-in.js, logo abaixo da declaração da variável de scheduledItems, adicione a linha a seguir.
```
var hostWebURL = decodeURIComponent(getQueryStringParameter("SPHostUrl"));
```
Observe o seguinte sobre este código:
- O getQueryStringParameter é uma função de utilidade que você cria na próxima etapa.
- O decodeUriComponent é uma função JavaScript padrão que reverte a codificação URI que o SharePoint faz nos parâmetros de consulta; por exemplo, uma barra codificada, "%2F", é alterada de volta para uma "/".

Adicione o seguinte código à parte inferior do arquivo. Essa função pode ser usada para ler os parâmetros da consulta.

// Utility functions

function getQueryStringParameter(paramToRetrieve) {
    var params = document.URL.split("?")[1].split("&");
    var strParams = "";
    for (var i = 0; i < params.length; i = i + 1) {
        var singleParam = params[i].split("=");
        if (singleParam[0] == paramToRetrieve) {
            return singleParam[1];
      }
    }
}

Adicione a seguinte função ao arquivo Add-in.js em algum lugar acima da seção de retornos de chamada de falha.
```
function ensureOrientationScheduling() {

  var camlQuery = new SP.CamlQuery();
  camlQuery.set_viewXml(
      '<View><Query><Where><Eq>' +
          '<FieldRef Name=\'OrientationStage\'/><Value Type=\'Choice\'>Not started</Value>' +
      '</Eq></Where></Query></View>');
  notStartedItems = employeeList.getItems(camlQuery);

  clientContext.load(notStartedItems);
  clientContext.executeQueryAsync(getScheduledOrientations, onGetNotStartedItemsFail);
  return false;
}
```
Observe o seguinte sobre este código:
- Isso é quase idêntico ao método de consulta de lista que obtém os itens Concluídos, exceto que obtém os itens que são Não Iniciados em vez daqueles que estão Concluídos. Estamos interessados apenas nos itens Não Iniciados porque o script faz a suposição simplificada de que, se uma orientação passar do estágio Não Iniciado, ela já deve estar agendada.
- Você cria os dois métodos de retorno de chamada na chamada executeQueryAsync em etapas posteriores.
Adicione a seguinte função ao arquivo Add-in.js logo abaixo da função anterior. Observe que ele usa o objeto hostWebContext para identificar a lista que é consultada.
```
function getScheduledOrientations() {

  var hostWebContext = new SP.AppContextSite(clientContext, hostWebURL);
  calendarList = hostWebContext.get_web().get_lists().getByTitle('Employee Orientation Schedule');

  var camlQuery = new SP.CamlQuery();
  scheduledItems = calendarList.getItems(camlQuery);

  clientContext.load(scheduledItems);
  clientContext.executeQueryAsync(scheduleAsNeeded, onGetScheduledItemsFail);
}
```
Observação

Observe que nenhuma marcação de consulta é adicionada à consulta CAML. O efeito de não haver nenhuma consulta real no objeto de consulta é garantir que todos os itens da lista sejam recuperados. Se a lista for muito grande, ela pode fazer com que a solicitação ao servidor seja inaceitavelmente longa para ser executada. Nesse caso, gostaríamos de encontrar outra forma de alcançar nosso objetivo. Mas, nesta situação de exemplo, com uma lista muito pequena (e as listas de calendários quase sempre são pequenas), obter a lista inteira para que possamos iterá-la ao cliente realmente nos ajudará a minimizar o número de chamadas ao servidor; ou seja, chamadas de executeQueryAsync.

Adicione a seguinte função ao arquivo.

function scheduleAsNeeded() {

  var unscheduledItems = false;
  var dayOfMonth = '10';

  var listItemEnumerator = notStartedItems.getEnumerator();

  while (listItemEnumerator.moveNext()) {
      var alreadyScheduled = false;
      var notStartedItem = listItemEnumerator.get_current();

      var calendarEventEnumerator = scheduledItems.getEnumerator();
      while (calendarEventEnumerator.moveNext()) {
          var scheduledEvent = calendarEventEnumerator.get_current();

            // The SP.ListItem.get_item('field_name ') method gets the value of the specified field.
          if (scheduledEvent.get_item('Title').indexOf(notStartedItem.get_item('Title')) > -1) {
              alreadyScheduled = true;
              break;
          }
      }
      if (alreadyScheduled === false) {

            // SP.ListItemCreationInformation holds the information the SharePoint server needs to
            // create a list item
          var calendarItem = new SP.ListItemCreationInformation();

            // The some_list .additem method tells the server which list to add
            // the item to.
          var itemToCreate = calendarList.addItem(calendarItem);

            // The some_item .set_item method sets the value of the specified field.
          itemToCreate.set_item('Title', 'Orient ' + notStartedItem.get_item('Title'));

            // The EventDate and EndDate are the start and stop times of an event.
          itemToCreate.set_item('EventDate', '2015-06-' + dayOfMonth + 'T21:00:00Z');
          itemToCreate.set_item('EndDate', '2015-06-' + dayOfMonth + 'T23:00:00Z');
          dayOfMonth++;

            // The update method tells the server to commit the changes to the SharePoint database.
          itemToCreate.update();
          unscheduledItems = true;
      }
  }
  if (unscheduledItems) {
      calendarList.update();
      clientContext.executeQueryAsync(onScheduleItemsSuccess, onScheduleItemsFail);
  }
}

Observe o seguinte sobre este código:

O método verifica se o título de um item Não Iniciado na lista Novos Funcionários em Seattle, que é o nome de um funcionário, está presente no título de um evento no calendário do Cronograma de Orientação de Funcionários. Há uma suposição simplificada de que todas as entradas no calendário são criadas com o nome completo do funcionário no título do evento.
Se nenhum dos eventos que já estão no calendário corresponder a um item Não Iniciado, o script criará um item de calendário para o item Não Iniciado.
O JSOM usa um objeto ListItemCreationInformation leve em vez de um objeto SPListItem para minimizar o tamanho do conteúdo que é enviado ao servidor do SharePoint.
Os dois campos DataHora do novo evento do calendário são definidos para os dias do mês em que este artigo foi escrito: 2015-06. Altere essas datas para um dia do mês e ano atuais, para que você não precise voltar em seu calendário para encontrar os itens.
Se algum item Não Iniciado não estiver agendado, o primeiro será agendado para o 10º dia do mês. Cada item adicional não agendado será agendado para o dia seguinte. A suposição simplificada é que não haverão muitos itens a ponto de alguns serem agendados para dias inexistentes no mês, como "32".
A maior parte desse código é JavaScript padrão. Há comentários para as linhas que usam o JSOM do SharePoint.

Adicione o seguinte manipulador de sucesso que é chamado quando os itens não agendados anteriormente são adicionados ao calendário.

function onScheduleItemsSuccess() {
  alert('There was one or more unscheduled orientations and they have been added to the '
            + 'Employee Orientation Schedule calendar.');
}

Adicione as seguintes funções com falha à seção Retornos de chamada com falha do arquivo.

  function onGetNotStartedItemsFail(sender, args) {
    alert('Unable to get the not-started items. Error:'
        + args.get_message() + '\n' + args.get_stackTrace());
}

function onGetScheduledItemsFail(sender, args) {
    alert('Unable to get scheduled items from host web. Error:'
        + args.get_message() + '\n' + args.get_stackTrace());
}

function onScheduleItemsFail(sender, args) {
    alert('Unable to schedule items on host web calendar. 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 seguinte marcação logo abaixo do botão purgeCompletedItems.

<p><asp:Button runat="server" OnClientClick="return ensureOrientationScheduling()"
               ID="ensureorientationschedulingbutton"
               Text="Ensure all items are on the Calendar" /></p>

Recrie o projeto no Visual Studio.
Para minimizar a necessidade de definir manualmente o Estágio de Orientação dos itens da lista como Não Iniciado ao testar o suplemento, abra o arquivo elements.xml da instância de lista NewEmployeesInSeattle (não o elements.xml do modelo de lista NewEmployeeOrientation) e certifique-se de que o valor do Estágio de Orientação de pelo menos três dos elementos Linha, incluindo a linha para Cassie Hicks, terá o valor Não Iniciado. Como esse é o valor padrão, a maneira mais simples de fazer isso é garantir que não haja um elemento Campo do OrientationStage para as três (ou mais) linhas.

Veja a seguir um exemplo de como deve ser a aparência do elemento Linhas.
```
<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>
  </Row>
  <Row>
    <Field Name="Title">Cassi Hicks</Field>
  </Row>
  <Row>
    <Field Name="Title">Lertchai Treetawatchaiwong</Field>
  </Row>
</Rows>
```

Especificar as permissões para o host da Web de que o suplemento precisa

Seu suplemento tem automaticamente a permissão de controle total para seu próprio suplemento Web, portanto, até agora você não precisou especificar quais permissões ele precisa. Mas você deve solicitar especificamente permissões para que a Web do host interaja com seus dados. O suplemento orientação do funcionário precisa de permissão para adicionar itens ao calendário na Web do host.

Em Gerenciador de Soluções, abra o arquivo appmanifest.xml.
No designer de manifesto, abra a guia Permissões.
Na linha superior da coluna Escopo, selecione Lista na lista suspensa.
Na coluna Permissão, selecione Gerenciar.
Se a coluna Propriedades for deixada em branco, o complemento solicitará permissão de gravação para todas as listas no host da Web. Uma prática recomendada é limitar os suplementos apenas às permissões de que precisam. No manifesto do suplemento, não é possível limitar as permissões a uma instância de lista específica, mas é possível limitar o suplemento a apenas instâncias de lista criadas em um modelo de lista base específico. O modelo de lista base de um calendário é Eventos cuja ID numérica é 106.

Selecione a célula Propriedades da mesma linha para fazer o botão Editar aparecer na célula. Agora a lista de permissões deve ser semelhante à seguinte.

Figura 2. Lista de permissão com o botão Editar visível
Selecione Editar para abrir a caixa de diálogo Propriedades.
Defina o Nome como BaseTemplateId e o Value como 106. Agora, a caixa de diálogo deve ter a aparência a seguir.

Figura 3. Caixa de diálogo de propriedades de permissão de lista
Clique em OK. Agora, a guia Permissões deve ser semelhante à seguinte.

Figura 4. A guia Permissões do designer de manifesto de suplemento no Visual Studio

Executar e testar o suplemento

Certifique-se de que o calendário do host da Web esteja preparado conforme descrito anteriormente neste artigo. Deve haver um único evento, denominado Orientar Cassi Hicks.
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.
O formulário de consentimento de permissão é aberto, onde você pode conceder ao suplemento a permissão que ele busca. Há uma lista suspensa na página onde você pode escolher entre todos os calendários do host da Web. Selecione Cronograma de Orientação de Funcionários e selecione Confiar.

Figura 5. Solicitação de consentimento de suplemento do SharePoint
Quando a página inicial do suplemento estiver completamente carregada, selecione o botão Garantir que os Itens Estejam Agendados.

Figura 6. Home page da Orientação de funcionários com um novo botão
Se qualquer uma das funções do retorno de chamada de falha for executada, você verá o alerta de mensagem de erro criado por suas funções de retorno de chamada. Caso contrário, você verá a mensagem de sucesso criada pelo retorno de chamada com êxito final: Havia uma ou mais orientações não agendadas e elas foram adicionadas ao calendário do Cronograma de Orientação de Funcionários.
Vá para o calendário do Cronograma de Orientação dos Funcionários no host da Web. Por exemplo, selecione o link estrutural da home page do site de desenvolvedor e selecione Conteúdos do Site. Selecione o bloco Cronograma de Orientação de Funcionários (não o bloco Orientação de Funcionários).

O calendário deve ser semelhante ao seguinte. O script detectou que já havia um evento para Cassi Hicks, por isso não criou um segundo evento para ela. Ele criou eventos para os outros dois funcionários cuja orientação estava no estado Não Iniciado. Também não criou um evento para o funcionário cuja orientação passou do estado Não Iniciado.

Figura 7. Calendário após dois novos eventos adicionados
Certifique-se de excluir os dois novos eventos do calendário antes de selecionar Garantir que os Itens Estejam Agendados novamente.
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

Vá em frente para o trabalho avançado nos suplementos do SharePoint hospedados no SharePoint:

Compartilhar via