Utiliser des données web hôte de JavaScript dans le complément web

Cet article est le septième d’une série sur les concepts de base du développement de compléments SharePoint hébergés par SharePoint. Vous devez tout d’abord avoir pris connaissance de la rubrique Compléments SharePoint et des articles précédents de la série, disponibles dans la rubrique Commencer à créer des compléments SharePoint hébergés par SharePoint | Étapes suivantes.

Notes

Si vous avez suivi cette série sur les compléments hébergés par SharePoint, vous disposez d'une solution Visual Studio que vous pouvez continuer à utiliser avec cette rubrique. Vous pouvez également télécharger le référentiel à l'adresse SharePoint_SP-hosted_Add-Ins_Tutorials et ouvrir le fichier BeforePage.sln.

Par défaut, SharePoint est conçu pour empêcher le code JavaScript d'un complément d'avoir accès à des données se trouvant dans d'autres sites web SharePoint sur la batterie. Cela permet d'empêcher que le script d'un complément malveillant ait accès à des données sensibles. Toutefois, un complément doit souvent avoir accès au site web hôte, ou à d'autres sites web d'une même collection de sites en tant que site web hôte.

Pour autoriser ce scénario dans votre complément, vous devez suivre deux étapes :

  • Vous demandez l'autorisation au site web hôte dans le fichier manifeste de votre complément. L'utilisateur qui installe le complément est invité à accorder cette autorisation. S’il ne le fait pas, le complément ne peut pas être installé.
  • Utilisez un objet SP. AppContextSite à la place d’un objet SP. ClientContext pour que JSOM appelle le site web hôte. Cet objet permet au complément d’obtenir un objet de contexte pour les sites web autre que le site web de complément, mais uniquement pour les sites web au sein de la même collection de sites. (Il existe également un moyen d’accéder à un site web de l’abonnement SharePoint Online [ou de l’application web SharePoint locale], mais il s’agit d’une méthode plus complexe.)

Dans cet article, vous utilisez le JSOM pour trouver les orientations qui n'ont pas encore commencé et pour veiller à ce qu'elles soient programmées dans un calendrier du site web hôte.

Préparation du calendrier de site web hôte

Ouvrez le site web hôte (votre site web de test pour les développeurs) et vérifiez qu’il contient un calendrier nommé Planification d’orientation des employés et qu’il contient un seul événement : Orient Cassie Hicks. Si ce n’est pas le cas, procédez comme suit :

  1. Sur la page d’accueil du site, sélectionnez Contenu du site > Ajouter un complément > Calendrier.

  2. Dans la boîte de dialogue Ajout de calendrier, saisissez Programme d’orientation de l’employé comme nom, puis sélectionnez Créer.

  3. Quand le calendrier s’ouvre, placez le curseur sur une date jusqu’à ce que le lien Ajouter apparaisse, puis sélectionnez Ajouter.

  4. Dans la boîte de dialogue Programme d’orientation de l’employé - Nouvel élément, entrez Orientation Charline Leblanc comme titre. Dans les autres champs, laissez les valeurs par défaut, puis sélectionnez Enregistrer.

    Le calendrier doit ressembler à l’exemple suivant :

    Figure 1. Calendrier personnalisé

    Calendrier intitulé Planification de l’orientation de l’employé avec un élément le 1er juin indiquant « Orientation Charline Leblanc »

