Migrar personalizaciones existentes del elemento web Editor de scripts a SharePoint Framework
SharePoint Framework es un modelo para crear personalizaciones de SharePoint. Si ha estado compilando soluciones de SharePoint del lado cliente mediante el elemento web Editor de scripts, es posible que se pregunte cuáles son las posibles ventajas de migrarlas a la SharePoint Framework.
En este artículo se resaltan las ventajas de migrar personalizaciones existentes del lado cliente a SharePoint Framework y se señala una serie de consideraciones que debe tener en cuenta al planear la migración.
Nota:
La información de este artículo se aplica a las personalizaciones creadas mediante el elemento web Content- y script Editor. Siempre que haya una referencia al elemento web Editor de scripts, debe leer el elemento web Editor de contenido y el elemento web Editor de scripts.
Ventajas de migrar las personalizaciones existentes del lado cliente a SharePoint Framework
SharePoint Framework se ha construido desde el principio como un modelo de desarrollo de SharePoint orientado al desarrollo del lado cliente. Aunque ofrece principalmente capacidades de extensibilidad para sitios de grupo modernos, las personalizaciones creadas en SharePoint Framework también funcionan con la experiencia de SharePoint clásica. La creación de personalizaciones mediante el SharePoint Framework le ofrece una serie de ventajas sobre el uso de cualquier otro modelo de desarrollo de SharePoint disponible hasta la fecha.
Cree una vez y reutilice en todos los dispositivos
La experiencia de usuario moderna de SharePoint se ha diseñado para permitir de forma nativa el acceso a la información almacenada en SharePoint con cualquier dispositivo. Además, la experiencia moderna es compatible con la aplicación móvil de SharePoint. Las soluciones creadas con el SharePoint Framework integrarse sin problemas con la experiencia moderna de SharePoint y se pueden usar en los distintos dispositivos y dentro de la aplicación móvil de SharePoint. Dado que SharePoint Framework soluciones también funcionan con la experiencia clásica de SharePoint, las pueden usar las organizaciones que aún no se han migrado a la experiencia moderna.
Más sólido y preparado para el futuro
Anteriormente, los desarrolladores personalizaban SharePoint haciendo referencia a elementos DOM específicos de la interfaz de usuario. Con este método, podían modificar la experiencia del usuario estándar o proporcionar funcionalidad adicional a los usuarios finales. Sin embargo, estas soluciones eran propensas a errores. Puesto que el DOM de página de SharePoint no se había concebido como una superficie de extensibilidad, las soluciones basadas en él quedaban inutilizadas cada vez que cambiaba.
SharePoint Framework ofrece a los desarrolladores puntos de extensibilidad y API estandarizados para crear soluciones del lado cliente y proporcionar a los usuarios finales funcionalidades adicionales. Los desarrolladores pueden usar la SharePoint Framework para crear soluciones de forma compatible y a prueba de futuro, y no es necesario preocuparse por cómo los cambios futuros en la interfaz de usuario de SharePoint podrían afectar a la solución.
Acceso más fácil a la información en SharePoint y Office 365
Microsoft está ampliando continuamente las capacidades de SharePoint y Office 365. A medida que las organizaciones usan más ambas plataformas, cada vez es más importante que los desarrolladores aprovechen la información y la información almacenadas en Office 365 para crear soluciones enriquecidas. Uno de los objetivos de SharePoint Framework es facilitar a los desarrolladores conectarse a las diversas API de SharePoint y Office 365.
Permitir a los usuarios configurar las soluciones que necesitan
Las soluciones del lado cliente creadas a través de la inserción de scripts a menudo no ofrecían a los usuarios finales una manera sencilla de configurarlas según sus necesidades. La única manera de configurar una solución de este tipo consistía en modificar el código o utilizar una interfaz de usuario creada específicamente para tal fin.
Los elementos web del lado cliente de SharePoint Framework ofrecen una forma estándar de configurar elementos web mediante un panel de propiedades, lo que resulta familiar a los usuarios que trabajaban con elementos web clásicos anteriormente. Los desarrolladores que crean elementos web del lado cliente pueden elegir si su elemento web va a tener un panel de propiedades reactivo (predeterminado), en el que cada cambio en una propiedad del elemento web se refleja directamente en el cuerpo el elemento web, o un panel de propiedades no reactivo, en el que los cambios en las propiedades del elemento web deben aplicarse explícitamente.
Trabajar en sitios sin scripts
Para ayudar a las organizaciones a controlar sus personalizaciones, Microsoft publicó la funcionalidad sin script en SharePoint Online. Cuando el inquilino, o una colección de sitios concreta, tiene el indicador sin scripts habilitado, se deshabilitan las personalizaciones que dependen de la incrustación e inyección de scripts.
Dado que SharePoint Framework elementos web del lado cliente se implementan a través del catálogo de aplicaciones con una aprobación previa, se pueden ejecutar en sitios sin script. De forma predeterminada, los sitios de grupo modernos tienen habilitada la opción sin scripts y no es posible incrustar secuencias de comandos en estos sitios. Esto hace que el uso de la SharePoint Framework la única manera admitida de crear personalizaciones del lado cliente en sitios de equipo modernos.
Similitudes entre las soluciones de SharePoint Framework y las personalizaciones del elemento web Editor de scripts
Aunque se basan en un modelo nuevo de desarrollo que usa una nueva cadena de herramientas, las soluciones de SharePoint Framework son similares a las personalizaciones del elemento web Editor de scripts que ha creado en el pasado. Dado que comparten los mismos conceptos, resulta más fácil migrarlas al nuevo SharePoint Framework.
Ejecutar como parte de la página
De forma similar a las personalizaciones incrustadas en elementos web del Editor de scripts, las soluciones de SharePoint Framework forman parte de la página. Por lo tanto, estas soluciones tienen acceso al DOM de la página y pueden comunicarse con otros componentes de la misma página. Además, los desarrolladores tienen más facilidad para hacer que sus soluciones tengan capacidad de respuesta para que se adapten a los distintos factores de forma con los que se puede mostrar una página de SharePoint, incluida la aplicación móvil de SharePoint.
A diferencia de los complementos de SharePoint, SharePoint Framework elementos web del lado cliente no están aislados en un iframe. Como consecuencia, cualquier recurso al que tenga acceso el elemento web del lado cliente está accesible también para otros elementos de la página. Es importante tener esto en cuenta al crear soluciones que se basen en el flujo implícito OAuth con tokens de acceso de portador o que utilicen cookies o el almacenamiento del explorador para almacenar información confidencial. Dado que los elementos web del lado cliente se ejecutan como parte de la página, otros elementos de esa página también pueden acceder a todos estos recursos.
Usar cualquier biblioteca para compilar el elemento web
Al compilar personalizaciones mediante el elemento web Editor de scripts, es posible que haya usado bibliotecas como jQuery o Knockout para que la personalización sea dinámica y responda mejor a la interacción del usuario. Al compilar SharePoint Framework elementos web del lado cliente, puede usar cualquier biblioteca del lado cliente para enriquecer la solución, de la misma manera que lo habría hecho en el pasado. La ventaja adicional que le ofrece SharePoint Framework es el aislamiento del script. Aunque el elemento web se ejecuta como parte de la página, su script se empaqueta como un módulo que permite, por ejemplo, que distintos elementos web de la misma página usen una versión diferente de jQuery sin colisionar entre sí. Se trata de una característica eficaz que le permite centrarse en ofrecer valor empresarial en lugar de realizar migraciones técnicas y comprometer la funcionalidad.
Ejecutar como el usuario actual
En las personalizaciones creadas mediante el elemento web Editor de scripts, siempre que necesite comunicarse con SharePoint, todo lo que tenía que hacer era llamar a su API. La solución del lado cliente se ejecutaba en el explorador en el contexto del usuario actual y, al enviar automáticamente la cookie de autenticación junto con la solicitud, su solución podía conectarse directamente a SharePoint. No era necesaria ninguna autenticación adicional, como al usar complementos de SharePoint, para comunicarse con SharePoint. El mismo mecanismo se aplica a las personalizaciones creadas en el SharePoint Framework que también se ejecutan en el contexto del usuario autenticado actualmente y tampoco requieren ningún paso de autenticación adicional para comunicarse con SharePoint.
Usar solamente el código del lado cliente
Tanto las soluciones de SharePoint Framework como las del elemento web Editor de scripts se ejecutan en el explorador y solo pueden contener código JavaScript del lado cliente. Las soluciones del lado cliente tienen varias limitaciones, como no elevar los permisos en SharePoint o ponerse en contacto con API externas que no admiten la comunicación entre orígenes (CORS) o la autenticación mediante el flujo implícito de OAuth. En tales casos, la solución del lado cliente podría aprovechar una API remota del lado servidor para realizar la operación necesaria y devolver los resultados al cliente.
Hospedar la solución en SharePoint
Una de las ventajas de crear personalizaciones de SharePoint mediante elementos web del Editor de scripts fue el hecho de que su código se podía hospedar en una biblioteca de documentos normal de SharePoint. En comparación con los complementos de SharePoint, requería menos infraestructura y simplificaba el hospedaje de la solución. Además, las organizaciones podrían utilizar los permisos de SharePoint para controlar el acceso a los archivos de la solución.
Aunque hospedar las soluciones de SharePoint Framework en una CDN ofrece una serie de ventajas, esto no es imprescindible y, si lo desea, puede alojar su código en una biblioteca normal de documentos de SharePoint. SharePoint Framework paquetes (archivos *.sppkg) implementados en el catálogo de aplicaciones especifican la dirección URL en la que SharePoint Framework puede encontrar el código de la solución. No existen restricciones con respecto a lo que debe ser la dirección URL, siempre y cuando el usuario que examina la página con el elemento web pueda descargar el script desde la ubicación especificada.
Office 365 ofrece la funcionalidad de CDN pública, que permite publicar archivos de una biblioteca de documentos específica de SharePoint en una CDN. La CDN pública de Office 365 consigue un buen equilibrio entre las ventajas de utilizar una CDN y la simplicidad de alojar los archivos de código en una biblioteca de documentos de SharePoint. Si a su organización no le importa que los archivos de código estén disponibles públicamente, vale la pena considerar el uso de la CDN pública de Office 365.
Diferencias entre las soluciones de SharePoint Framework y las personalizaciones del elemento web Editor de scripts
Las personalizaciones de SharePoint creadas con el elemento web SharePoint Framework y editor de scripts son similares. Todos se ejecutan como parte de la página en el contexto del usuario actual y se generan mediante JavaScript del lado cliente. Pero también hay algunas diferencias significativas que pueden influir en las decisiones arquitectónicas y que debe tener en cuenta al diseñar la solución.
Ejecutar en sitios sin scripts
Al compilar personalizaciones del lado cliente mediante el elemento web Editor de scripts, tenía que tener en cuenta si el sitio donde se usaría la personalización era un sitio sin script o no. Si el sitio era un sitio sin script, tenía que solicitar al administrador que deshabilitara la configuración sin script o compilar la solución de forma diferente, por ejemplo, mediante el modelo de complemento.
Puesto que las soluciones de SharePoint Framework se implementan a través del catálogo de aplicaciones con una autorización previa, que no están sujetos a las restricciones sin scripts y funcionan en todos los sitios.
Implementar y actualizar a través de TI
Los elementos web del Editor de scripts se usan para crear personalizaciones de SharePoint principalmente por parte de desarrolladores ciudadanos. Solo con los permisos del propietario del sitio, los desarrolladores independientes pueden crear personalizaciones de SharePoint atractivas que agreguen valor empresarial. Cada vez que se debe actualizar la personalización, los usuarios con los permisos necesarios pueden aplicar actualizaciones a los archivos de script de la solución y los cambios son visibles inmediatamente para todos los usuarios.
Las soluciones de elementos web del Editor de scripts dificultan que las organizaciones de TI realicen un seguimiento de las personalizaciones que se usan y dónde se usan. Además, las organizaciones no pueden saber qué scripts externos se usan en la intranet y tienen acceso a sus datos.
SharePoint Framework devuelve el control a los profesionales de TI. Como las soluciones SharePoint Framework se implementan y administran centralmente en el catálogo de aplicaciones, las organizaciones tienen la oportunidad de revisar cada solución antes de implementarla. Además, las actualizaciones se implementan a través del catálogo de aplicaciones, lo que permite a las organizaciones comprobarlas y aprobarlas antes de su implementación.
Centrarse más en la experiencia de usuario uniforme
Al crear personalizaciones mediante el elemento web Editor de scripts, los desarrolladores ciudadanos poseen el DOM completo de su personalización. No había ninguna directriz relacionada con la experiencia del usuario y el funcionamiento de cada personalización. Como resultado, diferentes desarrolladores crearon personalizaciones de diferentes maneras, lo que condujo a una experiencia de usuario incoherente para los usuarios finales.
Uno de los objetivos de SharePoint Framework es estandarizar la compilación de personalizaciones del lado cliente para que sean uniformes en cuanto a implementación, mantenimiento y experiencia del usuario. Mediante Office UI Fabric, los desarrolladores pueden conseguir más fácilmente que sus soluciones personalizadas tengan el mismo aspecto y comportamiento que si formaran parte de SharePoint, lo que simplifica la adopción por parte del usuario. La cadena de herramientas de SharePoint Framework genera archivos de paquete para las soluciones que se implementan en el Catálogo de aplicaciones, así como conjuntos de scripts que se implementan en la ubicación de hospedaje de su elección. Todas las soluciones se estructuran y administran de la misma forma.
Sin modificar el DOM fuera de la personalización
Los elementos web del Editor de scripts se usaban con frecuencia en el pasado para modificar partes de la página, como agregar botones a la barra de herramientas o cambiar el encabezado o la personalización de marca de la página. Estas personalizaciones se basaban en la existencia de elementos DOM específicos y, cada vez que se actualizaba la interfaz de usuario de SharePoint, existía la posibilidad de que dicha personalización se interrumpiese.
SharePoint Framework promueve un enfoque más estructurado y fiable para personalizar SharePoint. En lugar de utilizar los elementos DOM específicos para personalizar SharePoint, SharePoint Framework proporciona a los desarrolladores una API pública que pueden utilizar para extender SharePoint. Los elementos web del lado cliente son la única forma admitida por el SharePoint Framework, pero otras formas, como equivalentes de JSLink y Acciones personalizadas de usuario, se tienen en cuenta para el futuro para que los desarrolladores puedan implementar los escenarios de personalización más comunes mediante el SharePoint Framework.
Distribución como paquetes
Las personalizaciones de SharePoint del lado cliente solían utilizar bibliotecas y listas de SharePoint para almacenar sus datos. Cuando se creaban mediante el elemento web Editor de scripts, no había ninguna manera fácil de aprovisionar automáticamente los requisitos previos necesarios. Para implementar una misma personalización en otro sitio, a menudo era necesario copiar el elemento web, pero también volver a crear y mantener correctamente el almacenamiento necesario para los datos.
SharePoint Framework soluciones se distribuyen, ya que los paquetes pueden aprovisionar sus requisitos previos, como campos, tipos de contenido o listas, automáticamente. Los desarrolladores que compilan el paquete pueden especificar qué artefactos necesita la solución y, cada vez que se instala en un sitio, se crean los artefactos especificados. Esto simplifica considerablemente el proceso de implementación y administración de la solución en varios sitios.
Usar TypeScript para compilar soluciones más sólidas y fáciles de mantener
Al compilar personalizaciones mediante el elemento web Editor de scripts, los desarrolladores ciudadanos suelen usar JavaScript sin formato. Estas soluciones no solían contener pruebas automatizadas, por lo que refactorizar el código era una operación propensa a errores.
SharePoint Framework permite a los desarrolladores beneficiarse del sistema de tipos TypeScript para compilar soluciones. Gracias al sistema de tipos, los errores se detectan durante el desarrollo, en lugar de en tiempo de ejecución. Además, es más fácil refactorizar el código, ya que los cambios en el código están protegidos por TypeScript. Puesto que todo el JavaScript es TypeScript válido, la barrera de entrada es baja y puede migrar su JavaScript a TypeScript gradualmente, lo que facilita aún más el mantenimiento de su solución.
No se puede confiar en el objeto spPageContextInfo
Al crear personalizaciones reutilizables del lado del cliente, en el pasado, los desarrolladores usaban el objeto JavaScript spPageContextInfo para obtener información sobre la página, el sitio o el usuario actual. Este objeto les ofrecía una manera fácil de hacer sus soluciones reutilizables en los distintos sitios de SharePoint sin tener que utilizar direcciones URL fijas.
Aunque el objeto spPageContextInfo sigue presente en las páginas clásicas de SharePoint, no se puede usar de forma fiable con las páginas y bibliotecas modernas de SharePoint. Para compilar soluciones de SharePoint Framework, se recomienda a los desarrolladores que usen en su lugar el objeto [IWebPartContext.pageContext](/javascript/api/sp-webpart-base/iwebpartcontext), que contiene la información de contexto de la solución en particular.
No hay acceso al modelo de objetos de JavaScript de SharePoint de forma predeterminada
Al crear personalizaciones de cliente para la experiencia del usuario clásica de SharePoint, muchos desarrolladores utilizaban el modelo de objetos de JavaScript (JSOM) para comunicarse con SharePoint. JSOM les ofrecía IntelliSense y fácil acceso a la API de SharePoint, de forma similar al modelo de objeto de cliente (CSOM). En las páginas clásicas de SharePoint, la parte principal de JSOM estaba presente en la página de forma predeterminada y los desarrolladores podían cargar fragmentos adicionales para, por ejemplo, comunicarse con SharePoint Search.
La experiencia del usuario de la versión moderna de SharePoint no incluye SharePoint JSOM de forma predeterminada. Aunque los desarrolladores lo pueden cargar por sí mismos, la recomendación es utilizar la API de REST en su lugar. REST es más universal e intercambiable entre las diferentes bibliotecas del lado cliente, como jQuery, Angular o React.
Microsoft ya no invierte activamente en JSOM. Si prefiere trabajar con una API, puede usar la biblioteca principal de JavaScript para modelos y prácticas de SharePoint, que ofrece una API fluida y términos de TypeScript.
Migrar una personalización existente a SharePoint Framework
La migración de personalizaciones de elementos web del Editor de scripts existentes a la SharePoint Framework ofrece a los usuarios finales y desarrolladores una serie de ventajas. Al considerar la posibilidad de migrar personalizaciones existentes a la SharePoint Framework, puede optar por reutilizar tantos scripts existentes como sea posible o volver a escribir completamente la personalización.
Reutilizar scripts existentes
Al migrar las personalizaciones de elementos web del Editor de scripts existentes a la SharePoint Framework, puede optar por reutilizar los scripts existentes. A pesar de que SharePoint Framework promueve el uso de TypeScript, puede usar JavaScript sin formato y transformarlo gradualmente en TypeScript. Si necesita admitir una solución determinada durante un período limitado de tiempo o con un presupuesto limitado, este enfoque puede resultar apropiado para usted.
No siempre es posible reutilizar los scripts existentes en una solución de SharePoint Framework. Por ejemplo, las soluciones de SharePoint Framework se empaquetan como módulos de JavaScript y se cargan de forma asincrónica en una página. Algunas bibliotecas de JavaScript no funcionan correctamente cuando se hace referencia a ellas en un módulo o cuando necesitan que la referencia se haga de una forma específica. Además, el hecho de depender de eventos de página como onload() o de usar la función ready() de jQuery podría producir resultados no deseados.
Dada la variedad de bibliotecas de JavaScript, no hay ninguna manera fácil de indicar por adelantado si los scripts existentes se pueden reutilizar en una solución de SharePoint Framework o si necesita volver a escribirlos después de todo. La única manera de determinarlo consiste en intentar mover las distintas partes a una solución de SharePoint Framework y ver si funcionan como se espera.
Volver a escribir la personalización
Si necesita admitir la solución durante un período de tiempo más largo, le gustaría hacer un mejor uso de la SharePoint Framework o si resulta que los scripts existentes no se pueden reutilizar con el SharePoint Framework, es posible que tenga que volver a escribir completamente la personalización. Aunque es más costoso que reutilizar los scripts existentes, ofrece mejores resultados durante un período de tiempo más largo: una solución que tiene un mejor rendimiento y es más fácil de mantener y usar.
Al volver a escribir una personalización de elementos web del Editor de scripts existente en una solución de SharePoint Framework, debe empezar teniendo en cuenta la funcionalidad deseada. Para implementar la experiencia del usuario, debe considerar el uso de Office UI Fabric para que la solución parezca parte integrante de SharePoint. Para determinados componentes como gráficos o controles deslizantes, debe intentar buscando bibliotecas modernas que se distribuyan como módulos y tengan tipos de TypeScript. Esto facilita la integración del componente en la solución.
Aunque no hay una sola respuesta sobre qué componente es mejor para cada escenario, SharePoint Framework es lo bastante flexible como para adaptarse a los escenarios más populares, y debería poder transformar sus personalizaciones existentes del lado cliente en soluciones completas de SharePoint Framework.
Consejos para la migración
Hay algunos patrones comunes a la hora de transformar las personalizaciones existentes del elemento web Editor de scripts en SharePoint Framework.
Mover el código existente a SharePoint Framework
Las personalizaciones de SharePoint creadas mediante el elemento web Editor de secuencia de comandos suelen consistir en marcado HTML incluido en el elemento web y una o más referencias a archivos JavaScript. A la hora de transformar la personalización existente en una solución de SharePoint Framework, probablemente haya que mover el formato HTML del elemento web Script Editor al método render() del elemento web del lado cliente de SharePoint Framework. Las referencias a scripts externos se cambiarán a referencias en la propiedad externals del archivo ./config/config.json. Los scripts internos se copiarían en la carpeta de origen del elemento web y se haría referencia a ellos desde la clase del elemento web mediante instrucciones require().
Hacer referencia a funciones desde archivos de script
Para hacer referencia a funciones de archivos de script, estas funciones deben definirse como una exportación. Considere la posibilidad de usar un archivo JavaScript existente en un elemento web del lado cliente SharePoint Framework:
var greeting = function() {
alert('How are you doing?');
return false;
}
Para poder llamar a la función greeting desde la clase del elemento web, deberá cambiar el archivo JavaScript a:
var greeting = function() {
alert('How are you doing?');
return false;
}
module.exports = {
greeting: greeting
};
Después, en la clase del elemento web, puede hacer referencia al script y llamar a la función greeting:
public render(): void {
this.domElement.innerHTML = `<input type="button" value="Click me"/>`;
const myScript = <any> require('./my-script.js');
this.domElement.querySelector('input').addEventListener('click', myScript.greeting);
}
Ejecutar llamadas AJAX
Muchas personalizaciones del lado cliente utilizan jQuery para ejecutar peticiones de AJAX por su simplicidad y compatibilidad con distintos exploradores. Si esto es todo lo que usa jQuery para, puede ejecutar las llamadas AJAX mediante el cliente HTTP estándar proporcionado con el SharePoint Framework.
SharePoint Framework ofrece dos tipos de cliente HTTP: el cliente SPHttpClient, pensado para ejecutar peticiones a la API de REST de SharePoint, y el cliente HttpClient diseñado para emitir solicitudes web a otras API de REST. A continuación se muestra cómo ejecutaría una llamada mediante SPHttpClient para obtener el título del sitio de SharePoint actual:
this.context.spHttpClient.get(`${this.context.pageContext.web.absoluteUrl}/_api/web?$select=Title`,
SPHttpClient.configurations.v1,
{
headers: {
'Accept': 'application/json;odata=nometadata',
'odata-version': ''
}
})
.then((response: SPHttpClientResponse): Promise<{Title: string}> => {
return response.json();
})
.then((web: {Title: string}): void => {
// web.Title
}, (error: any): void => {
// error
});