Desarrollo con SharePoint Framework

Escrito por Luis Valencia - 30/11/2016

En el pasado tuvimos "SharePoint Solutions", para aquellos de nosotros que somos lo suficientemente mayores y comenzamos con WSS 3.0, SharePoint 2003 o 2007, esta era la única manera de desarrollar soluciones en ese momento. Tuvimos que crear nuestras soluciones con código C #, código que crea páginas, WebParts, listas, Features, Timer Jobs, etc. Hasta el año 2012 fue la manera más popular para desarrollar en SharePoint, pero después de SharePoint 2013 Microsoft comenzó a cambiar su visión, Office 365 es un producto muy importante en la vision de Microsoft, en ese momento se introdujo los SharePoint Add-Ins (anteriormente conocido como SharePoint Apps), con este modelo de desarrollo podemos crear Add-In con C #, pero el código estaba alojado en otro servidor, IIS o Azure, con las API CSOM que puede interactuar con datos de SharePoint, e integrar SharePoint con miles de otras API #. Con SharePoint Hosted Add-Ins, sólo podemos desarrollar con javascript, el código se ejecuta en el navegador, pero con las API REST también podemos interactuar con los datos de SharePoint y combinar varios plugins javascript para llegar a soluciones bien interestantes.

Estas 2 últimas piezas están todavía en funcionamiento, y es probable que sobrevivan durante mucho tiempo, son muy potentes y probablemente tendrán espacio en muchos blogs durante los próximos años. Sin embargo desde mayo de 2016, Microsoft ha anunciado la introducción del SharePoint Framework, también conocido como SPF, este nuevo framework y cito es un:

Modelo de desarrollo de WebParts que permite y soporte plenamente el desarrollo del lado del cliente, fácil integración con el Microsoft Graph y soporte para herramientas de código abierto.

Esta nuevo Framework es espectacular, es de código abierto, por lo que cualquiera de ustedes puede colaborar con el repositorio GitHub, y una de las cosas que me gustan de él, que Microsoft sí lo están utilizando para construir las nuevas experiencias de SharePoint, por ejemplo, el look and feel de la nueva Biblioteca de documentos, entre otras cosas que se han dado a conocer los últimos meses.

Con cada nueva tecnología, llega un reto, un desafío para aprender algo nuevo, debido a que SPF esta basado en las últimas tecnologías de código abierto voy a mencionar lo que se necesita para aprender:

·       Obligatorio: 

1.       TypeScript.

2.       NodeJS. 

3.       NPM (gesto de paquetes como nuget). 

4.       Gulp.

·       No es obligatorio :

1.        React. 

2.       Angular

3.       Cualquier otro framework de JS.

A pesar de que menciono que no son obligatorios, hoy en día es importante tener el conocimiento en alguno de estos para entregar mejores soluciones. En este post vamos a aprender como configurar el ambiente para el desarrollo de WebParts con SharePoint Framework.

Cómo empezar

PASO 1:

1.       Obtener un developer tenant de Office 365

Con el fin de construir y desplegar elementos Web en SharePoint durante la vista previa inicial, se necesita un Tenant de Desarrollo Office  365. Tenga en cuenta que, por ahora, el tenant  tiene que ser un tenant  desarrollador, no sólo la colección de sitios.

Si está recibiendo siguiente excepción cuando se mueve a workbench.aspx página, significa que no está utilizando el tenant de desarrollo: "La operación solicitada es parte de una característica experimental que no se admite en el entorno actual . la operación solicitada es parte de una característica experimental que no se admite en el entorno actual

2.       Crear un sitio catálogo de aplicaciones.

Si usted es como yo y ya ha utilizado el modelo de complementos, entonces usted ya debe saber cómo crear una, si no seguir leyendo:

·       Navegar a SharePoint Centro de administración escribiendo el siguiente URL en su navegador (Sustituir yourtenantprefix con su prefijo de Office 36)

https://yourtenantprefix-admin.SharePoint.com

·       En la barra lateral izquierda, haga clic en el elemento de menú de aplicaciones y haga clic en App Catalog.

·       Haga clic en el botón Aceptar para crear un nuevo sitio catálogo de aplicaciones.

·       En la página siguiente, introduzca los siguientes datos:

Título: Aplicación catálogo

Sitio Web Dirección sufijo: Llene sufijo preferido para catálogo de aplicaciones, por ejemplo: aplicaciones

Administrador: Introduzca su nombre de usuario y haga clic en el botón de decisión para resolver el nombre de usuario

·       Haga clic en el botón OK para crear el sitio catálogo de aplicaciones. SharePoint en este momento va a crear el sitio catálogo de aplicaciones y usted será capaz de ver su progreso en el centro de administración de SharePoint

