Crear elementos de complemento para instalar con el complemento para SharePoint
Con los elementos del complemento, puede mostrar la experiencia de usuario del complemento directamente en las páginas del sitio web de SharePoint. Un elemento de complemento muestra la página web (que suele tener forma interactiva o una visualización dinámica de datos) que especifique mediante un IFrame (también conocido como marco) en una página en la web de host.
Para obtener más información sobre los elementos de complemento, consulte los siguientes artículos:
- Obtener acceso al complemento desde la interfaz de usuario
- Diseño de la experiencia del usuario para complementos de SharePoint
- Extender la interfaz de usuario de SharePoint en complementos
En la ilustración siguiente se muestra cómo se ve el contenido del elemento de complemento en una página de SharePoint.
El contenido del elemento de complemento en una página de SharePoint
Un elemento de complemento se implementa con la clase ClientWebPart y, al igual que todos los elementos web, está disponible en la Galería de elementos web después de que un usuario instale el complemento de SharePoint que lo incluye. Los usuarios pueden personalizar aún más el elemento de complemento mediante las propiedades que proporcione. (Para obtener un ejemplo de propiedades configurables en un elemento de complemento, vea la ilustración Página de SharePoint que hospeda un elemento de complemento básico más adelante en este artículo).
En el ejemplo de este artículo se usa una página web hospedada en un servidor remoto, no en SharePoint, como página de contenido. Tenga en cuenta que también puede usar páginas de SharePoint para hospedar el contenido del elemento de complemento, como se describe en la sección Otros elementos de complemento de escenarios comunes más adelante en este artículo.
Requisitos previos para usar los ejemplos de este artículo
Para seguir los pasos de este ejemplo, necesita lo siguiente:
- Visual Studio
- Microsoft Office Developer Tools para Visual Studio
- Un entorno de desarrollo SharePoint. Si necesita ayuda para configurar un entorno de desarrollo, consulte Dos tipos de complementos de SharePoint: hospedados en SharePoint y hospedados por el proveedor.
Crear un elemento de complemento para su instalación en la web de host
Son necesarias varias tareas para crear e instalar su elemento de complemento en la web de host:
- Crear los proyectos de Complemento de SharePoint y de web remota.
- Agregue un formulario para el contenido del elemento de complemento.
- Agregue el elemento de complemento al proyecto de Complemento de SharePoint.
Después de completar las tareas, la parte del complemento debe ser similar a la siguiente ilustración cuando el elemento del complemento está en modo de edición. Aquí podemos ver (1) el contenido del complemento que se muestra en una página SharePoint, y (2) las propiedades personalizadas de los elementos del complemento.
Página de SharePoint que hospeda un elemento de complemento básico
Agregar un formulario para el contenido del elemento de complemento
Cree un Complemento de SharePoint hospedado por el proveedor, tal y como se describe en Introducción a la creación de Complementos de SharePoint hospedados por el proveedor, pero asigne al proyecto el nombre TestAppPart.
Una vez creada la solución de Visual Studio, haga clic con el botón derecho en el proyecto de aplicación web (no en el proyecto de complemento de SharePoint) y agregue un nuevo formulario web seleccionando Agregar> nuevo formularioweb>de elemento>. Dé al formulario el nombre AppPartContent.aspx.
En el archivo AppPartContent.aspx, reemplace todo el elemento HTML y sus elementos secundarios por el siguiente código HTML. Deje todo el marcado encima del elemento HTML tal y como está. El código HTML contiene JavaScript que realiza las siguientes tareas:
- Extrae los valores de propiedad predeterminados de la siguiente cadena de consulta
- Procesa los valores de propiedad
Observe que el código espera algunos parámetros en la cadena de consulta. El elemento de complemento proporciona sus propiedades personalizadas a través de la cadena de consulta de forma que la página web pueda usarlas. La siguiente tarea explica cómo declarar propiedades personalizadas y cómo ponerlas a disposición de la página web del complemento.
<html> <body> <div id="content"> <!-- Placeholders for properties --> String property: <span id="strProp"></span><br /> Integer property: <span id="intProp"></span><br /> Boolean property: <span id="boolProp"></span><br /> Enumeration property: <span id="enumProp"></span><br /> </div> <!-- Main JavaScript function, controls the rendering logic based on the custom property values --> <script lang="javascript"> "use strict"; var params = document.URL.split("?")[1].split("&"); var strProp; var intProp; var boolProp; var enumProp; // Extracts the property values from the query string. for (var i = 0; i < params.length; i = i + 1) { var param = params[i].split("="); if (param[0] == "strProp") strProp = decodeURIComponent(param[1]); else if (param[0] == "intProp") intProp = parseInt(param[1]); else if (param[0] == "boolProp") boolProp = (param[1] == "true"); else if (param[0] == "enumProp") enumProp = decodeURIComponent(param[1]); } document.getElementById("strProp").innerText = strProp; document.getElementById("intProp").innerText = intProp; document.getElementById("boolProp").innerText = boolProp; document.getElementById("enumProp").innerText = enumProp; </script> </body> </html>Guarde y cierre el archivo.
Agregar el elemento de complemento al proyecto de Complemento de SharePoint
Haga clic con el botón derecho en el proyecto de complemento de SharePoint (no en el proyecto de aplicación web) y, a continuación, seleccione Agregar>nuevo elemento>web office/cliente de SharePoint>(Web host). (El "elemento de complemento" también se denomina "elemento web cliente").
Asigne al elemento el nombre Elemento de complemento básico.
En el cuadro de diálogo Especificar el elemento web del cliente , seleccione Seleccionar o escriba una dirección URL para una página web existente. Seleccione la página TestAppWebPart/AppPartContent.aspx de la lista desplegable. (Una vez hecha la elección, la dirección URL de la página puede aparecer en el cuadro con "TestAppWebPart" sustituido por ~remoteAppUrl y con {StandardTokens } agregado a los parámetros de consulta.)
Seleccione Finalizar.
Haga clic con el botón derecho en Elemento de complemento básico, en el Explorador de soluciones, y seleccione Propiedades.
En el panel Propiedades, seleccione Propiedades personalizadas y seleccione el botón de globo (…).
Use el cuadro de diálogo Propiedades personalizadas para agregar cuatro propiedades personalizadas al elemento de complemento. Debe establecer cinco atributos para cada una de las cuatro propiedades personalizadas. Los nombres de los atributos y sus valores se indican en la tabla 1. Cree las propiedades mediante el siguiente procedimiento.
Seleccione Agregar.
En la lista de atributos, seleccione el primero de la tabla 1: DefaultValue.
Establezca el valor (por ejemplo, Valor predeterminado de cadena).
Elija el siguiente atributo, Name, y establezca su valor, por ejemplo, strProp.
Continúe con los atributos Type, WebCategory y WebDisplayName.
Seleccione Agregar de nuevo y repita el proceso de las cuatro filas de la tabla 1. No cierre el cuadro de diálogo.
Tabla 1. Atributos para las propiedades personalizadas del elemento de complemento
DefaultValue Nombre Tipo WebCategory WebDisplayName Valor predeterminado de cadena strProp cadena Categoría de elemento de complemento básico Una propiedad de tipo cadena 0 intProp entero Categoría de elemento de complemento básico Una propiedad de tipo entero falso boolProp booleano Categoría de elemento de complemento básico Una propiedad de tipo booleano 1st enumProp enumeración Categoría de elemento de complemento básico Una propiedad de tipo enumeración En este momento, el cuadro de diálogo será similar a este:
Cuadro de diálogo Propiedades personalizadas para ClientWebPart
Seleccione la propiedad enumProp, el atributo EnumItems y, después, pulse el botón de globo (…).
Use el editor de colecciones ClientWebPartEnumItem para agregar tres elementos. Debe establecer dos atributos en cada uno. Los nombres de los atributos y sus valores se indican en la tabla 1. Cree las propiedades mediante el siguiente procedimiento.
Seleccione Agregar.
En la lista de atributos, seleccione el primer atributo de la tabla 2: Value.
Establezca el valor del atributo (por ejemplo, “1.º”).
Elija el siguiente atributo, WebDisplayName, y establezca su valor (por ejemplo, First option).
Vuelva a seleccionar Agregar y repita el proceso para todas las filas de la tabla 2.
Tabla 2. Elementos de enumeración de la propiedad enumProp
Valor WebDisplayName 1.º Primera opción 2nd Segunda opción 3rd Tercera opción Cuando termine, el cuadro de diálogo será similar a este:
Editor de colección ClientWebPartEnumItem
Seleccione Aceptar para cerrar el cuadro de diálogo y, después, vuelva a seleccionar Aceptar para cerrar el cuadro de diálogo Propiedades personalizadas.
Visual Studio genera el siguiente código XML en el archivo elements.xml de la parte del complemento (saltos de línea agregados para mayor claridad). Tenga en cuenta que el atributo Title del elemento ClientWebPart se establece en "Título de elemento de complemento básico" y la descripción se establece en "Descripción básica de la parte del complemento". Elimine la palabra "Title" del primero y reemplace la segunda por un elemento de complemento Básico.
<?xml version="1.0" encoding="UTF-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<ClientWebPart
Name="Basic add-in part"
Title="Basic add-in part Title"
Description="Basic add-in part Description" >
<!-- The properties are passed through the query string
using the following notation: _propertyName_
in the Src property of the Content element.
-->
<Content
Src="~remoteAppUrl/AppPartContent.aspx?strProp=_strProp_&amp;intProp=_intProp_&amp;boolProp=_boolProp_&amp;enumProp=_enumProp_"
Type="html"/>
<Properties>
<Property
Name="strProp"
Type="string"
RequiresDesignerPermission="true"
DefaultValue="String default value"
WebCategory="Basic add-in part category"
WebDisplayName="A property of type string.">
</Property>
<Property
Name="intProp"
Type="int"
RequiresDesignerPermission="true"
DefaultValue="0"
WebCategory="Basic add-in part category"
WebDisplayName="A property of type integer.">
</Property>
<Property
Name="boolProp"
Type="boolean"
RequiresDesignerPermission="true"
DefaultValue="false"
WebCategory="Basic add-in part category"
WebDisplayName="A property of type boolean.">
</Property>
<Property
Name="enumProp"
Type="enum"
RequiresDesignerPermission="true"
DefaultValue="1st"
WebCategory="Basic add-in part category"
WebDisplayName="A property of type enum.">
<EnumItems>
<EnumItem WebDisplayName="First option" Value="1st"/>
<EnumItem WebDisplayName="Second option" Value="2nd"/>
<EnumItem WebDisplayName="Third option" Value="3rd"/>
</EnumItems>
</Property>
</Properties>
</ClientWebPart>
</Elements>
Establecer la página de inicio del complemento como la página principal de los sitios web de host
El complemento de SharePoint de ejemplo continuo no tiene ninguna web de complemento y su aplicación web remota solo existe para hospedar el formulario. No hay ninguna experiencia inmersiva y a página completa para este complemento. Por tanto, debería establecerse como su página de inicio la página de inicio de la web de host.
Para empezar, seleccione el proyecto de complemento de SharePoint (no el proyecto de aplicación web) en Explorador de soluciones y copie el valor de la propiedad Url del sitio, incluido el protocolo (por ejemplohttps://contoso.sharepoint.com) en el Portapapeles.
Abra el manifiesto del complemento y pegue la dirección URL en el cuadro Página de inicio.
De forma opcional, puede eliminar la página Default.aspx del proyecto de aplicación web, ya que no se usa en el complemento de SharePoint.
Compilar y probar la solución
Seleccione la tecla F5.
Nota:
Al seleccionar F5, Visual Studio compila la solución, implementa el complemento y abre la página de permisos del complemento.
Seleccione el botón Confiar.
Agregue el elemento de complemento básico desde la galería de elementos de complemento. Para obtener instrucciones detalladas, vea Agregar un elemento de complemento a una página.
Cuando el complemento está instalado en la web de host, el elemento de complemento básico está disponible en la galería de elementos de complemento. Debería parecerse mucho a la siguiente ilustración.
Elemento de complemento en la galería de elementos de complemento
Cuando haya agregado el elemento de complemento, seleccione la flecha abajo a la derecha del título Elemento de complemento básico y elija Editar elemento web.
Verá el elemento de complemento en modo edición.
Abra la Categoría de elemento de complemento básico y cambie algunos valores de las propiedades.
Haga clic en Aceptar para guardar los cambios y comprobar que las propiedades han cambiado en el elemento de complemento.
Al finalizar la sesión de depuración y no volverá a usar F5 en este proyecto durante un tiempo, se recomienda retirar el complemento de SharePoint una última vez para asegurarse de que la parte del complemento de prueba se quita de la página principal. Haga clic con el botón derecho en el proyecto de complemento de SharePoint y seleccione Retirar.
Solución de problemas
| Problema | Solución |
|---|---|
| El elemento de complemento no muestra ningún contenido. La parte del complemento muestra el siguiente error: Se canceló la navegación a la página web. Este error se produce porque el explorador ha bloqueado la página de contenido. | Habilite el contenido mixto. El procedimiento puede ser diferente en función del explorador que use: Internet Explorer 9 y 10 muestran el siguiente mensaje en la parte inferior de la página: Solo se muestra contenido seguro. Seleccione Mostrar todo el contenido para mostrar el contenido del elemento de complemento. Internet Explorer 8 shows a dialog box with the following message: Do you want to view only the webpage content that was delivered securely? Select No to display the add-in part content. De manera opcional, puede habilitar el contenido mixto en la zona de Internet en la que está trabajando. Para la mayoría de desarrolladores, la zona de Internet es Intranet local. Si este no es su caso, sustituya Intranet local con la zona de Internet en la que esté trabajando. En Internet Explorer, seleccione Herramientas>Opciones de Internet. En el cuadro de diálogo Opciones de Internet , en la pestaña Seguridad , seleccione Intranet local y, a continuación, seleccione el botón Nivel personalizado . En el cuadro de diálogo Configuración de seguridad, habilite Mostrar contenido mixto en la sección Miscelánea. |
Otras situaciones comunes con elementos de complemento
En este artículo se muestra cómo crear un elemento de complemento básico con propiedades personalizadas usando una página web remota como página de contenido. También puede explorar los siguientes escenarios y detalles de los elementos de complemento.
Usar una página de SharePoint como página de contenido
En la mayoría de los casos, una página web no se puede mostrar en un marco si envía un encabezado HTTP X-Frame-Options en la respuesta. De forma predeterminada, las páginas de SharePoint incluyen el encabezado X-Frame-Options . Si usa una página web de SharePoint hospedada en la web del complemento, podría encontrarse con el siguiente error (que se muestra en la ilustración siguiente): Este contenido no se puede mostrar en un marco.
Elemento de complemento que no puede mostrar su contenido en un marco
Tenga en cuenta que ciertos escenarios son susceptibles a ataques ClickJacking cuando las páginas web se muestran en un marco. Revise con detenimiento los escenarios de elementos de complemento para asegurarse de que no existe ningún riesgo de ataques de secuestro de clics.
Si la página hospedada en la web del complemento no es susceptible a ataques ClickJacking, puede usar el elemento web AllowFraming para suprimir el encabezado X-Frame-Options de la respuesta de la página. En el ejemplo de código siguiente se muestra cómo usar el elemento web AllowFraming en una página de SharePoint. Copie este código de marcado en la página hospedada en la web de complemento. Colóquelo encima del primer elemento asp:content de la página. No debería ser elemento secundario de ningún otro elemento.
<WebPartPages:AllowFraming ID="AllowFraming1" runat="server" />
Puede descargar un ejemplo de código de elemento de complemento donde se muestra cómo usar una página de SharePoint como página de contenido.
Cambiar el tamaño del elemento de complemento
Si usa contenido dinámico en la parte del complemento, es posible que el contenido cambie su ancho y alto. Dada su naturaleza dinámica, es posible que no se ajuste al marco. También es posible que esté usando demasiado espacio. Con el contenido dinámico puede resultar muy difícil especificar un tamaño fijo en la declaración del elemento de complemento. Sin embargo, puede cambiar el tamaño del marco para que se ajuste al ancho y alto del contenido.
Puede usar mensajes POST desde la página web de contenido para especificar el tamaño del marco. En el siguiente ejemplo de JavaScript se muestra cómo enviar un mensaje POST para cambiar el tamaño del marco en el que se hospeda el elemento del complemento. Normalmente, tendría esto en un método JavaScript en un archivo JavaScript al que llame desde la página. Por ejemplo, la página podría tener un control en el que cada usuario especifique el tamaño de la ventana del elemento de complemento. A continuación, se llama al método personalizado desde el controlador onchange del control.
Para obtener un ejemplo completo de un elemento de complemento cuyo tamaño cambia dinámicamente, vea Ejemplo de código: Cambiar el tamaño de los elementos de complemento de forma dinámica en complementos de SharePoint.
window.parent.postMessage("<message senderId={SenderId}>resize(120, 300)</message>", {hostweburl});
En el ejemplo anterior, el código del elemento de complemento establece automáticamente el valor senderId en la cadena de consulta de la página cuando se representa la página. Bastará con que la página lea el valor de SenderId en la cadena de consultas y lo use cuando se solicite cambiar el tamaño. La dirección URL de la web de host se puede recuperar desde la cadena de consultas adjuntando los tokens StandardTokens o HostUrl al atributo Src de la definición del elemento de complemento.
Usar la hoja de estilo de SharePoint en el contenido del elemento de complemento
Dado que el elemento de complemento está hospedado en una página de SharePoint, es posible que desee que el contenido del elemento de complemento tenga el aspecto de que forma parte de la página. Una manera de lograr una apariencia similar es usar las mismas clases de estilo que la página de SharePoint que hospeda el elemento del complemento. Puede hacer que la hoja de estilos del sitio web de SharePoint esté disponible para el elemento del complemento agregando una referencia al archivo defaultcss.ashx desde la web del complemento.
Para obtener una explicación sobre cómo hacer referencia al archivo defaultcss.ashx en los complementos de SharePoint, vea Usar una hoja de estilo de sitio web de SharePoint en complementos de SharePoint.
Para ver un elemento de complemento que hace referencia a la hoja de estilos, descargue el Ejemplo de código: Mostrar contenido de una página web remota con el elemento de complemento cafetera.
Detectar cuándo el elemento de complemento está en modo de edición
Los usuarios pueden editar el elemento del complemento para cambiar sus propiedades. Por ejemplo, es posible que un usuario quiera cambiar una de las propiedades Apariencia o Diseño del elemento del complemento. Si la parte del complemento está en modo de edición, es posible que desee modificar la lógica de representación o evitar que se produzca algún procesamiento innecesario. Considere, por ejemplo, un elemento de complemento que llama a una base de datos back-end cada vez que se vuelve a cargar la página host. Cambiar un valor de propiedad de elemento de complemento en modo de edición hace que se vuelva a cargar la página, pero es posible que no desee que la llamada de red se desencadene en ese caso. Puede usar el token editMode para detectar si los usuarios están editando la parte del complemento.
Para usar el token editMode, agregue un parámetro de cadena de consulta al atributo Src del elemento Content en la declaración del elemento de complemento.
<Content Src="content_page_url&amp;editmode=_editMode_">
El token editMode permite que la página de contenido determine si el elemento del complemento está en modo de edición. Si la parte del complemento está en modo de edición, el token editMode se resuelve en 1; De lo contrario, el token se resuelve en 0.