Creación de controles de experiencia de usuario mediante complementos hospedados por el proveedor de SharePoint
Cree controles de experiencia de usuario en complementos hospedados por el proveedor de SharePoint que funcionen y se comporten como controles de experiencia de usuario en la web host.
En el artículo se describen tres ejemplos que muestran cómo implementar controles de experiencia de usuario en el complemento hospedado por el proveedor:
Core.PeoplePicker : muestra cómo agregar un control de selector de personas.
Core.TaxonomyMenu : muestra cómo implementar un control de menú de taxonomía localizable.
Core.TaxonomyPicker : muestra cómo implementar un control selector de taxonomía.
Estos ejemplos usan JavaScript y el JSOM para comunicarse con SharePoint y usan la biblioteca entre dominios para controlar las llamadas de función desde el complemento al dominio del sitio host.
Nota:
El código de este artículo se proporciona tal cual, sin garantía de ningún tipo, expresa o implícita, incluidas las garantías implícitas de aptitud para un propósito particular, comerciabilidad o ausencia de infracción.
Control de selector de personas
El ejemplo Core.PeoplePicker muestra cómo implementar un control de selector de personas en un complemento hospedado por el proveedor. Cuando el usuario comienza a escribir un nombre en el cuadro de entrada de texto, el control busca posibles coincidencias en el almacén de perfiles de usuario y los muestra en la interfaz de usuario. El complemento muestra un control selector de personas configurable y extensible que se ejecuta en un host remoto y consulta el almacén de perfiles de usuario en el sitio host para que coincida con las entradas del usuario.
control de selector de Personas
Nota:
La solución de Visual Studio para el ejemplo contiene un módulo denominado "Ficticio" para asegurarse de que, cuando se implementa el complemento, crea una web de complemento. Se requiere una web de complemento para las llamadas entre dominios.
La carpeta Scripts del proyecto Core.PeoplePickerWeb contiene archivos app.js y peoplepickercontrol.js (junto con los archivos de recursos del selector de personas para obtener compatibilidad adicional con el lenguaje). El archivo app.js captura el contexto de cliente mediante la biblioteca entre dominios y enlaza el código HTML del archivo Default.aspx al control selector de personas. El archivo Default.aspx contiene las <div> etiquetas que implementan el cuadro de texto y la funcionalidad de búsqueda de personas.
<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" />
A continuación, el archivo app.js crea y configura un control selector de personas.
//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();
El control selector de personas consulta el objeto ClientPeoplePickerWebServiceInterface de la biblioteca JSOM para iniciar búsquedas de usuarios cuyos nombres coinciden con las cadenas de caracteres especificadas.
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); }));
Control de menú taxonomía
El ejemplo Core.TaxonomyMenu muestra cómo implementar un control de menú de taxonomía localizable que se rellena desde el almacén de términos en un complemento hospedado por el proveedor. El complemento también configura los idiomas, grupos, conjuntos y términos de almacén de términos necesarios para rellenar el menú y comprueba la preferencia de idioma del usuario para establecer el idioma para mostrar.
El complemento implementa una clase TaxonomyHelper (CSOM) que configura el almacén de términos y lo rellena con términos. A continuación, carga en la carpeta raíz del sitio un archivo JavaScript que muestra los vínculos de navegación.
El complemento configura el almacén de términos en el sitio host. Usa objetos y métodos de CSOM para crear un grupo de términos y un conjunto de términos y, a continuación, rellena el conjunto de términos con cuatro términos.
Pantalla de configuración de almacén de términos
Al elegir el botón Almacén de términos de instalación , el complemento:
- Asegúrese de que los idiomas necesarios (inglés, alemán, francés y sueco) estén habilitados en el almacén de términos.
- Crea un grupo de términos y un conjunto de términos y rellena el conjunto de términos con cuatro nuevos términos.
El código siguiente de la clase TaxonomyHelper comprueba que los idiomas necesarios están habilitados y, si no lo están, los habilita.
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();
Por último, el código siguiente de la misma clase TaxonomyHelper crea cada nuevo término, junto con etiquetas para los idiomas alemán, francés y sueco. También establece un valor para la propiedad _Sys_Nav_SimpleLinkUrl , que es equivalente a la propiedad Simple Link o Header de la Herramienta de administración del almacén de términos. En este caso, la dirección URL de cada término apunta de nuevo al sitio raíz.
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);
A continuación, el complemento inserta el archivo topnav.js en la carpeta raíz del sitio host. Este archivo contiene el Código JavaScript que inserta los vínculos de este conjunto de términos en la navegación de la página principal del sitio host. La interfaz de usuario del complemento también muestra cómo aparecerán los vínculos de navegación en el sitio host después de que el complemento cargue el archivo JavaScript.
El código siguiente del archivo topnav.js usa JSOM para comprobar el idioma preferido del usuario.
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");
A continuación, el complemento determina si la preferencia de idioma del usuario coincide con uno de los idiomas habilitados. Si encuentra una coincidencia, el código siguiente obtiene los términos y las etiquetas asociadas para el idioma preferido del usuario.
while (termEnumerator.moveNext()) {
var currentTerm = termEnumerator.get_current();
var label = currentTerm.getDefaultLabel(lcid);
termItems.push(currentTerm);
termLabels.push(label);
context.load(currentTerm);
Por último, el código siguiente del archivo topnav.js inserta vínculos que contienen los términos en el elemento de navegación superior del sitio host.
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);
Control selector de taxonomía
El ejemplo Core.TaxonomyPicker muestra cómo implementar un control de selector de taxonomía en un complemento hospedado por el proveedor. Cuando el usuario comienza a escribir un término en el cuadro de entrada de texto, el control busca posibles coincidencias en el almacén de términos y los muestra en una lista bajo el cuadro de entrada.
El complemento crea una página HTML que se ajusta a los requisitos del selector de taxonomía de JSOM y, a continuación, agrega y configura el control. Usa la biblioteca JSOM para consultar el almacén de términos del sitio host. El selector de taxonomía se comunica con el servicio de metadatos administrados de SharePoint, que requiere permiso de escritura en el ámbito de permisos de taxonomía para que pueda leer desde conjuntos de términos cerrados y escribir en conjuntos de términos abiertos. Asegúrese de que el archivo AppManifest.xml ha establecido el permiso de escritura en el ámbito adecuado.
La carpeta Scripts del proyecto Core.TaxonomyPicker contiene archivos app.js y taxonomypickercontrol.js (junto con un archivo de recursos de selector de taxonomía para obtener compatibilidad adicional con el lenguaje). El archivo app.js captura el contexto de cliente mediante la biblioteca entre dominios y enlaza el código HTML del archivo Default.aspx al control selector de taxonomía. El archivo Default.aspx contiene el campo oculto que implementa tanto el cuadro de texto como la funcionalidad del selector de taxonomía. También agrega una lista con viñetas para mostrar las sugerencias devueltas desde el almacén de términos.
<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>
A continuación, el archivo app.js crea y configura un control de selector de taxonomía.
// 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);
});
});
El control selector de taxonomía usa el código siguiente para abrir una instancia de TaxonomySession en el JSOM para cargar todos los términos del almacén de términos.
// 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));
A continuación, el control selector de taxonomía busca posibles coincidencias de los términos cargados y agrega nuevos términos al almacén de términos según sea necesario.