<a name="create-the-javascript-and-a-button-to-invoke-it">Créer le JavaScript et un bouton pour appeler

  1. Ouvrez le fichier Add-in.js dans le nœud Scripts dans l’Explorateur de solutions.

  2. Ajoutez les déclarations suivantes sous la déclaration de completedItems.

    var notStartedItems;
    var calendarList;
    var scheduledItems;
    
    • notStartedItems fait référence aux éléments de la liste Nouveaux employés à Seattle dont l’Étape de l’orientation est actuellement définie sur Non démarré.
    • calendarList fait référence au calendrier créé sur le site web hôte.
    • scheduledItems fait référence à une collection d’éléments du calendrier.
  3. Quand vous exécutez un complément SharePoint, SharePoint appelle sa page de démarrage et ajoute des paramètres de requête à l’URL de la page de démarrage. SPHostUrl est l’un de ces paramètres, qui correspond à l’URL du site web hôte. Le complément a besoin de ces informations pour appeler les données du site web hôte. En haut du fichier Add-in.js, sous la déclaration de variable de scheduledItems, ajoutez la ligne suivante.

    var hostWebURL = decodeURIComponent(getQueryStringParameter(&quot;SPHostUrl"));
    

    Tenez compte des informations suivantes :

    • getQueryStringParameter est une fonction utilitaire que vous créez à l’étape suivante.
    • decodeUriComponent est une fonction JavaScript standard qui annule l’encodage URI réalisé par SharePoint sur les paramètres de requête ; par exemple, une barre oblique codée « %2F » est transformée en « / ».
  4. Ajoutez le code suivant en bas du fichier. Cette fonction peut être utilisée pour lire les paramètres de requête.

    // 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];
          }
        }
    }
    
  5. Ajoutez la fonction suivante au fichier Add-in.js quelque part au-dessus de la section de rappels d’échec.

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

    Tenez compte des informations suivantes :

    • Il est presque identique à la méthode de requête de liste qui obtient les éléments Terminé, sauf qu’il obtient les éléments Non démarré au lieu des éléments Terminé. Seuls les éléments Non démarré nous intéressent, car le script suppose qu’une orientation doit être programmée quand elle n’est plus à l’étape Non démarré.
    • Vous créez les deux méthodes de rappel dans l’appel executeQueryAsync au cours des étapes suivantes.
  6. Ajoutez la fonction suivante au fichier Add-in.js sous la fonction précédente. Notez qu’elle utilise l’objet hostWebContext pour identifier la liste interrogée.

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

    Notes

    Notez qu’aucune balise de requête n’est ajoutée à la requête CAML. Le fait que l’objet requête ne contienne aucune requête réelle vous garantit que tous les éléments de la liste sont récupérés. Si la liste est volumineuse, l’envoi de requête au serveur peut être excessivement long. Dans ce cas, nous aimerions trouver un autre moyen d’atteindre notre objectif. Cependant, si vous disposez d’une liste très courte comme c’est le cas dans cette rubrique (les listes de calendriers sont presque toujours courtes), le fait d’obtenir la liste complète pour l’itérer sur le client nous permettra de réduire le nombre d’appels vers le serveur, c’est-à-dire les appels de l’élément executeQueryAsync.

  7. Ajoutez la fonction suivante au fichier.

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

    Tenez compte des informations suivantes :

    • La méthode vérifie si le titre d’un élément Non démarré dans la liste Nouveaux employés à Seattle, qui est le nom d’un employé, est indiqué dans le titre d’un événement dans le calendrier Programme d’orientation de l’employé. Il est supposé que toutes les entrées du calendrier sont créées avec le nom complet de l’employé dans le titre de l’événement.

    • Si aucun événement déjà présent dans le calendrier ne correspond à un élément non démarré, le script crée un élément de calendrier pour l'élément non démarré.

    • JSOM utilise un objet ListItemCreationInformation non activable au lieu d’un objet SPListItem pour réduire la taille de la charge utile qui est envoyée au serveur SharePoint.

    • Les deux champs DateHeure du nouvel événement de calendrier sont définis sur des jours du mois où cet article a été rédigé : 2015-06. Modifiez ces dates pour qu'elles correspondent à un jour du mois et de l'année en cours, de sorte à trouver les éléments sans revenir en arrière dans votre calendrier.

    • Si des éléments non démarrés ne sont pas programmés, le premier est programmé pour le 10 du mois. Chaque élément imprévu supplémentaire est programmé pour le jour suivant. Il est donc supposé qu'il n'existera pas plus d'éléments non programmés que de jours dans le mois, de façon à ne pas obtenir des jours inexistants, comme « 32 ».

    • La majorité de ce code est un code JavaScript standard. Il existe des commentaires pour les lignes qui utilisent SharePoint JSOM.

  8. Ajoutez le gestionnaire de réussite suivant qui est appelé lorsque les éléments imprévus précédemment sont ajoutés au calendrier.

    function onScheduleItemsSuccess() {
      alert('There was one or more unscheduled orientations and they have been added to the '
                + 'Employee Orientation Schedule calendar.');
    }
    
  9. Ajoutez les fonctions d’échec suivantes à la section de rappels d’échec du fichier.

      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());
    }
    
  10. Ouvrez le fichier default.aspx et recherchez l’élément asp:Content avec l’ID PlaceHolderMain.

  11. Ajoutez les balises suivantes juste en dessous du bouton purgeCompletedItems.

    <p><asp:Button runat="server" OnClientClick="return ensureOrientationScheduling()"
                   ID="ensureorientationschedulingbutton"
                   Text="Ensure all items are on the Calendar" /></p>
    
  12. Régénérez le projet dans Visual Studio.

  13. Pour réduire la nécessité de définir manuellement l’étape d’orientation d’éléments de liste sur Non démarré lors du test du complément, ouvrez le fichier elements.xml pour l’instance de liste NewEmplescenceInSeattle (et non le fichier elements.xml pour le modèle de liste NewEmployeeOrientation), et assurez-vous que l’étape d’orientation valeur pour au moins trois des éléments ligne, y compris la ligne de Cassie Hicks, aura la valeur Non démarré. Étant donné qu’il s’agit de la valeur par défaut, le moyen le plus simple consiste à s’assurer qu’il n’existe aucun élément Field pour OrientationStage pour les trois lignes (ou plus).

    Voici un exemple de la façon dont l’élément Rows doit se présenter.

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

