Tipos de géneros de libros - Crear componente SPfx

Hola a todo@s, continuando con la serie de entradas en el blog La Librería, en esta entrada se busca tener el primer contacto con el componente SPfx para SharePoint Online, que se encargara de la gestión de los tipos de géneros de libros.

El concepto de un componente SPfx, es el de un Web Part de la versión SharePoint on-premise, pero se desarrolla con tecnologías del lado del cliente como son JavaScript o React.js.

Los objetivos que se pretende enseñar en esta entrada son los siguientes:

Definir y crear el componente SPfx para SharePoint Online.
Adaptar la configuración inicial del componente SPfx a las necesidades del ejercicio.

Definir y crear el componente SPfx

Para la creación del componente SPfx para SharePoint Online, se ha tomado como referencia la página oficial de Microsoft, en el siguiente enlace Build your first SharePoint client-side , donde se muestra un ejemplo y se ha adaptado a las necesidades de este ejercicio.

Los pasos para definir y crear nuestro componente SPfx son los siguientes:

Abrir un terminal de consola o si se prefiere Visual Studio Code, donde poder ejecutar el comando de definir y crear el componente SPfx.
Ubicar el terminal, en la carpeta donde se quiere alojar todo lo necesario para construir el componente SPfx. Recordad la importancia de disponer de un control de versiones para este tipo de proyectos.
Ejecutar el comando de creación de un componente SPfx en el terminal seleccionado.
```
yo @microsoft/sharepoint
```

Automáticamente en el terminal, se visualizarán una serie de preguntas, que definirán las características del componente SPfx. A continuación, se exponen las preguntas y las respuestas aportadas al asistente.

Preguntas del asistente	Respuesta al asistente
What is your solution name?	Dejar el valor predefinido que proporciona el asistente. El valor predefinido para el nombre de la solución es el mismo nombre de la carpeta donde se va a ubicar el proyecto SPfx.
Which baseline packages do you want to target for your component(s)?	Seleccionar la opción SharePoint Online only (latest) si solo se va a desarrollar para SharePoint Online.
Where do you want to place the files?	Seleccionar la opción Use the current folder para ubicar todo el contenido del proyecto en la carpeta que se definio en pasos anteriores.
Do you want to allow the tenant admin the choice of being able to deploy the solution to all sites immediately without running any feature deployment or adding apps in sites?	Seleccionar la opción No, ya que no se va a tratar nada de las actualizaciones en el Tenant.
Will the components in the solution require permissions to access web APIs that are unique and not shared with other components in the tenant?	Seleccionar la opción No, ya que no se va a trabajar nada con referencia a permisos entre componentes en el Tenant.
Which type of client-side component to create?	Seleccionar la opción WebPart, ya que el componente SPfx no va a cambiar ciertos comportamientos propios de SharePoint Online, como puede ser listas o menús contextuales.
What is your name?	Se introduce el título del desarrollo, que en este caso es Manager types of book genres.
What is your description?	Dejar el valor predefinido. Mas a delante en esta entrada se indicará como modificar este contenido.
Which framework would you like to use?	En este ejercicio, se ha seleccionado la opción React, a pesar de que la opción que indica el ejemplo de Microsoft es No javascript web framework, por los siguientes motivos: La tendencia de los desarrollos front-end del año 2018 y siguientes años, es la utilización del framework de React.js. Al trabajar con este framework y si decido apartarme de la senda de SharePoint, dispongo de conocimientos, como para no estar en un callejo sin salida. La utilización de React, como framework, implica que ciertos desarrolos se realicen de una forma diferente al del ejemplo de Microsoft, pero tan validos como los demás.

Con la finalización de las preguntas por parte del asistente, se inicia el proceso de creación del proyecto SPfx.

Asistente del proceso de creación del componente SPfx

Finalización del proceso de creación del componente SPfx
Terminado el proceso de creación del proyecto SPfx, solo hay que ejecutar el comando de activación del servidor de Gulp para ver en funcionamiento nuestro proyecto.
```
gulp serve
```
Aviso importante: Antes de ejecutar el servidor de Gulp, es necesario instalar un certificado de desarrollo, con la siguiente sentencia. Esta sentencia solo hay que ejecutarlo una única vez.
```
gulp trust-dev-cert
```
Ejecutando el servidor de Gulp
Con la ejecución en marcha del servidor de Gulp, se abrirá de forma automática el navegador por defecto, que emulará un entorno de SharePoint Online. Se selecciona el componente SPfx, que se acaba de crear y se visualizará su funcionalidad por defecto.

Se selecciona el componente SPfx que se acaba de crear con el asistente

Visualización del componente SPfx con el diseño por defecto

Realizados estos sencillos pasos, ya se dispone de un componente SPfx, para desarrollar el gestor de tipos de géneros de libros para La librería.

Adaptar la configuración inicial del componente SPfx

Antes de continuar desarrollando el componente de SPfx para la gestión de tipos de géneros de libros, es necesario realizar configuraciones en ciertos aspectos, para facilitar nuestra forma de implementar y manejar el proyecto.

