Erstellen von UX-Steuerelementen mithilfe von vom SharePoint-Anbieter gehosteten Add-Ins
Erstellen Sie UX-Steuerelemente in vom SharePoint-Anbieter gehosteten Add-Ins, die funktionieren und sich wie UX-Steuerelemente im Hostweb verhalten.
Der Artikel beschreibt drei Beispiele, die ihnen zeigen, wie Sie UX-Steuerelemente in Ihrem vom Anbieter gehosteten Add-In implementieren:
Core.PeoplePicker – Zeigt Ihnen, wie Sie ein Personenauswahl-Steuerelement hinzufügen.
Core.TaxonomyMenu – Zeigt Ihnen, wie Sie ein lokalisierbares Taxonomiemenü-Steuerelement implementieren.
Core.TaxonomyPicker – Zeigt Ihnen, wie Sie ein Taxonomieauswahl-Steuerelement implementieren.
In diesen Beispielen wird JavaScript und JSOM für die Kommunikation mit SharePoint verwendet, und die domänenübergreifende Bibliothek wird verwendet, um Funktionsaufrufe vom Add-In an die Hostwebsitedomäne zu verarbeiten.
Hinweis
Der Code in diesem Artikel wird wie besehen und ohne jegliche Garantie zur Verfügung gestellt, gleich ob ausdrücklich oder konkludent, einschließlich jedweder stillschweigenden Gewährleistung der Eignung für einen bestimmten Zweck, Marktgängigkeit oder Nichtverletzung von Rechten.
Steuerelement „Personenauswahl“
Das Core.PeoplePicker-Beispiel zeigt Ihnen, wie Sie ein Personenauswahl-Steuerelement in einem vom Anbieter gehosteten Add-In implementieren. Wenn der Benutzer beginnt, einen Namen in das Texteingabefeld einzugeben, durchsucht das Steuerelement den Benutzerprofilspeicher nach möglichen Übereinstimmungen und zeigt sie auf der Benutzeroberfläche an. Das Add-In zeigt ein konfigurierbares und erweiterbares Personenauswahlsteuerelement an, das auf einem Remotehost ausgeführt wird, und fragt den Benutzerprofilspeicher auf der Hostwebsite ab, um Benutzereingaben abzugleichen.
Personen-Auswahlsteuerelement
Hinweis
Die Visual Studio-Projektmappe für das Beispiel enthält ein Modul mit dem Namen "Dummy", um sicherzustellen, dass das Add-In bei der Bereitstellung ein Add-In-Web erstellt. Für domänenübergreifende Aufrufe ist ein Add-In-Web erforderlich.
Der Ordner Skripts des Projekts Core.PeoplePickerWeb enthält app.js- und peoplepickercontrol.js-Dateien (zusammen mit Personenauswahl-Ressourcendateien für zusätzliche Sprachunterstützung). Die app.js-Datei ruft den Clientkontext mithilfe der domänenübergreifenden Bibliothek ab und bindet den HTML-Code in der Datei Default.aspx in das Steuerelement für die Personenauswahl ein. Die Datei Default.aspx enthält die <div> Tags, die sowohl das Textfeld als auch die Funktion für die Personensuche implementieren.
<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" />
Die app.js-Datei erstellt und konfiguriert dann ein Personenauswahl-Steuerelement.
//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();
Das Personenauswahl-Steuerelement fragt das ClientPeoplePickerWebServiceInterface-Objekt in der JSOM-Bibliothek ab, um Suchvorgänge nach Benutzern zu initiieren, deren Namen mit den eingegebenen Zeichenfolgen übereinstimmen.
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); }));
Taxonomiemenü-Steuerelement
Das Core.TaxonomyMenu-Beispiel zeigt, wie Sie ein lokalisierbares Taxonomiemenü-Steuerelement implementieren, das aus dem Terminologiespeicher in einem vom Anbieter gehosteten Add-In aufgefüllt wird. Das Add-In richtet auch die erforderlichen Terminologiespeichersprachen, Gruppen, Sätze und Begriffe zum Auffüllen des Menüs ein und überprüft die Spracheinstellung des Benutzers, um die Anzeigesprache festzulegen.
Das Add-In implementiert eine TaxonomyHelper-Klasse (CSOM), die den Terminologiespeicher einrichtet und mit Begriffen auffüllt. Anschließend wird eine JavaScript-Datei in den Stammordner der Website hochgeladen, in der die Navigationslinks angezeigt werden.
Das Add-In richtet den Terminologiespeicher auf der Hostwebsite ein. Es verwendet CSOM-Objekte und -Methoden, um eine Ausdrucksgruppe und einen Ausdruckssatz zu erstellen, und füllt dann den Ausdruckssatz mit vier Begriffen auf.
Bildschirm zum Einrichten des Terminologiespeichers
Wenn Sie die Schaltfläche Ausdrucksspeicher einrichten auswählen, führt das Add-In Folgendes aus:
- Stellt sicher, dass die erforderlichen Sprachen (Englisch, Deutsch, Französisch und Schwedisch) im Terminologiespeicher aktiviert sind.
- Erstellt eine Ausdrucksgruppe und einen Ausdruckssatz und füllt den Ausdruckssatz mit vier neuen Begriffen auf.
Der folgende Code in der TaxonomyHelper-Klasse überprüft, ob die erforderlichen Sprachen aktiviert sind, und wenn dies nicht der Fall ist, werden sie aktiviert.
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();
Schließlich erstellt der folgende Code in derselben TaxonomyHelper-Klasse jeden neuen Begriff zusammen mit Bezeichnungen für die Sprachen Deutsch, Französisch und Schwedisch. Außerdem wird ein Wert für die eigenschaft _Sys_Nav_SimpleLinkUrl festgelegt, die der Simple Link- oder Header-Eigenschaft im Terminologiespeicherverwaltungstool entspricht. In diesem Fall verweist die URL für jeden Begriff auf die Stammwebsite.
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);
Als Nächstes fügt das Add-In die topnav.js-Datei in den Stammordner der Hostwebsite ein. Diese Datei enthält den JavaScript-Code, der die Links aus diesem Ausdruckssatz in die Navigation der Startseite der Hostwebsite einfügt. Die Add-In-Benutzeroberfläche zeigt auch, wie die Navigationslinks auf der Hostwebsite angezeigt werden, nachdem das Add-In die JavaScript-Datei hochgeladen hat.
Der folgende Code in der topnav.js-Datei verwendet JSOM, um nach der bevorzugten Sprache des Benutzers zu suchen.
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");
Das Add-In bestimmt dann, ob die Spracheinstellung des Benutzers mit einer der aktivierten Sprachen übereinstimmt. Wenn eine Übereinstimmung gefunden wird, ruft der folgende Code die Begriffe und die zugehörigen Bezeichnungen für die bevorzugte Sprache des Benutzers ab.
while (termEnumerator.moveNext()) {
var currentTerm = termEnumerator.get_current();
var label = currentTerm.getDefaultLabel(lcid);
termItems.push(currentTerm);
termLabels.push(label);
context.load(currentTerm);
Schließlich fügt der folgende Code in der topnav.js-Datei Links, die die Begriffe enthalten, in das obere Navigationselement der Hostwebsite ein.
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);
Taxonomieauswahl-Steuerelement
Das Core.TaxonomyPicker-Beispiel zeigt, wie Sie ein Taxonomieauswahl-Steuerelement in einem vom Anbieter gehosteten Add-In implementieren. Wenn der Benutzer mit der Eingabe eines Begriffs in das Texteingabefeld beginnt, durchsucht das Steuerelement den Begriffsspeicher nach potenziellen Übereinstimmungen und zeigt diese in einer Liste unter dem Eingabefeld an.
Das Add-In erstellt eine HTML-Seite, die den Anforderungen der JSOM-Taxonomieauswahl entspricht, und fügt dann das Steuerelement hinzu und konfiguriert es. Sie verwendet die JSOM-Bibliothek, um den Terminologiespeicher der Hostwebsite abzufragen. Die Taxonomieauswahl kommuniziert mit dem SharePoint Managed Metadata Service, der Schreibberechtigungen im Taxonomieberechtigungsbereich erfordert, damit er aus geschlossenen Ausdruckssätzen lesen und in offene Ausdruckssätze schreiben kann. Stellen Sie sicher, dass die AppManifest.xml-Datei die Schreibberechtigung im entsprechenden Bereich festgelegt hat.
Der Ordner Skripts des Projekts Core.TaxonomyPicker enthält app.js- und taxonomypickercontrol.js-Dateien (zusammen mit einer Taxonomieauswahl-Ressourcendatei für zusätzliche Sprachunterstützung). Die app.js-Datei ruft den Clientkontext mithilfe der domänenübergreifenden Bibliothek ab und bindet den HTML-Code in der Datei Default.aspx in das Taxonomieauswahl-Steuerelement ein. Die Datei Default.aspx enthält das ausgeblendete Feld, das sowohl das Textfeld als auch die Taxonomieauswahl-Funktion implementiert. Außerdem wird eine Aufzählung hinzugefügt, um vom Terminologiespeicher zurückgegebene Vorschläge anzuzeigen.
<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>
Die app.js-Datei erstellt und konfiguriert dann ein Taxonomieauswahl-Steuerelement.
// 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);
});
});
Das Taxonomieauswahl-Steuerelement verwendet den folgenden Code, um eine TaxonomySession-instance im JSOM zu öffnen, um alle Begriffe aus dem Terminologiespeicher zu laden.
// 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));
Das Taxonomieauswahl-Steuerelement sucht dann nach potenziellen Übereinstimmungen aus den geladenen Begriffen und fügt dem Terminologiespeicher nach Bedarf neue Begriffe hinzu.