Spécifier les autorisations sur le site web hôte requises par le complément

Votre complément dispose automatiquement de l'autorisation Contrôle total sur son site web de complément, c'est pourquoi jusqu'à maintenant vous n'avez pas dû spécifier les autorisations dont il avait besoin. Toutefois, vous devez demander expressément des autorisations au site web hôte pour interagir avec ses données. Le complément Orientation des employés a besoin d'autorisations pour ajouter des éléments au calendrier du site web hôte.

  1. Dans l' Explorateur de solutions, ouvrez le fichier appManifest.xml.

  2. Dans le concepteur de manifeste, ouvrez l’onglet Autorisations.

  3. Dans la ligne supérieure de la colonne Portée, sélectionnez Liste dans la liste déroulante.

  4. Dans la colonne Autorisation, sélectionnez Gérer.

  5. Si la colonne Propriétés est vide, le complément demande une autorisation d’accès en écriture pour chaque liste du site web hôte. Nous vous recommandons de limiter les compléments aux autorisations dont ils ont besoin. Dans le manifeste de complément, il est impossible de limiter les autorisations à une instance de liste spécifique, mais il est possible de limiter le complément aux instances de liste reposant sur un modèle de liste de base spécifique. Le modèle de liste de base d’un calendrier est la liste Events dont l’ID numérique est 106.

    Sélectionnez la cellule Propriétés sur la même ligne pour afficher le bouton Modifier dans la cellule. La liste des autorisations devrait alors ressembler à ceci :

    Figure 2. Liste des autorisations avec le bouton Modifier affiché

    Liste des autorisations figurant dans l’onglet Autorisations dans le concepteur de manifeste de complément Visual Studio, où le bouton Modifier apparaît dans la cellule de la colonne Propriétés.

  6. Sélectionnez Modifier pour ouvrir la boîte de dialogue Propriétés.

  7. Sous Nom, choisissez la propriété BaseTemplateId et attribuez-lui la valeur 106. Voici à quoi ressemble la boîte de dialogue :

    Figure 3. Boîte de dialogue Propriétés des autorisations de liste

    Boîte de dialogue Propriétés pour les autorisations de liste dans Visual Studio avec le nom de la propriété défini sur « ID de liste de base » et la valeur sur « 106 »

  8. Sélectionnez OK. L’onglet Permissions doit maintenant ressembler à ce qui suit.

    Figure 4. Onglet Autorisations du concepteur de manifeste de complément dans Visual Studio

    Onglet Autorisations du concepteur de manifeste de complément dans Visual Studio montrant que le complément veut l’autorisation Gérer pour les listes dont le type de base est 106.