3.       Crear una nueva colección de sitios desarrollador. *

·       Navegar a SharePoint Centro de administración escribiendo el siguiente URL en su navegador.

Sustituir yourtenantprefix con su prefijo de Office 365:

https://yourtenantprefix-admin.SharePoint.com

·       En la cinta de SharePoint, haga clic nuevo-> Colección privada de sitios.

·       En el cuadro de diálogo, introduzca lo siguiente:

Título: escriba un título para su colección de sitio de desarrolladores, por ejemplo: desarrollador del sitio

Sitio Web Dirección sufijo común: Introduzca un sufijo para la colección de sitios desarrollador, por ejemplo: dev

Selección de plantilla: Seleccione Sitio desarrollador como la plantilla colección de sitios

Administrador: Introduzca su nombre de usuario y haga clic en el botón de decisión para resolver el nombre de usuario

·       Haga clic en el botón Aceptar para crear la colección de sitios.

4.       Configuración de biblioteca de documentos

Con el fin de depurar y tener vista previa de los WebParts necesitamos cargar la página workbench.aspx, también tenemos que crear una nueva columna, las instrucciones son las siguientes:

·       Crear la nueva columna.

·       Siga los pasos de abajo para agregar el nuevo campo a la Biblioteca Documentos:

o   Haga clic en el icono de engranajes en la parte superior derecha y haga clic en Configuración del sitio para abrir la página de configuración.

o   Haga clic en las bibliotecas y las listas del sitio en la categoría Administración de sitios.

o   Haga clic en Personalizar Documentos

o   Ahora, haga clic en Crear columna en Columnas:

§  Tipo ClientSideApplicationId como el nombre de la columna y dejar otros campos como son.

o   Haga clic en el botón Aceptar para crear la columna.

·       Luego sube el workbench.aspx, última versión se puede encontrar aqui: https://github.com/SharePoint/sp-dev-docs/wiki/Setup-SharePoint-Tenant

5.       Configuración del entorno de desarrollo

Algo nuevo aquí, ahora podemos desarrollar con un sistema operativo MAC, ¿no es genial? primera vez que las herramientas son tan ampliamente disponibles a través de sistemas operativos para construir las nuevas experiencias de SharePoint. 

a.       Instalar nodejs LTS (Long Term Support) versión. 
Descargar desde aquí.

b.       Instalar NPM. Abra un símbolo del sistema y pegue el siguiente código:

npm -g install npm@next

c.       Si está utilizando Windows instalar este paquete:

npm install --global --production windows-build-tools 

d.       Instalar VS CODE. Descargar desde aquí.

e.       Instalar Yeoman y gulp. Abrir y ejecutar CMD.

npm i -g yo gulp

f.        Instalar Yeoman SharePoint generador.

npm i -g @microsoft/generator-SharePoint nt

Las herramientas anteriores son de código abierto y ampliamente utilizados en la comunidad por otro tipo de desarrollos, también son ampliamente utilizados en el nuevo ASP.NET core, así que aprender un poco acerca de ellos es un deber.

Nuestro Primer WebPart

Ahora, vamos a hacer un WebPart fácil, un WebPart que tenga una propiedad sencilla y se pueda ver el valor de esa propiedad dinámicamente. En primer lugar lo que tenemos que saber que lo que estamos construyendo aquí es puro WebPart del lado del cliente. Los WebParts del lado del cliente ya son soportados en SharePoint y en Office 365, pero de una manera diferente, se puede añadir un editor de código, y pegar el código JavaScript y HTML, no tendrán ningún problema, pero el problema con este enfoque es el mantenimiento, el código reside en una página, en la sección de código de un elemento Web, no hay manera de controlar el código fuente con TFS o Git.

En este punto, podemos usar CMD para algunos de los comandos que necesitamos para ejecutar, pero quiero introducir una herramienta que algunos de ustedes pueden no conocer, CMDER, un gran reemplazo con una mejor apariencia y características avanzadas. Puede descargarlo aquí.

Paso 1

Vamos a crear nuestro directorio donde almacenaremos nuestra solución.

mkdir OurFirstSPFApp 

cd OurFirstSPFApp 

Paso 2

Crear el proyecto WebPart, para ello vamos a utilizar el generador Yeoman que construimos en el paso anterior

yo @microsoft/SharePoint 

Se le pedirá una serie de preguntas:

·       Aceptar el nombre por defecto como su nombre de la solución y pulse Enter. 
Seleccione Usar la carpeta actual para colocar los archivos.

·       El siguiente conjunto de instrucciones le pedirá información específica acerca de su WebPart:

