Tutorial de Angular Dashboard Framework

Angular Dashboard Framework es una librería más que un framework que nos permite hacer fácilmente dashboards personalizados y configurables para nuestras apps o páginas web. Se basa en un grid que creamos definiendo lo que llama una ‘structure’, y varios widgets que inicialmente definiremos en el orden que deseemos, pero que después, el usuario, puede eliminar, insertar otros, reordenar, o, incluso, configurar en base a los parámetros que definamos.

La librería está escrita en Angular.JS, utilizando la librería Sortable para implementar el drag&drop de los widgets y Bootstrap para los estilos, por lo que está bastante estandarizada y podemos modificar el comportamiento a nuestro gusto si no se adapta a lo que necesitamos exactamente.

La configuración definida por el usuario, se guarda mediante la librería ‘Angular Local Storage’ de forma que persiste aún cuando cerramos el navegador. De todas formas, esto sería fácil de cambiar para guardarlo, por ejemplo, en una base de datos si lo deseamos. Otra gran ventaja de esta librería es que, si por alguna razón no logra cargar un widget, mantiene una animación de carga, de forma que es más consecuente.

Dependencias y directiva

En éste manual no voy a hablaros de Angular.JS, daré por hecho que se sabe cómo funciona. Me voy a centrar en la librería de Angular Dashboard Framework. Esta librería está construída con dependencias a otras librerías de Angular.JS, y es necesario que las conozcamos para insertarlas en nuestro html principal o en el inyector de librerías de nuestra app de Angular.JS. Las dependencias son las siguientes:

• angular: 1.2.28
• angular-bootstrap: 0.12.0
• bootstrap: 3.3.4
• Sortable: 1.1.1
• angular-mocks: 1.2.28
• angular-scenario: 1.2.28
• angular-route: 1.2.28
• angular-local-storage: 0.1.5
• es5-shim: ~2.0.8

De forma que en el index.html debemos insertar las siguientes líneas:

<!-- styles -->
<link href="bower_components/bootstrap/dist/css/bootstrap.min.css" rel="stylesheet">
<link href="bower_components/angular-dashboard-framework/dist/angular-dashboard-framework.min.css" rel="stylesheet">

<!-- scripts -->
<script type="text/javascript" src="bower_components/angular/angular.js"></script>
<script type="text/javascript" src="bower_components/Sortable/Sortable.js"></script>
<script type="text/javascript" src="bower_components/angular-bootstrap/ui-bootstrap.js"></script>
<script type="text/javascript" src="bower_components/angular-bootstrap/ui-bootstrap-tpls.js"></script>
<script type="text/javascript" src="bower_components/angular-dashboard-framework/dist/angular-dashboard-framework.js"></script>

También debemos añadir el módulo adf a la lista de módulos requeridos:

angular.module('sample', ['adf']);

Para insertar el dashboard en nuestro html, tan solo tenemos que introducir la siguiente directiva de Angular.JS:

<adf-dashboard name="mydashboard" collapsible="true" structure="6-6" adf-model="model" />

Aunque también tenemos la posibilidad de hacerlo como un atributo:

<div adf-dashboard name="mydashboard" editable="true" collapsible="true" maximizable="true" structure="6-6" adf-model="model" adf-widget-filter="function">
...
</div>

Los diversos atributos son:

• name (string): Nombre del dashboard
• editable (boolean): Si es false, deshabilita el modo de edición del dashboard.
• collapsible (boolean): Si es true hace los widgets del dashboard plegables.
• maximizable (boolean): Si es true añade un botón para abrir los widgets en un panel más grande.
• structure (string): Estructura por defecto del dashboard.
• adfModel (object): Objeto que es el modelo del dashboard.
• adfWidgetFilter (function): función que filtra los widgets que se pueden añadir.

Todos los atributos son opcionales menos el nombre, que es obligatorio.

Estructuras

Una estructura (structure), del dashboard define la forma como los widgets se colocan en el dashboard, mediante la definición de las filas y las columnas, que utilizan los estilos existentes en bootstrap (aunque también le puedes definir tu propio estilo). Puedes definir tus propias estructuras, pero también existen algunas ya definidas en el paquete de estructuras base. Las estructuras definidas en el paquete son: 12/4-4-4; 12/6-6; 12/6-6/12; 3-9 (12/6-6); 4-8; 6-6.

Tras la instalación de este  módulo (podemos utilizar bower), debemos incluirlo tambien en nuestro index.html y en nuestra lista de dependencias del módulo de nuestra app:

