¿Cómo usar el Template Web para WebProjects (Onesait Platform Web Template) ?

Introducción

El Template Web es una plantilla base que permite crear de forma sencilla aplicaciones web desplegables como proyectos Web en plataforma simplemente configurando un conjunto de endpoints en los ficheros JS de configuración.

Para empezar debéis descargar el repositorio de https://github.com/onesaitplatform/onesaitplatform-webproject-template 

Una vez descargado os encontraréis  una estructura como esta:

Dentro del repositorio podemos distinguir 2 partes:

• Plantillas HTML

• Librerías Javascript y CSS de la aplicación (assets). 

Plantillas HTML

Al clonar el proyecto veremos 2 plantillas: index y login, ambas plantillas configurables para que se ajusten a las necesidades del proyecto.

La plantilla login (login.html) se usa para hacer el login de usuarios contra la aplicación realizando un proceso de autenticación para el acceso a la plantilla Index.

La plantilla Index (index.html), es el Home web del proyecto. Desde allí, con una visualización y un sistema de menús configurable (que veremos luego más detalladamente en la sección de librerías de frontend de la aplicación) se puede acceder a todos los elementos de gestión del frontend.

Cada una de estas pantallas o visualizaciones están encapsuladas en dashboards (explicados en el punto 1.6). Estos dashboards son elementos de visualización dinámicos compuestos de gadgets/widgets que interactúan entre sí y cargan datos de forma óptima.

Librerías JavaScript y de estilo CSS

En el proyecto además de las librerías de estilos básicas y de las librerías de JavaScript básicas que se usan en los dashboards para sus gadgets genéricos, es necesario para algunas de las funcionalidades desarrolladas una serie de librerías open-source adicionales, a continuación, se describen todas ellas.
Las vamos a dividir en archivos de aplicación "app" y archivos de terceros, "vendors" que son plugins o librerías open-source que se utilizan para generar gadgets livehtml o funcionalidades específicas en algunos de ellos.
Vemos a continuación la estructura y contenido de las carpetas.

1º Nivel	2º Nivel	Descripción de la carpeta
Contiene los archivos básicos para la parte de frontend y su configuración.		En la carpeta css están los archivos de estilo. En la carpeta js están los archivos básicos JavaScript para el frontend, que inicializa funcionalidades básicas y de boostrap y de configuración y funcionamiento de las plantillas index y login. En la carpeta media tenemos imágenes, logotipos y fondos de la aplicación frontend.
Contiene los archivos de librerías y plugins de terceros que se usan para la parte de frontend y la configuración de dashboards		En la carpeta base están los archivos de fuentes de iconos usados, además de unos archivos agrupados de varios estilos y varios plugins JavaScript que se usan para campos tipo date, datepicker, datetimepickers, select2, boostrap-select, input mask, jquery-validation, range, sliders, colorpickers, etc. datatables es la carpeta que contiene estilos y JavaScript usados por las tablas de datos usadas en varios dashboards. x-editable contiene un plugin open source para la edición en línea de datos.

Sistema de configuración

El sistema de configuración de templates tiene 2 objetivos principales: el primero, configurar el acceso y el menú de navegación de la aplicación frontend, y el segundo, configurar el aspecto visual de la plantilla index y login.
Toda la información que necesita el frontend para auto-configurarse se almacena en el archivo application-config.js que está en /assets/app/js y es controlado para la configuración de menú por menu.js y para el control del aspecto por frontend.js, ambos también en la misma ubicación.
Dentro del application-config.js se declaran dos objetos de configuración JSON, uno para el menú y otro para la configuración de acceso y aspecto del frontend, a continuación, vamos a ver el formato y uso del objeto que describe los menús del sistema de navegación del frontend:

Configuración del objeto menú menuJson en application-config.js
El Objeto menuJson configura los menús de 1º y 2º nivel (submenús) de la aplicación y se compone de las siguientes propiedades:

• Menú: nombre del menú o plataforma (informativo)

• Rol: rol del usuario que carga el menú, para carga de diferentes menús según rol (no disponible está funcionalidad, prevista para siguiente versión 1.2)

• Home: (booleano) indica si queremos o no tener un menú Home por defecto en el menú que irá a index.html por defecto.

• noSession: en caso de perder la sesión, a que plantilla al mismo nivel de index se quiere redirigir la navegación.

• Navigation: Array de objetos de navegación, es decir, los menús y submenús en sí.

Dentro del array de navegación (navigation) se pueden cargar dos tipos de elementos, menús sencillos y menús con submenús, en ambos casos, estos ítems pueden cargar tanto páginas HTML (a las cuales será redirigida la navegación) como dashboards de la aplicación, que se cargarán vía iframe en la index. Veamos las propiedades de cada uno:
Menú sencillo (sin submenús):

La condición principal para hacer un menú sencillo es colocar la propiedad submenú a un array vacío, los siguientes campos permiten:

• title, indica el titulo o label que se mostrará se pueden indicar en varios idiomas EN,ES,…