Configurar paquete del componente SPfx

El propósito de este apartado es la de realizar ajustes relacionados con el paquete instalación del componente SPfx, que se importa en la colección de sitios de tipo catálogo. Se van a aspectos como el logotipo, propiedades o nombres del SPfx.

Actualizar logotipo del SPfx

Para cambiar el logotipo que tiene asociado el componente SPfx, se puede hacer de diversas formas, según el manual que tiene Microsoft, en el enlace Configure icon. Para este ejercicio se ha optado por colocar un logotipo personalizado. Los pasos realizados son los siguientes:

Acceder al fichero con extensión .manifest.json que hay en el proyecto. En este ejercicio el fichero se llama ManagerTypesOfBookGenresWebPart.manifest.json.
En el contenido del fichero Json, ubicarse en la sección preconfiguredEntries.
Se remplazar la propiedad officeFabricIconFontName por la propiedad iconImageUrl. El valor de la nueva propiedad es una imagen codificada en Base64.

En el enlace Base64 Image Encoder, se disponéis de una herramienta para convertir imágenes en Base64.

Configuración del icono del componente SPfx
Se guardan los cambios y se vuelve a ejecutar el servidor de Gulp, para visualizar el nuevo icono del componente SPfx.

Comprobación del cambio de icono en el componente SPfx

Establecer el título y la descripción en múltiples idiomas

Tal vez, a la hora de desarrollar un componente SPfx, resulta que el sitio web al que esta destinado, está en otro idioma distinto al inglés. Y si la gente no sabe inglés, se les puede facilitar el trabajo, colocando el título y la descripción del componente en el idioma del sitio web, con unos simples pasos:

Acceder al fichero con extensión .manifest.json que hay en el proyecto. En este ejercicio el fichero se llama ManagerTypesOfBookGenresWebPart.manifest.json.
En el contenido del fichero Json, ubicarse en la sección preconfiguredEntries y posteriormente, las subsecciones title y description, se inserta a continuación a la propiedad default, las propiedades es-es y en-us con sus valores correspondientes en su idioma.

Ya de paso, se aprovecha para cambiar la descripción del SPfx, que en pasos anteriores se había dejado el valor sugerido por el asistente de creación de SPfx.

Configuración del título y descripción para otros idiomas en el componente SPfx
Se guardan los cambios y se vuelve a ejecutar el servidor de Gulp.

Nota: Si se quiere ver los cambios realizado en el título y descripción del componente en otro idioma, hay que agregar el paquete del componente en la colección de sitios del cátalo del Tenant.

Eliminar propiedad sin usabilidad en el SPfx

En SharePoint on-premise, al crear un web part, se creaba una propiedad pública de ejemplo para que se introdujera contenido en una caja de texto y se visualizará en la renderización del control. En la versión de SPfx, también se dispone de una propiedad pública de ejemplo, que no es necesaria para este ejercicio, por lo que se va a proceder a su eliminación.

Propiedad ‘Description Field’ del componente SPfx que se quiere eliminar

La eliminación de la propiedad pública Description Field del componente SPfx, se realiza en los siguientes pasos:

Acceder al fichero con extensión .manifest.json que hay en el proyecto. En este ejercicio el fichero se llama ManagerTypesOfBookGenresWebPart.manifest.json.
En el contenido del fichero Json, ubicarse en la sección preconfiguredEntries y posteriormente, en la subsección properties, donde se procede a eliminar la propiedad description que es la encargada de dar un valor inicial a la propiedad Description Field al agregar el SPfx en la página.

Eliminar el valor inicial de la propiedad ‘Description Field’
Acceder al fichero mystrings.d.ts y eliminar las definiciones de las propiedades BasicGroupName y DescriptionFieldLabel del interfaz IManagerTypesOfBookGenresWebPartStrings.

Eliminación de las definiciones del fichero de recursos del componente SPfx
Acceder al fichero en-us.js y eliminar las propiedades BasicGroupName y DescriptionFieldLabel de la definición de literales del fichero de recursos del SPfx.

Ya de paso, se aprovecha para poner una descripción en el panel de las propiedades del SPfx.

Eliminar del fichero de recursos los literales de la propiedad y el grupo del componente SPfx
Acceder al fichero ManagerTypesOfBookGenresWebPart.ts y en el método getPropertyPaneConfiguration se elimina el grupo definido en el panel de configuraciones del SPfx.

Eliminación de la configuración del Grupo y sus propiedades en el componente SPfx
Acceder al fichero ManagerTypesOfBookGenresWebPart.ts y en el método render se elimina la propiedad descripcion de los valores iniciales del SPfx, debido a que ya no se dispone de la caja de texto que proporciona la información de esta propiedad.

Se elimina el proceso de pasar el valor de la caja de texto a la implementación del componente SPfx
Acceder al fichero IManagerTypesOfBookGenresProps.ts y en el interfaz IManagerTypesOfBookGenresProps eliminar la propiedad description.

El fichero IManagerTypesOfBookGenresProps se encarga de definir las propiedades que recibe el SPfx, al ser instanciado.

