Créer des contrôles d’expérience utilisateur à l’aide de compléments hébergés par un fournisseur SharePoint

Créez des contrôles d’expérience utilisateur dans des compléments hébergés par un fournisseur SharePoint qui fonctionnent et se comportent comme des contrôles d’expérience utilisateur sur le site web hôte.

L’article décrit trois exemples qui vous montrent comment implémenter des contrôles d’expérience utilisateur dans votre complément hébergé par un fournisseur :

• Core.PeoplePicker : vous montre comment ajouter un contrôle sélecteur de personnes.

• Core.TaxonomyMenu : vous montre comment implémenter un contrôle de menu taxonomie localisable.

• Core.TaxonomyPicker : vous montre comment implémenter un contrôle sélecteur de taxonomie.

Ces exemples utilisent JavaScript et le modèle JSOM pour communiquer avec SharePoint, et utilisent la bibliothèque inter-domaines pour gérer les appels de fonction du complément au domaine du site hôte.

Contrôle Sélecteur de personnes

L’exemple Core.PeoplePicker vous montre comment implémenter un contrôle sélecteur de personnes dans un complément hébergé par un fournisseur. Lorsque l’utilisateur commence à taper un nom dans la zone de saisie de texte, le contrôle recherche des correspondances potentielles dans le magasin de profils utilisateur et les affiche dans l’interface utilisateur. Le complément affiche un contrôle sélecteur de personnes configurable et extensible qui s’exécute sur un hôte distant et interroge le magasin de profils utilisateur sur le site hôte pour qu’il corresponde aux entrées utilisateur.

Contrôle du sélecteur de Personnes

Le dossier Scripts du projet Core.PeoplePickerWeb contient des fichiers app.js et peoplepickercontrol.js (ainsi que des fichiers de ressources du sélecteur de personnes pour une prise en charge linguistique supplémentaire). Le fichier app.js extrait le contexte client à l’aide de la bibliothèque inter-domaines et raccorde le code HTML du fichier Default.aspx au contrôle sélecteur de personnes. Le fichier Default.aspx contient les <div> balises qui implémentent à la fois la zone de texte et la fonctionnalité de recherche de personnes.

<div id="divAdministrators" class="cam-peoplepicker-userlookup ms-fullWidth">
  <span id="spanAdministrators"></span>
<asp:TextBox ID="inputAdministrators" runat="server" CssClass="cam-peoplepicker-edit" Width="70"></asp:TextBox>
</div>
<div id="divAdministratorsSearch" class="cam-peoplepicker-usersearch ms-emphasisBorder"></div>
<asp:HiddenField ID="hdnAdministrators" runat="server" />

Le fichier app.js crée et configure ensuite un contrôle sélecteur de personnes.

//Make a people picker control.
//1. context = SharePoint Client Context object
//2. $('#spanAdministrators') = SPAN that will 'host' the people picker control
//3. $('#inputAdministrators') = INPUT that will be used to capture user input
//4. $('#divAdministratorsSearch') = DIV that will show the 'drop-down' of the picker
//5. $('#hdnAdministrators') = INPUT hidden control that will host resolved users
peoplePicker = new CAMControl.PeoplePicker(context, $('#spanAdministrators'), $('#inputAdministrators'), $('#divAdministratorsSearch'), $('#hdnAdministrators'));
// required to pass the variable name here!
peoplePicker.InstanceName = "peoplePicker";
// Hook up everything.
peoplePicker.Initialize();

Le contrôle sélecteur de personnes interroge l’objet ClientPeoplePickerWebServiceInterface dans la bibliothèque JSOM pour lancer des recherches pour les utilisateurs dont le nom correspond aux chaînes de caractères entrées.