o   Aceptar el nombre por defecto como nombre de elemento Web y pulse Enter. 
Acepte la descripción predeterminada como su descripción de elementos Web y pulse Enter. 

o   Aceptar el valor predeterminado No JavaScript Framework web como el Framework que desea utilizar y pulse Enter.

Imagen 1.- Configuración de Yeoman. 

·       Yeoman instalará todas las dependencias necesarias y la estructura del proyecto, como se muestra aquí: 

Imagen 2.- Instalación de las dependencias necesarias para Yeoman. 

Paso 3

Se puede utilizar cualquier editor de código que te gusta, a mi me gusta VS Code, y eso es lo que veras en las capturas de pantalla. Para abrir la parte web en VS Code sólo tiene que escribir:

code . 

Etapa 4

Ahora necesitamos una vista previa de nuestra web part, para eso tenemos que depender de gulp, gulp es un administrador de tareas que se encarga de construir procesos tales como:

·       Combinar y minificar JavaScript y CSS. 

·       Ejecutar herramientas para llamar a las funciones de empaquetamiento y minificación antes de cada compilación. 

·       Compilar archivos SASS en CSS. 

·       Compilar los archivos de Typescript a JavaScript. En un futuro post vamos a personalizar el proceso de construcción con gulp. Por ahora, vamos a utilizar el siguiente comando:

gulp serve 

Imagen 3.- Creación del servidor de NodeJS. 

·       Esto creará un servidor NodeJS local. Una vez que corremos gulp serve un navegador se abrirá con nuestro workbench de trabajo local, este es el lugar donde vamos a editar nuestra página y agregar el elemento Web para la prueba. 

Imagen 4.- Workbench local. 

Paso 5

Vamos a compilar nuestro proyecto. Visual Studio Code proporciona soporte incorporado para el Gulp y otros administradores de tareas. Puede presionar Ctrl + Shift + B si está en Windows o Cmd + Shift + B si se encuentra en Mac para compilar, depurar y tener vista previa del WebPart.

Una vez que hagas esto, usted será capaz de ver en la ventana de resultados como el proyecto se está construyendo.

Imagen 5.- Resultados de la compilación del proyecto. 

Ahora puede agregar el elemento Web a su página:

Imagen 6.- Agregando un WebPart en una página. 

Y verlo en acción, 

Imagen 6.- WebPart añadida. 

Paso 5

Vamos a aprender acerca de la estructura del proyecto:

Imagen 7.- Estructura del proyecto. 

El SRC es donde toda la magia sucede, esto es la carpeta que realmente importa, y en la que se codifica.

TypeScript es el idioma principal para construir WebParts de SharePoint del lado del cliente. TypeScript es un superconjunto escrito de JavaScript que se compila en pleno JavaScript. Las herramientas de desarrollo del lado del cliente de SharePoint se construyen utilizando clases de TypeScript, módulos e interfaces para ayudar a los desarrolladores a crear piezas solidas para los Web parts del lado del cliente.

Paso 6

Vamos a dar un paseo a través del código y los archivos más importantes:

·       OurFirstSpAppWebPart.ts La clase de elemento Web.

·       OurFirstSpAppWebPart.ts define el punto de entrada principal para su WebPart en la que la clase OurFirstSpAppWebPart extiende la clase BaseClientSideWebPart. Cualquier Web Part del lado del cliente se debe extender esta clase.

public constructor(context: IWebPartContext) { 

    super(context);

}

·       BaseClientSideWebPart implementa la funcionalidad mínima que se requiere para construir una WebPart. Esta clase también ofrece un montón de parámetros para validar y acceder a las propiedades de sólo lectura, como displayMode, propiedades de elementos web, el contexto, el instanceId del WebPart, el DOMElement y mucho más. Nótese que también estamos definiendo nuestra clase de Web Part para aceptar un tipo de propiedad IOurFirstSpfAppWebPartProps.

·       Las propiedades se definen en una interfaz en un IOurFirstSpfAppWebPartProps.ts

export interface IOurFirstSpfAppWebPartProps { 

  description: string;

}

·       Esta definición de la propiedad se utiliza para definir los tipos de propiedades personalizados para su web part, lo que vamos a ver en el panel de propiedades.

·       Parte de Web render (). El elemento DOM donde del WebPart se mostrara es en el método render. Este método se utiliza para representar la web part dentro de ese elemento DOM. En nuestra web part OurFirstSpfAppWebPart, se pasa en el DIV para el elemento DOM. Los parámetros del método incluyen el modo de visualización (ya sea de lectura o de edición) y las propiedades de la web part configurados si los hubiere:

import { 

  BaseClientSideWebPart,

  IPropertyPaneSettings,

  IWebPartContext,

  PropertyPaneTextField

} from '@microsoft/sp-client-preview';

