Créer une extension de carte adaptative avec une action de géolocalisation

Modèle d’un projet d’extension de carte adaptative

Créez un répertoire de projet pour votre projet et modifiez votre dossier actuel en répertoire.

Créez un nouveau projet en exécutant le Yeoman Microsoft Office SharePoint Online Generator à partir du nouveau répertoire que vous avez créé :

yo @microsoft/sharepoint

Lorsque vous y êtes invité, entrez les valeurs suivantes (sélectionnez l’option par défaut pour toutes les invites qui ne sont pas mentionnées ci-dessous):

• Quel est le nom de votre solution ? géolocalisation-didacticiel
• Quel type de composant côté client créer? Extension de carte adaptative
• Quel modèle voudriez-vous utiliser ? Modèle de texte principal
• Quel est le nom de votre extension de carte adaptative? Géolocalisation

À ce stade, Yeoman installe les dépendances requises et crée la structure des fichiers de la solution. Ce processus peut prendre quelques minutes.

Mettez à jour l’URL workbench hébergée de votre projet.

Lorsque vous utilisez la tâche gulp servir, par défaut, il lance un navigateur avec l’URL workbench hébergée spécifiée dans votre projet. L’URL par défaut du workbench hébergé dans un nouveau projet pointe vers une URL non valide.

• Recherchez et ouvrez le fichier ./config/serve.json dans votre projet.

• Recherchez la propriété initialPage:

  {
    "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
    "port": 4321,
    "https": true,
    "initialPage": "https://enter-your-SharePoint-site/ _layouts/workbench.aspx"
  }
  

• Remplacez le domaine enter-your-SharePoint-site par l’URL de votre client SharePoint et du site que vous souhaitez utiliser pour les tests. Par exemple : https://contoso.sharepoint.com/sites/devsite/_layouts/workbench.aspx.

À ce stade, si vous faites gulp serve, la carte GeoLocation s’affiche :

Ajouter des actions de géolocalisation à votre extension de carte adaptative

À ce stade, nous avons obtenu le code généré automatiquement. À présent, essayons d’ajouter des actions de géolocalisation à l’affichage carte et aux expériences d’affichage rapide.

Nous allons créer une carte qui aura une vue de carte et une vue rapide. Dans l’affichage Carte, nous fournissons un bouton qui affiche l’emplacement actuel de l’utilisateur, et le fait de cliquer sur l’affichage carte lui-même ouvre un affichage rapide.

Dans l’affichage rapide, nous fournirons trois boutons qui effectueront les actions suivantes :

• Obtenir l’emplacement actuel de l’utilisateur
• Autoriser l’utilisateur à choisir un emplacement dans la carte
• Afficher un emplacement spécifique sur la carte

Mettre à jour les étiquettes qui apparaîtront sur la carte

Avant de commencer à ajouter les actions, nous allons d’abord mettre à jour les chaînes que vous verrez sur la carte.

Pour cela, recherchez et ouvrez le fichier suivant dans votre projet : ./src/adaptiveCardExtensions/geoLocation/loc/en-us.js

Remplacez le contenu de ce fichier par :

define([], function() {
  return {
    "PropertyPaneDescription": "Tutorial on geolocation action in ACE.",
    "TitleFieldLabel": "Geolocation",
    "Title": "GeoLocation",
    "SubTitle": "GeoLocation Actions",
    "PrimaryText": "Location Demo",
    "Description": "Demonstrating GeoLocation Capabilities",
    "ShowCurrentLocation": "My Location"
  }
});

Ensuite, recherchez et ouvrez le fichier suivant dans votre projet : ./src/adaptiveCardExtensions/geoLocation/loc/mystring.d.ts

Ajoutez les éléments suivants :

ShowCurrentLocation: string;

à l’interface IGeoLocationAdaptiveCardExtensionStrings.

Ajouter des actions dans l’affichage Carte

Comme mentionné précédemment, dans l’affichage Carte, nous allons ajouter un bouton qui affichera l’emplacement actuel de l’utilisateur et, en cliquant sur l’affichage carte, nous afficherons l’expérience d’affichage rapide.

Nous allons d’abord ajouter la fonctionnalité pour le bouton sur l’affichage carte. Pour cela, recherchez et ouvrez le fichier suivant dans votre projet : ./src/adaptiveCardExtensions/geoLocation/cardView/CardView.ts

Ici, remplacez la définition de la fonctioncardButtons par ce qui suit :

public get cardButtons(): [ICardButton] | [ICardButton, ICardButton] | undefined {
  return [
    {
      title: strings.ShowCurrentLocation,
      action: {
        type: 'VivaAction.ShowLocation'
      }
    }
  ];
}

Avec cette modification, nous avons configuré un bouton avec l’étiquette My Location et l’action de clic est VivaAction.ShowLocation, qui affiche l’emplacement actuel de l’utilisateur.

Ensuite, remplacez le contenu de la fonctiononCardSelection par ce qui suit :

public get onCardSelection(): IQuickViewCardAction | IExternalLinkCardAction | undefined {
  return {
      type: 'QuickView',
      parameters: {
        view: QUICK_VIEW_REGISTRY_ID
      }
  };
}

Cette modification implique que lorsqu’un utilisateur clique sur l’affichage carte, il doit ouvrir un affichage rapide pour lui.

Avec les modifications apportées jusqu’à présent, l’affichage de votre carte ressemblerait à ceci :