if (searchText.length >= parent.GetMinimalCharactersBeforeSearching()) {
                            resultDisplay = 'Searching...';
                            if (typeof resultsSearching != 'undefined') {
                                resultDisplay = resultsSearching;
                            }

                  var searchbusy = parent.Format('<div class=\'ms-emphasisBorder\' style=\'width: 400px; padding: 4px; border-left: none; border-bottom: none; border-right: none; cursor: default;\'>{0}</div>', resultDisplay);
                            parent.PeoplePickerDisplay.html(searchbusy);
                            // Display the suggestion box.
                            parent.ShowSelectionBox();

                   var query = new SP.UI.ApplicationPages.ClientPeoplePickerQueryParameters();
                            query.set_allowMultipleEntities(false);
                            query.set_maximumEntitySuggestions(2000);
                            query.set_principalType(parent.GetPrincipalType());
                            query.set_principalSource(15);
                            query.set_queryString(searchText);
                            var searchResult = SP.UI.ApplicationPages.ClientPeoplePickerWebServiceInterface.clientPeoplePickerSearchUser(parent.SharePointContext, query);

                  // Update the global queryID variable so that you can correlate incoming delegate calls.
                            parent._queryID = parent._queryID + 1;
                            var queryIDToPass = parent._queryID;
                            parent._lastQueryID = queryIDToPass;

                  // Make the SharePoint request.
                            parent.SharePointContext.executeQueryAsync(Function.createDelegate(this, function () { parent.QuerySuccess(queryIDToPass, searchResult); }),
                                                Function.createDelegate(this, function () { parent.QueryFailure(queryIDToPass); }));

Contrôle de menu taxonomie

L’exemple Core.TaxonomyMenu vous montre comment implémenter un contrôle de menu taxonomie localisable qui est rempli à partir du magasin de termes dans un complément hébergé par un fournisseur. Le complément configure également les langues, groupes, ensembles et termes du magasin de termes requis pour remplir le menu, et vérifie la préférence de langue de l’utilisateur pour définir la langue d’affichage.

Le complément implémente une classe TaxonomyHelper (CSOM) qui configure le magasin de termes et le remplit avec des termes. Il charge ensuite dans le dossier racine du site un fichier JavaScript qui affiche les liens de navigation.

Le complément configure le magasin de termes sur le site hôte. Il utilise des objets et des méthodes CSOM pour créer un groupe et un ensemble de termes, puis remplit l’ensemble de termes avec quatre termes.

Écran de configuration du magasin de termes

Lorsque vous choisissez le bouton Configurer le magasin de termes , le complément :

• Vérifie que les langues requises (anglais, allemand, Français et suédois) sont activées dans le magasin de termes.
• Crée un groupe de termes et un ensemble de termes et remplit l’ensemble de termes avec quatre nouveaux termes.

Le code suivant dans la classe TaxonomyHelper vérifie que les langues requises sont activées et, si ce n’est pas le cas, elle les active.

var languages = new int[] { 1031, 1033, 1036, 1053 };
            Array.ForEach(languages, l => { 
                if (!termStore.Languages.Contains(l)) 
                    termStore.AddLanguage(l); 
            });

            termStore.CommitAll();
            clientContext.ExecuteQuery();

// Create the term group.
termGroup = termStore.CreateGroup("Taxonomy Navigation", groupId);
                clientContext.Load(termGroup);
                clientContext.ExecuteQuery();

Enfin, le code suivant dans la même classe TaxonomyHelper crée chaque nouveau terme, ainsi que des étiquettes pour les langues allemande, Français et suédoise. Il définit également une valeur pour la propriété _Sys_Nav_SimpleLinkUrl , qui est équivalente à la propriété Simple Link ou Header dans l’outil de gestion du magasin de termes. Dans ce cas, l’URL de chaque terme pointe vers le site racine.

var term = termSet.CreateTerm(termName, 1033, Guid.NewGuid());
term.CreateLabel(termNameGerman, 1031, false);
term.CreateLabel(termNameFrench, 1036, false);
term.CreateLabel(termNameSwedish, 1053, false);
term.SetLocalCustomProperty("_Sys_Nav_SimpleLinkUrl", clientContext.Web.ServerRelativeUrl);

Ensuite, le complément insère le fichier topnav.js dans le dossier racine du site hôte. Ce fichier contient le code JavaScript qui insère les liens de ce terme défini dans la navigation de la page d’accueil du site hôte. L’interface utilisateur du complément vous montre également comment les liens de navigation s’affichent sur le site hôte une fois que le complément a chargé le fichier JavaScript.

Le code suivant dans le fichier topnav.js utilise JSOM pour case activée pour la langue préférée de l’utilisateur.

var targetUser = "i:0#.f|membership|" + _spPageContextInfo.userLoginName;
        context = new SP.ClientContext.get_current();
var peopleManager = new SP.UserProfiles.PeopleManager(context);
var userProperty = peopleManager.getUserProfilePropertyFor(targetUser, "SPS-MUILanguages");

Le complément détermine ensuite si la préférence de langue de l’utilisateur correspond à l’une des langues activées. S’il trouve une correspondance, le code suivant obtient les termes et les étiquettes associées pour la langue préférée de l’utilisateur.

while (termEnumerator.moveNext()) {
    var currentTerm = termEnumerator.get_current();
    var label = currentTerm.getDefaultLabel(lcid);

    termItems.push(currentTerm);
    termLabels.push(label);
    context.load(currentTerm);

Enfin, le code suivant dans le fichier topnav.js insère des liens qui contiennent les termes dans l’élément de navigation supérieur du site hôte.

html += "<ul style='margin-top: 0px; margin-bottom: 0px;'>"
        for (var i in termItems) {
            var term = termItems[i];
            var termLabel = termLabels[i];
            var linkName = termLabel.get_value() != 0 ? termLabel.get_value() : term.get_name();
            var linkUrl = term.get_localCustomProperties()['_Sys_Nav_SimpleLinkUrl'];

            html += "<li style='display: inline;list-style-type: none; padding-right: 20px;'><a href='" + linkUrl + "'>" + linkName + "</a></li>";
        }
        html += "</ul>";

        $('#DeltaTopNavigation').html(html);
        SP.UI.Notify.removeNotification(nid);

Contrôle du sélecteur de taxonomie

L’exemple Core.TaxonomyPicker vous montre comment implémenter un contrôle sélecteur de taxonomie dans un complément hébergé par un fournisseur. Lorsque l’utilisateur commence à taper un terme dans la zone de saisie de texte, le contrôle recherche des correspondances potentielles dans le magasin de termes et les affiche dans une liste sous la zone d’entrée.

Le complément crée une page HTML conforme aux exigences du sélecteur de taxonomie JSOM, puis ajoute et configure le contrôle. Il utilise la bibliothèque JSOM pour interroger le magasin de termes du site hôte. Le sélecteur de taxonomie communique avec le service de métadonnées managées SharePoint, qui nécessite une autorisation d’écriture au niveau de l’étendue d’autorisation de taxonomie afin qu’il puisse lire à partir d’ensembles de termes fermés et écrire dans des ensembles de termes ouverts. Vérifiez que le fichier AppManifest.xml a défini l’autorisation d’écriture au niveau de l’étendue appropriée.

Le dossier Scripts du projet Core.TaxonomyPicker contient des fichiers app.js et taxonomypickercontrol.js (ainsi qu’un fichier de ressources du sélecteur de taxonomie pour une prise en charge linguistique supplémentaire). Le fichier app.js extrait le contexte client à l’aide de la bibliothèque inter-domaines et raccorde le code HTML du fichier Default.aspx au contrôle du sélecteur de taxonomie. Le fichier Default.aspx contient le champ masqué qui implémente à la fois la zone de texte et la fonctionnalité de sélecteur de taxonomie. Il ajoute également une liste à puces pour afficher les suggestions retournées à partir du magasin de termes.

<div style="left: 50%; width: 600px; margin-left: -300px; position: absolute;">
            <table>
                <tr>
                    <td class="ms-formlabel" valign="top"><h3 class="ms-standardheader">Keywords Termset:</h3></td>
                    <td class="ms-formbody" valign="top">
                        <div class="ms-core-form-line" style="margin-bottom: 0px;">
                            <asp:HiddenField runat="server" id="taxPickerKeywords" />
                        </div>
                    </td>
                </tr>
            </table>

            <asp:Button runat="server" OnClick="SubmitButton_Click" Text="Submit" />

            <asp:BulletedList runat="server" ID="SelectedValues" DataTextField="Label" />
</div>

Le fichier app.js crée et configure ensuite un contrôle sélecteur de taxonomie.

// Load scripts for calling taxonomy APIs.
                    $.getScript(layoutsRoot + 'init.js',
                        function () {
                            $.getScript(layoutsRoot + 'sp.taxonomy.js',
                                function () {
                                    // Bind the taxonomy picker to the default keywords term set.
                                    $('#taxPickerKeywords').taxpicker({ isMulti: true, allowFillIn: true, useKeywords: true }, context);
                                });
                        });

Le contrôle sélecteur de taxonomie utilise le code suivant pour ouvrir un instance TaxonomySession dans le modèle JSOM afin de charger tous les termes du magasin de termes.

// Get the taxonomy session by using CSOM.
            var taxSession = SP.Taxonomy.TaxonomySession.getTaxonomySession(spContext);
            //Use the default term store...this could be extended here to support additional term stores.
            var termStore = taxSession.getDefaultSiteCollectionTermStore();

            // Get the term set based on the properties of the term set.
            if (this.Id != null)
                this.RawTermSet = termStore.getTermSet(this.Id); // Get term set by ID.
            else if (this.UseHashtags)
                this.RawTermSet = termStore.get_hashTagsTermSet(); // Get the hashtags term set.
            else if (this.UseKeywords)
                this.RawTermSet = termStore.get_keywordsTermSet(); // Get the keywords term set.

            // Get all terms for the term set and organize them in the async callback.
            this.RawTerms = this.RawTermSet.getAllTerms();
            spContext.load(this.RawTermSet);
            spContext.load(this.RawTerms);
            spContext.executeQueryAsync(Function.createDelegate(this, this.termsLoadedSuccess), Function.createDelegate(this, this.termsLoadedFailed));

Le contrôle sélecteur de taxonomie recherche ensuite les correspondances potentielles des termes chargés et ajoute de nouveaux termes au magasin de termes en fonction des besoins.

Voir aussi

• Composants de l’expérience utilisateur dans SharePoint et SharePoint Online