<script type="text/javascript" src="bower_components/adf-structures-base/dist/adf-structures-base.min.js"></script>

angular.module('sample', ['adf', 'adf.structures.base']);

Para definir nuestras propias estructuras necesitamos crear un nuevo módulo de Angular.JS con el siguiente contenido:

angular.module('adf.structures.base', ['adf'])
 .config(function(dashboardProvider){
    dashboardProvider
     .structure('4-8', {
       rows: [{
         columns: [{
           styleClass: 'col-md-4'
         },{
           styleClass: 'col-md-8'
         }]
       }]
     });
 });

En la línea 4, tenemos entre comillas el nombre de la estructura. En las líneas 7 y 9, entre comillas está el estilo de bootstrap a aplicar a las columnas. Podemos definir de forma seguida todas las estructuras que queramos poniendo ‘.configure’ en lugar del punto y coma de la línea 12, a continuación del paréntesis que cierra el primer structure, cerrando el punto y coma al final del último structure.

Widgets

Los widgets son las piezas del dashboard que contienen todo lo que se va a ver en el mismo. El contenido de un widget puede ser lo que quieras, no hay límites, tan solo deberíamos tener en cuenta los límites de las columnas que definamos en la estructura del dashboard. Existen bastantes widgets ya definidos que proporcionan listas de enlaces, reloj, el tiempo… Tras la instalación de estos widgets debemos hacer como con las estructuras, introduciendo esta nueva dependencia en el index-html y en la lista de dependencias de la app. Sin embargo, lo más común es que no nos baste y necesitemos más widgets, sobre todo muy personalizados, que no estén definidos en por defecto. Las posibilidades de los widgets no tiene límites, desde una simple imagen o un mensaje estático, o, incluso, podríamos definir un complejo widget con un mapa dinámico que muestre puntos con alguna librería como leaflet, por ejemplo. Ésto es así porque la creación del widget permite cualquier código HTML5 con CSS y Angular.JS.

Para la creacion de un nuevo widget, podemos usar yeoman, tal como explican en el Getting started; pero tambien podemos seguir la siguientes indicaciones, de forma que no nos cree archivos de dependencias o .json que no necesitaremos al estar integrado en otro proyecto mayor.

Es recomendable crear una carpeta para los widgets, para que estén ordenados. a partir de esta carpeta, creamos una por widget que debe tener, por lo menos, los siguientes archivos:

• <nombre-widget>.js

Módulo angular con el config del widget. Su contenido básico es:

'use strict';
angular.module('adf.widget.nombre-widget', ['adf.provider'])
 .config(function(dashboardProvider){
    dashboardProvider
     .widget('nombre-widget', {
         title: 'Título Widget',
         description: 'Descrición Widget',
         templateUrl:'{widgetsPath}/angular-logo/src/view.html',
         edit: {
             templateUrl:'{widgetsPath}/angular-logo/src/edit.html'
         }
     });
 });

Los nombre del módulo (línea 2), y el widget (línea 5), así como el título (línea 6) y la descripción (línea 7), son modificables a gusto del programador. El nombre del módulo es recomendable hacerlo como adf.widget.nombre-widget por claridad y normalización, pero se puede definir como se desee. En el nombre del .widget, podemos definir el que queramos, pero mejor definir uno descriptivo. Los atributos title y description, podemos definirla de forma que describan el widget lo mejor posible. Aunque no son obligatorios, si que es muy recomendable definir un título por lo menos. El templateUrl y edit.templateUrl, sí que son obligatorios, y definen las plantillas html para el widget y la configuración del widget respectivamente.

Aquí podremos introducir el comportamiento de Angular.JS que necesitemos, añadiendo algún controller o lo que necesitemos. Aunque, si lo consideramos mejor o nuestra arquitectura lo requiere, podemos definir otro archivo de Angular.JS a parte para ésta labor.

• edit.html

Formulario de configuración para el widget. Debe contener los campos que se quiera poder cambiar y configurar: título, descripción, horas para los relojes, ubicaciones de mapas, etc. Se utiliza ng-model para bindearlo con el config que estará en el .js o con los controlers.

• view.html

Contenido en html del widget. Podemos introducir css y angular (o javascript). Aquí no hay nada que debamos poner como base, el contenido es 100% libre de ser definido por cada uno.

El artículo Tutorial de Angular Dashboard Framework apareció por primera vez en Instinto Binario.