Exécuter et tester le complément

  1. Assurez-vous que le calendrier du site web hôte est préparé comme décrit plus haut dans cet article. Il doit comporter un seul événement, appelé Orient Cassi Hicks.

  2. Activez les fenêtres contextuelles dans le navigateur utilisé par Visual Studio au moment du débogage.

  3. Utilisez la touche F5 pour déployer et exécuter votre complément. Visual Studio effectue une installation temporaire du complément sur votre site SharePoint de test et exécute immédiatement celui-ci.

  4. Le formulaire de consentement d’autorisation s’ouvre au moment où vous pouvez accorder au complément l’autorisation dont il a besoin. Une liste déroulante apparaît sur la page où vous pouvez choisir un calendrier sur le site web hôte. Sélectionnez Programme d’orientation de l’employé, puis Approuver.

    Figure 5. Invite de consentement du complément SharePoint

    Invite de consentement de complément SharePoint avec une brève description des autorisations dont le complément a besoin et des boutons pour « Approuver » ou « Annuler »

  5. Quand la page de démarrage du complément est chargée, sélectionnez le bouton S’assurer que les éléments sont programmés.

    Figure 6. Page d’accueil de l’Orientation de l’employé avec un nouveau bouton

    Page d’accueil Orientation de l’employé avec un nouveau bouton dont l’étiquette est « S’assurer que les éléments sont programmés »

  6. Si l'une des fonctions de rappel d'échec est exécutée, l'alerte du message d'erreur créée par vos fonctions de rappel s’affiche. Sinon, vous verrez le message de réussite créé par le rappel de succès final : Au moins une orientation non programmée a été détectée et ajoutée au calendrier Programme d'orientation des employés..

  7. Accédez au calendrier Programme d’orientation de l’employé sur le site web hôte. Par exemple, sélectionnez le lien de navigation vers la page d’accueil de votre site de développeur, puis Contenu du site. Sélectionnez la vignette Programme d’orientation de l’employé (et non la vignette Orientation de l’employé).

    Le calendrier doit ressembler à ce qui suit. Le script a détecté qu'il existait déjà un événement pour Charline Leblanc, c'est pourquoi il n'en a pas créé un deuxième pour elle. Il a toutefois créé des événements pour les deux autres employés dont l'orientation était non démarrée. Il n'a pas non plus créé d'événement pour l'employé dont l'orientation n'était plus non démarrée.

    Figure 7. Affichage du calendrier après l’ajout de deux événements

    Calendrier d’orientation des employés avec l’ajout d’événements pour l’orientation de 2 employés le 10 et le 11 du mois

  8. Supprimez bien les deux nouveaux événements du calendrier avant de sélectionner à nouveau S’assurer que les éléments sont programmés.

  9. Pour mettre fin à la session de débogage, fermez la fenêtre du navigateur ou arrêtez le débogage dans Visual Studio. Chaque fois que vous appuyez sur F5, Visual Studio retire la version précédente du complément et installe la plus récente.

  10. Vous allez travailler avec ce complément et la solution Visual Studio dans d'autres articles. Il est donc recommandé de retirer le complément une dernière fois lorsque vous avez terminé de travailler et n'allez pas le réutiliser pendant un moment. Cliquez avec le bouton droit sur le projet dans l' Explorateur de solutions et sélectionnez Retirer.

Étapes suivantes

Poursuivre le travail avancé dans les Compléments SharePoint hébergés par SharePoint :