• icon: indica el icono que se usará para este menú, se pueden usar cualquier icono de los disponibles en las siguientes librerías y con este formato:

  • fontAwesome, con formato "fa fa-ICONO" (e.j "fa fa-calendar", para calendario)

  • lineAwesome, con formato "la la-ICONO"

  • flaticon con formato "flaticon-ICONO"

  • https://fontawesome.com/icons?d=gallery&m=free, https://icons8.com/line-awesome

• url: se usa si queremos cargar una página, si queremos cargar un dashboard, debe dejarse vacía.

• submenu: contendrá los submenús en caso de ser un menú con submenús, en el caso de menú sencillo se deja simplemente vacía para indicar eso.

• Dashboard: indica que el menú cargará un dashboard, si queremos cargar una página, dejaremos este objeto vacío, en caso contrario, configuraremos los siguientes campos:

  • Src: la url completa con https del dashboard a cargar, el link de dashboard que da la consola

  • Title: el título del dashboard

  • Background: si queremos cargar un color de fondo en el iframe contendor del dashboard

  • Height: la altura en pixels del dashboard si no se aplica, se carga por defecto en 650px.

  • Mode: INSERT, indica el modo del dashboard, es una funcionalidad futura, que ahora no aplica en esta versión.

Veamos a continuación dos ejemplos uno para página y otro para dashboard:

Menú Sencillo a página:

Menú sencillo a Dashboard:

La otra opción que permite un menú sencillo es un elemento de separación, que sólo hace de separador entre grupos de menús, para crear un separador se agrega un menú sencillo sin url y sin dashboard:
Menú sencillo separador:

La otra opción del Sistema de navegación son los menús complejos o menús con submenús, funcionan exactamente igual que los sencillos, solo que se ubican dentro del campo submenu[ ] del menú principal, veamos a continuación un ejemplo:

Con todas estas opciones se construye la navegación de la aplicación como podemos ver a continuación:

En esta imagen podemos ver todos los tipos de elementos que podemos construir en la navegación de la aplicación: El menú home, por defecto no mostrado, varios menús con submenús, el de Complaints con dos submenús: Dashboard y Report, y otro menú con submenús que se llama Objectives.

El siguiente objeto de configuración es mainJson. Este objeto JSON configura el comportamiento y el estilo visual de las plantillas login e index. Para ello dentro se divide la configuración en bloques que describen cada una de zona de las páginas o elementos generales de las mismas.
Vamos a ver estos bloques o secciones de configuración y su cometido:

• Parámetros generales (título, descripción).

• Acceso: url base y url API para conectar el frontend con la plataforma Onesait. Se indica también el path a las imágenes usadas en las páginas de frontend y el tipo de acceso a la index (PUBLIC,PRIVATE), que son los dos modos de acceso:

  • PUBLIC: cuando se accede a la index, no se pide login ni hay proceso de logado.

  • PRIVATE: cuando se accede a la index, si no se está logado previamente (login), la aplicación nos redirige a la pantalla de login donde podemos logarnos contra la plataforma onesait, usando las urlbase y api antes configuradas para los procesos de oAuth y logado.

• App (aplicación): logo y configuración de la index. Se indica si queremos tener visible el footer, o un mensaje emergente de bienvenida, …

• Login: configuración del login, del logo, fondo etc., y además si queremos agregar los servicios de signUp (agregando la programación), forgotpassword y el de rememberMe.

• User: elementos y menú del usuario, en el header si está visible la información de usuario. Posee un menú desplegable con una serie de ítems y enlaces que se puede crear y customizar. Para ello el administrador elije los que quiere ver y los configura.

• Header: configuración de elementos visibles dentro del header de la index. Desde aquí podemos configurar fácilmente si queremos algunos elementos (estáticos y otros dinámicos) estén visibles/ocultos en el header (cabecera) de la aplicación:

  • Dashboards (menú estático configurable).

  • Reports (menú estático configurable).

  • Search (buscador configurable).

  • Notifications (desplegable de notificaciones configurable).

  • Quick actions (acciones rápidas configurables).

  • User Profile (desplegable con las opciones de profile de usuario).

  • Sidebar menú (menú de configuración adicional configurable).

  • Template configuration (menú de configuración que permite todas estas configuraciones).

• Content: configuración del primer dashboard a cargar en la index tras cargar.

  • Permite indicar como hacemos en menú, la información de un dashboard para que sea cargado inicialmente en la index tras cargar.

• Footer: configuración de elementos en el footer de la index. Permite configurar los elementos visibles en el footer y sus enlaces a páginas (que deben crearse y agregarse al proyecto web). Se pueden agregar las siguientes páginas: About, Privacy, Terms, Company y support

• Themes: selección de color de menú y tema visual (en desarrollo)

A continuación, vemos un ejemplo de este objeto de configuración del template:

Despliegue

Una vez he configurado mi template puedo abrir desde mi equipo el fichero login.html y comprobar que todo funciona. 

Para desplegarlo como proyecto web en plataforma simplemente empaquetaré como un ZIP el proyecto

y lo desplegaré en una instancia de plataforma siguiendo los pasos descritos en esta guía: (WebApps Manager) (ES) Cómo publicar tu web a través de la Plataforma.