import styles from './OurFirstSpfWebPart.module.scss'; 

import * as strings from 'ourFirstSpfWebPartstrings'; 

import { IOurFirstSpfWebPartWebPartProps } from './IOurFirstSpfWebPartWebPartProps';

 

export default class OurFirstSpfWebPartWebPart extends BaseClientSideWebPart<IOurFirstSpfWebPartWebPartProps> {

  public constructor(context: IWebPartContext) {

    super(context);

  }

public render(): void { 

  this.domElement.innerHTML = `

    <div class="${styles.helloWorld}">

      <div class="${styles.container}">

        <div class="ms-Grid-row ms-bgColor-themeDark ms-fontColor-white ${styles.row}">

          <div class="ms-Grid-col ms-u-lg10 ms-u-xl8 ms-u-xlPush2 ms-u-lgPush1">

            <span class="ms-font-xl ms-fontColor-white">Welcome to SharePoint!</span>

            <p class="ms-font-l ms-fontColor-white">Customize SharePoint experiences using Web Parts.</p>

            <p class="ms-font-l ms-fontColor-white">${this.properties.description}</p>

            <a href="https://github.com/SharePoint/sp-dev-docs/wiki" class="ms-Button ${styles.button}">

              <span class="ms-Button-label">Learn more</span>

            </a>

          </div>

        </div>

    </div>

  </div>`;

}

Analicemos este código, el más importante, como se puede ver que importamos los estilos de un CSS, pero lo que es más sorprendente de TypeScript es que podemos reemplazar estilos dinámicamente usando variables, como por ejemplo:

${styles.helloWorld}

También aquí se puede ver que podemos utilizar:

${this.properties.description}

Para utilizar las propiedades del panel de propiedades, pero ¿qué pasa si queremos hacer algo más interesante, lo que yo quiero que se fijen es algo llamado el panel de propiedades reactiva, podemos explicar sobre esto más adelante, pero básicamente lo que se ingrese o seleccione en sus propiedades se refleja inmediatamente en su web part en tiempo real, como llamados servicios web, actualización de valores, etc.

Para el ejemplo, he agregado 2 propiedades en el archivo: IOurFirstSpfWebPartWebPartProps.ts

export interface IOurFirstSpfWebPartWebPartProps { 

  description: string;

  n1: string;

  n2: string;

}

Luego he añadido estas propiedades en el manifest.json:

{

  "$schema": "../../../node_modules/@microsoft/sp-module-interfaces/lib/manifestSchemas/jsonSchemas/clientSideComponentManifestSchema.json",

  "id": "1ac1bfca-4ac6-4bb8-906e-6715ab383a2b",

  "componentType": "WebPart",

  "version": "0.0.1",

  "manifestVersion": 2,

  "preconfiguredEntries": [{

    "groupId": "1ac1bfca-4ac6-4bb8-906e-6715ab383a2b",

    "group": { "default": "Under Development" },

    "title": { "default": "OurFirstSpfWebPart" },

    "description": { "default": "OurFirstSPFWebPart description" },

    "officeFabricIconFontName": "Page",

    "properties": {

      "description": "OurFirstSpfWebPart",

       "n1": "1",

       "n2": "2"

    }

  }]

}

Y, finalmente, en mi método render he utilizado estos para sumar 2 números.

  public render(): void {

    this.domElement.innerHTML = `

      <div class="${styles.ourFirstSpfWebPart}">

        <div class="${styles.container}">

          <div class="ms-Grid-row ms-bgColor-themeDark ms-fontColor-white ${styles.row}">

            <div class="ms-Grid-col ms-u-lg10 ms-u-xl8 ms-u-xlPush2 ms-u-lgPush1">

              <span class="ms-font-xl ms-fontColor-white">Welcome to SharePoint!</span>

              <p class="ms-font-l ms-fontColor-white">Customize SharePoint experiences using Web Parts.</p>

              <p class="ms-font-l ms-fontColor-white">${parseInt(this.properties.n1)+parseInt(this.properties.n2)}</p>

              <a href="https://github.com/SharePoint/sp-dev-docs/wiki" class="ms-Button ${styles.button}">

                <span class="ms-Button-label">Learn more</span>

              </a>

            </div>

          </div>

        </div>

      </div>`;

  }

Como puedes ver la sintaxis es muy parecida a Angular donde de alguna manera se enlaza lo que se esta digitando en el panel de propiedades, con lo que queremos que haga nuestro WebPart.

El resultado final

Imagen 8.- Resultado final obtenido. 

 

Luis Valencia
Office Servers & Services MVP
le.valencia@outlook.com

@levalencia

http://www.luisevalencia.com

***