Se elimina el proceso de pasar el valor de la caja de texto a la implementación del componente SPfx
Acceder al fichero ManagerTypesOfBookGenres.tsx que es el encargado de renderizar el HTML del SPfx y en el método render, se elimina la utilización de la propiedad description de la variable props del componente.

Se elimina la utilización de la propiedad ‘description’ de los ‘Props’ del componente SPfx en su renderización

Realizados los cambios mencionados, al vuelve a ejecutar el servidor de Gulp, y al editar el SPfx, se comprueba que la propiedad Description ya o está definida en el panel de las características del componente SPfx.

Ejemplo de cómo quedaría el componente SPfx sin la propiedad por defecto

Eliminar interfaz de usuario inicial

El diseño que se proporciona al crear el componente SPfx del ejercicio, no es el más acorde con las pretensiones que se tiene para la librería, se va a proceder a dejar el diseño original a la mínima expresión para su ejecución. Los pasos que se aplican son los siguientes:

Acceder al único fichero con extensión .tsx. En este ejercicio el fichero se llama ManagerTypesOfBookGenres.tsx.
En el contendido del fichero, acceder hasta el método público render, que es el encargado de renderizar el HTML, eliminar todo el contenido que hay dentro de la etiqueta Div que usa la clase container.

Eliminación del renderizado inicial del componente SPfx
Acceder al fichero ManagerTypesOfBookGenres.module.scss que el encargado de las hojas de estilos, y se ha reducido a la mínima expresión par su correcta comportamiento al compilar.

En un principio no es necesario de aplicar hojas de estilo de tipo RESET para que el diseño del componente SPfx, este idéntico entre los diferentes navegadores.

Reducción de los estilos del componente SPfx al mínimo

Con los cambios realizados, ya se dispone de un interfaz de usuario limpio y preparado para el desarrollo de nuestro componente SPfx.

Ejemplo de la renderización del componente SPfx sin diseño predefinido

Agregar ficheros de recursos de idiomas

En los tiempos en donde las empresas se expanden para ganar más cuota de mercado, surge la necesidad de realizar componentes SPfx que se adapten los idiomas de cada cliente. En el ejercicio, se va a explicar cómo se manejan los ficheros de recursos con múltiples idiomas.

La adaptación de los componentes SPfx, a la utilización de ficheros de recursos, no es complicado si se siguen una serie de pautas y recomendaciones:

Al crear el componente SPfx, el idioma predeterminado con el que se configura es el inglés estadounidense y viene representado por el fichero de recursos en-us.js en la carpeta loc. Para crear el fichero de recursos en español, se realizará una copia del fichero original y se renombrará con el nombre es-es.js.
El nuevo fichero contiene las configuraciones y los literales del idioma inglés, por lo que se procederá a traducir su contenido actual.

Nuevo fichero de recursos del componente SPfx
La utilización del fichero de recursos en los componentes SPfx, se realiza con la importación de su modulo.

Como ejemplo al manejo de los ficheros de recursos, se va a proceder a visualizar en el interfaz de usuarios, el contenido de una propiedad del fichero de recursos, a través de la variable declarada en la importación del módulo.

Ejemplo de utilización de los ficheros de recursos en el componente SPfx
Si se ejecuta el servidor de Gulp con los parámetros por defecto en el terminal, los literales se visualizarán en inglés, mientras que, si el ejecuta el servidor de Gulp indicándole que use la cultura en español, los literales se visualizarán en español.

Literales en ingles ejecutando el servidor de Gulp por defecto
```
gulp serve
```
Literales en español ejecutando el servidor de Gulp con cultura en español
```
gulp serve --locale=es-Es
```

Recomiendo las siguientes pautas a la hora de manejar los ficheros de recursos para agilizar los desarrollos:

No colocar los literales del fichero de recurso, como si fuera un cajón desastre, recomiendo agrupar en la médica de lo posible los literales.
Intentar llevar la misma estructura de contenido entre diferentes ficheros de recursos.
Intentar reutilizar literales para las mismas acciones, para evitar duplicidades.

Para poder agregar más literales a los ficheros de recursos es necesario definir los literales, en el fichero mystrings.d.ts y propagar esas definiciones a los ficheros de idiomas.

Configurar state del componente SPfx

Para evitar tener un problema a la hora de manejar el state del componente principal del componente SPfx, hay que hacer los siguientes pasos:

Acceder al único fichero con extensión .tsx. En este ejercicio el fichero se llama ManagerTypesOfBookGenres.tsx y posicionarse en la definición del componente SPfx.

Definición del componente principal del componente SPfx
Sustituir los corchetes por el parámetro any de los parámetros que se introducen en el componente heredado por parte de nuestro componente principal.

Configuración del componente principal para usar la propiedad ‘state’ en el componente SPfx
Para finalizar solo quedaría definir el constructor del componente, para tener definido el state.
```
constructor(props: any) {
  super(props);
  this.state = {};
}
```

Buscar este blog

Briconsejos SharePoint