Ajouter des actions dans l’affichage rapide

Dans l’affichage rapide, nous allons introduire des boutons pour 3 actions :

• Obtenir l’emplacement actuel de l’utilisateur
• Autoriser l’utilisateur à choisir un emplacement dans la carte
• Afficher un emplacement spécifique sur la carte (pour notre exemple, nous allons afficher le mont Everest)

En plus de ceux-ci, nous disposerons de deux blocs de texte pour afficher Latitude et Longitude, qui afficheront les coordonnées respectives lors de l’exécution de l’action VivaAction.GetLocation (plus d’informations plus loin).

Nous allons d’abord définir le modèle de l’affichage rapide. Pour cela, recherchez et ouvrez le fichier suivant dans votre projet : ./src/adaptiveCardExtensions/geoLocation/quickView/template/QuickViewTemplate.json

Remplacez le contenu de ce fichier par ce qui suit :

{
  "schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.2",
  "body": [
    {
      "type": "TextBlock",
      "text": "${latitude}"
    },
    {
      "type": "TextBlock",
      "text": "${longitude}"
    }
  ],
  "actions": [
    {
      "title": "Choose location on map",
      "type": "VivaAction.GetLocation",
      "parameters": {
        "chooseLocationOnMap": true
      }
    },
    {
      "title": "Get my location",
      "type": "VivaAction.GetLocation"
    },
    {
      "title": "Show custom location",
      "type": "VivaAction.ShowLocation",
      "parameters": {
        "locationCoordinates": {
          "latitude": 27.98884062493244,
          "longitude": 86.9249751
        }
      }
    }
  ]
}

Avec cela, nous fournissons deux blocs de texte pour afficher les Latitude et Longitude de l’emplacement que nous obtenons via VivaAction.GetLocation. En plus de ces actions, nous avons décrit trois actions de géolocalisation.

Après avoir ajouté ces actions, votre affichage rapide se présente comme suit :

Configurer l’état de notre extension de carte adaptative

Jusqu’à présent, nous avons créé l’affichage carte et l’affichage rapide. Si vous effectuez une gulp serve à ce stade, vous pourrez effectuer les actions décrites ci-dessus.

Mais maintenant, allons un peu plus loin.

Nous souhaitons maintenant afficher les coordonnées de l’emplacement actuel de l’utilisateur ou de l’emplacement choisi par l’utilisateur dans l’affichage rapide lorsque les actions respectives sont exécutées.

Pour cela, nous allons tirer parti des deux blocs de texte que nous avons introduits précédemment dans le fichier QuickViewTemplate.json

Pour ce faire, nous allons d’abord introduire de nouveaux états. Recherchez et ouvrez d’abord le fichier suivant dans votre projet : ./src/adaptiveCardExtensions/geoLocation/GeoLocationAdaptiveCardExtension.ts

Ici, ajoutez les states suivantes à l’interface IGeoLocationAdaptiveCardExtensionState :

latitude: string;
longitude: string;

Ensuite, dans la fonction onInit, remplacez this.state={} par

this.state = {
  latitude: 'TBD',
  longitude: 'TBD'
};

Nous allons maintenant également apporter des modifications similaires dans l’affichage rapide.

Recherchez et ouvrez le fichier suivant dans votre projet : ./src/adaptiveCardExtensions/geoLocation/quickView/QuickView.ts

Ajoutez les propriétés suivantes à l’interface IQuickViewData :

latitude: string;
longitude: string;

puis ajoutez les deux lignes suivantes dans l’objet retourné de data getter :

latitude: "Latitude: " + this.state.latitude,
longitude: "Longitude: " + this.state.longitude

Implémenter la fonction onAction

Jusqu’à présent, nous avons défini nos actions de géolocalisation et câblé dans nos états. Nous pouvons maintenant implémenter la fonction onAction, qui permet au développeur tiers de décider ce qu’il souhaite faire des coordonnées d’emplacement que l’utilisateur a partagées avec lui.

Pour ce faire, ouvrez le fichier QuickView.ts (./src/adaptiveCardExtensions/geoLocation/quickView/QuickView.ts) et importez l’interface IGetLocationActionArguments , comme suit :

import {IGetLocationActionArguments} from '@microsoft/sp-adaptive-card-extension-base';

Enfin, présentez la fonction onAction suivante dans la classe QuickView :

public onAction(action: IGetLocationActionArguments): void {
  if (action.type === 'VivaAction.GetLocation') {
    this.setState({
      latitude: action.location.latitude.toString(),
      longitude: action.location.longitude.toString()
    });
  }
}

Désormais, chaque fois que l’action VivaAction.GetLocation est déclenchée à partir de votre vue rapide, en fonction des paramètres passés, l’infrastructure d’extension de carte adaptative passe les coordonnées actuelles de l’utilisateur ou les coordonnées choisies par l’utilisateur au rappel onAction . Dans l’implémentation partagée ci-dessus, nous vérifions si le type de action est de type VivaAction.GetLocationet, le cas échéant, nous reproduisons l’affichage rapide en effectuant une setState, dans laquelle nous mettons à jour les blocs de texte latitude et longitude .

À ce stade, vous pouvez réexécuter gulp serve et voir comment toutes les modifications que vous avez apportées jusqu’à présent se sont regroupées.

Et voilà ! Félicitations pour avoir créé votre extension de carte adaptative avec des actions de géolocalisation.