Guidelines: Graphics es

From Pandora FMS Wiki
Jump to: navigation, search

Contents

1 Introducción al uso de gráficas

Se utilizarán tres librerías de gráficas:

  • Una librería dinámica que utiliza la tecnología Javascript/HTML5 (Flot)
  • Otra estática que simplemente genera una imagen (pChart)
  • La librería gráfica GD

Para ello, existe una abstracción con un único punto de entrada, en el cual se indicarán los datos necesarios para la gráfica.

2 Estructura

Desde fuera de la abstracción solamente será visible el fichero fgraph.php, que actuará como punto de entrada.

Este fichero será el que conozca los ficheros entrada de cada una de las librerías. Estos ficheros son functions_flot.php, functions_pchart.php y functions_gd.php, y cada uno servirán de punto de entrada único a sus respectivas librerías.

Las librerías flot y pchart son librerías contenidas por la abstracción en sus respectivos directorios. En cambio la librería GD se ha de instalar con PHP en el sistema, y la abstracción servirá de punto de entrada pero no contendrá código de la librería.

Algunos tipos de gráficas solo serán compatibles con una librería, y en otros, como por ejemplo las gráficas de sectores o áreas, tendrán su correspondencia en diferentes librerías como pchart y flot, siendo escogida una u otra en función de un valor recibido.

Dentro del paquete, además se encuentra un fichero con funciones útiles, éste es functions_utils.php, y un directorio con imágenes llamado images_graphs.

Graphs abstraction structure.png

3 Dependencias

Esta abstracción está concebida para ser utilizada en aplicaciones tales como Pandora FMS, Integria IMS o Babel Enterprise. Ciertas funciones generales de estas aplicaciones se han utilizado en la abstracción creando dependencias de código, pero evitando así duplicar funciones para facilitar su mantenimiento.

De este modo, la librería incluye en sus ficheros algunos que se presuponen en la aplicación donde van a funcionar, por lo que para usarlas en otro contexto habría que hacer unos ligeros ajustes.

Estas dependencias son functions.php y functions_html.php, y ocurren en el fichero functions_pchart.php donde encontraremos sendas inclusiones:

include_once('../functions.php');
include_once('../functions_html.php');

3.1 Adaptar la librería a otros entornos

Para adaptarlo a otros entornos podemos optar por dos caminos: implementar las dependencias donde se requieren, o hacerlo en otro lugar y cambiar las inclusiones.

Deberemos tener en cuenta varias cosas:

3.1.1 Qué funciones son necesarias

De functions.php se utiliza la función get_parameter junto con todas las que ésta utiliza para evitar sql injections. Y de functions_html.php se utiliza la función html2rgb, utilizada para convertir un color de su formato html (hexadecimal) a RGB.

3.1.2 En qué ruta se buscan

Se presupone que se encuentran en un nivel de directorios por debajo de donde está la librería. Por ejemplo, en Pandora FMS, functions.php está en el directorio include, y los ficheros de la abstracción están en include/graphs. En el caso de cambiar esta ruta de la librería habría que revisar el fichero functions_flot.php, donde en diferentes sitios se hace referencia directa a esta ruta.

4 Incluir la librería

En los ficheros desde los que queramos usar las gráficas deberemos incluir el punto de entrada fgraph.php

5 Funciones

Tenemos a nuestra disposición las siguientes funciones

(*) Ver Formato de los datos para saber como pasar la información en cada caso

5.1 Funciones de pchart y flot

Las siguientes funciones tienen un parámetro especial llamado flash_chart. Dicho parámetro será un booleano e indicará que se utilice la librería de gráficas javascript (flot) si es TRUE y la de imágenes estáticas (pChart) en caso de ser FALSE.

5.1.1 area_graph

Gráfica de área que admite gráficas combinadas y personalización de colores

5.1.1.1 Parámetros

Obligatorios:

  • flash_chart: Valor booleano que indica si las gráfica usará flot (true) o pchart (false)
  • chart_data: Datos de la gráfica o gráficas
  • width: Ancho de la gráfica
  • height: Alto de la gráfica
  • color: Color/colores de la gráfica/gráficas
  • legend: Leyenda de la tabla
  • long_index: Índice largo para la información detallada de las gráficas flash
  • no_data_image: Ruta de una imagen para mostrar cuando la gráfica no tiene datos en caso de que no se quiera mostrar la imagen por defecto

Optativos:

  • xaxisname: Nombre del eje x, saldrá bajo la gráfica (por defecto cadena vacía)
  • yaxisname: Nombre del eje y, saldrá a la izquierda de la gráfica en orientación vertical (por defecto cadena vacía)
  • homeurl: URL de la instalación de la aplicación, por ejemplo: http://www.myinstalation.com/pandora. Si no se le pasa las llamadas internas de tipo URL se harán de forma relativa, por lo que se aconseja pasar este parámetro para evitar problemas. (por defecto cadena vacía).
  • water_mark: Ruta de la imagen que se pondrá como marca de agua (por defecto cadena vacía)
  • font: Fuente utilizada (por defecto '../fonts/unicode.ttf')
  • font_size: Tamaño de la fuente (por defecto 8)

5.1.2 line_graph

Gráfica de línea que admite gráficas combinadas y personalización de colores

5.1.2.1 Parámetros

Esta gráfica admite los mismos parámetros que la de área.

5.1.3 stacked_area_graph

Gráfica de área pero con los valores sobrepuestos. Esto es, a cada gráfica le suma los valores de la anterior.

5.1.3.1 Parámetros

Esta gráfica admite los mismos parámetros que la de área.

5.1.4 stacked_line_graph

Gráfica de líne pero con los valores sobrepuestos al igual que en las stacked_area_graph

5.1.4.1 Parámetros

Esta gráfica admite los mismos parámetros que la de área.

5.1.5 vbar_graph

Gráfica de barras verticales que admite personalización de colores finos (un color por barra)

5.1.5.1 Parámetros

Obligatorios:

  • flash_chart: Valor booleano que indica si las gráfica usará flot (true) o pchart (false)
  • chart_data: Datos de la gráfica o gráficas
  • width: Ancho de la gráfica
  • height: Alto de la gráfica

Optativos:

  • color: Color/colores de la gráfica/gráficas (por defecto array vacío)
  • legend: Leyenda de la tabla (por defecto array vacío)
  • xaxisname: Nombre del eje x, saldrá bajo la gráfica (por defecto cadena vacía)
  • yaxisname: Nombre del eje y, saldrá a la izquierda de la gráfica en orientación vertical (por defecto cadena vacía)
  • force_height: Valor booleano que fuerza la altura de una gráfica a la que le es pasada se vea como se vea. Si esta valor es falso, se realiza un chequeo por el que si hace falta ampliar la altura para la correcta visualización de la gráfica se hará automáticamente. (por defecto true)
  • homeurl: URL de la instalación de la aplicación, por ejemplo: http://www.myinstalation.com/pandora. Si no se le pasa las llamadas internas de tipo URL se harán de forma relativa, por lo que se aconseja pasar este parámetro para evitar problemas. (por defecto cadena vacía).
  • water_mark: Ruta de la imagen que se pondrá como marca de agua (por defecto cadena vacía)
  • font: Fuente utilizada (por defecto '../fonts/unicode.ttf')
  • font_size: Tamaño de la fuente (por defecto 8)
  • force_steps: Valor booleano que fuerza separar los datos del eje un mínimo de 40 píxeles, si se envía false se mostrarán todos con riesgo de que queden amontonados (por defecto a true)

5.1.6 hbar_graph

Gráfica de barras horizontales que admite personalización de colores finos (un color por barra)

5.1.6.1 Parámetros

Esta gráfica admite los mismos parámetros que la de barras verticales.

5.1.7 pie2d_graph

Gráfica de sectores en dos dimensiones

5.1.7.1 Parámetros

Obligatorios:

  • flash_chart: Valor booleano que indica si las gráfica usará flot (true) o pchart (false)
  • chart_data: Datos de la gráfica o gráficas
  • width: Ancho de la gráfica
  • height: Alto de la gráfica

Optativos:

  • others_str: Cadena personalizada para calificar a la agrupación de valores más pequeños cuando se pasan muchos. (por defecto 'others')
  • homeurl: URL de la instalación de la aplicación, por ejemplo: http://www.myinstalation.com/pandora. Si no se le pasa las llamadas internas de tipo URL se harán de forma relativa, por lo que se aconseja pasar este parámetro para evitar problemas. (por defecto cadena vacía).
  • water_mark: Ruta de la imagen que se pondrá como marca de agua (por defecto cadena vacía)
  • font: Fuente utilizada (por defecto '../fonts/unicode.ttf')
  • font_size: Tamaño de la fuente (por defecto 8)

5.1.8 pie3d_graph

Gráfica de sectores en dos dimensiones

5.1.8.1 Parámetros

Esta gráfica admite los mismos parámetros que las gráficas de sectores de 2 dimensiones.

5.2 Funciones sólo de pchart

5.2.1 threshold_graph

Gráfica de línea especial con interpolación. Todavía no se ha usado pero con unas pequeñas modificaciones se podrá adaptar a las necesidades.

Obligatorios:

  • flash_chart: Valor booleano que indica si las gráfica usará flot (true) o pchart (false)
  • chart_data: Datos de la gráfica
  • width: Ancho de la gráfica
  • height: Alto de la gráfica

5.2.2 radar_graph

Gráfica de kiviat con forma de diamante.

5.2.2.1 Parámetros

Obligatorios:

  • flash_chart: Valor booleano que indica si las gráfica usará flot (true) o pchart (false)
  • chart_data: Datos de la gráfica o gráficas
  • width: Ancho de la gráfica
  • height: Alto de la gráfica
  • no_data_image: La ruta de una imagen para mostrarla cuando el diagrama no recibe datos

5.2.3 polar_graph

Gráfica de kiviat redonda.

5.2.3.1 Parámetros

Esta gráfica admite los mismos parámetros que la gráfica de radar.

5.2.4 slicesbar_graph

Gráfica de segmentos horizontal.

5.2.4.1 Parámetros

Obligatorios:

  • graph_data: datos de la gráfica.
  • period: Rango de tiempo de la gráfica (en segundos).
  • width: Ancho de la gráfica.
  • height: Alto de la gráfica.
  • colors: Array con los colores que se asociarán a los datos de la gráfica. Por ejemplo:
$colors = 	array(1 => '#38B800', 2 => '#FFFF00', 3 => '#FF0000', 4 => '#C3C3C3');

5.3 Funciones solo de GD

Estas funciones tienen dos modos de uso:

  1. Mediante la llamada a la función
  2. Mediante la llamada mediante URL a fgraph.php

5.3.1 progressbar

Barra de progreso.

5.3.1.1 Parámetros

Obligatorios:

  • progress: Valor numérico del progreso. Cuando sea menor de 0 o mayor de 100 se mostrará como fuera de límite
  • width: Anchura de la barra
  • height: Altura de la barra
  • title: Título de la barra
  • font: Fuente utilizada en la barra

Optativos:

  • mode: Valor numérico para establecer el tipo de barra (por defecto 1):
    • 0: Se muestra sin texto y va cambiando de color según se llena empezando por rojo y acabando en verde en el 100%
    • 1: Se muestra siempre en azul y con un texto con el porcentaje de progreso
    • 2: Se muestra sin texto y va cambiando de color según se llena empezando por verde y acabando en rojo en el 100%
  • out_of_lim_str: Cadena personalizada para mostrar cuando se sale de los límites (por defecto 'Out of limits')
  • out_of_lim_image: Ruta de la imagen que se mostrará cuando se sale de los límites (por defecto usa la imagen de la abstracción 'images_graphs/outlimits.png')

5.3.2 histogram

Grafica simple de histograma (barras horizontales)

5.3.2.1 Parámetros
  • width: Anchura del gráfico
  • height: Altura del gráfico
  • mode: Valor numérico para establecer el tipo de gráfica:
    • 0:
    • 1:
    • 2:
  • data: Datos de una o varias barras
  • max_value: Valor máximo de referencia para las barras
  • font: Fuente utilizada en la barra
  • title: Título de la gráfica

5.4 Funciones especiales

5.4.1 include_flash_chart_script

Inclusión de la librería javascript necesaria para las gráficas flash

5.4.1.1 Parámetros

Obligatorios:

No

Optativos:

  • homeurl: URL de la instalación de la aplicación, por ejemplo: http://www.myinstalation.com/pandora. Si no se le pasa las llamadas internas de tipo URL se harán de forma relativa, por lo que se aconseja pasar este parámetro para evitar problemas. (por defecto cadena vacía).

6 Formato de los datos

Según la naturaleza de la gráfica deseada los datos se envían en distinto formato. No es lo mismo una gráfica de sectores en la que simplemente se mandan unos valores asociados a unos nombres y se calculan los porcentajes de cada uno, que una gráfica de área combinada, para la cual se pueden mandar una serie de datos tales como leyendas, los datos del eje de abscisas, el color de cada gráfica, su nivel alpha, etc.

Por ello vamos a clasificar las gráficas según su naturaleza para explicar con ejemplos el formato de los datos y aprender así a utilizarlas.

6.1 Gráficas de sectores, radar y polar

Este tipo de gráficas es la más simple en cuanto a la estructura de datos que recibirán.

6.1.1 Datos enviados

  • Lista de valores
  • Lista de cadenas

6.1.2 Formato

Un array con las cadenas como claves y los valores como los valores asociados a cada clave.

6.1.3 Ejemplo

Queremos construir una gráfica de sector con las horas empleadas por cada empleado en un proyecto determinado.

Tenemos los datos de 4 empleados con un número de horas asociado a cada uno en ese proyecto:

  • employee_a - 8 horas
  • employee_b - 16 horas
  • employee_c - 21 horas
  • employee_d - 10 horas

El array que debemos pasarle a la función para que se representen estos datos será:

array('employee_a' => 8, 'employee_b' => 16, 'employee_c' => 21, 'employee_d' => 10)

6.1.4 Resultado estático

Static pie.png

6.1.5 Resultado flot

Flot pie.png

6.2 Gráficas de barras

Se le envía una lista de valores y la lista de cadenas a las que irán asociados dichos valores. Estas gráficas no soportan gráficas combinadas, pero por compatibilidad, los datos se envían en un array cuyo índice es un identificador de la gráfica.

6.2.1 Datos enviados

  • Identificador de gráfica
  • Lista de valores
  • Lista de cadenas

6.2.2 Formato

Un array con las cadenas como claves y en cada valor un array cuyo índice es el identificador de la gráfica y el valor su valor asociado a la cadena.

6.2.3 Ejemplo

array (
   'Mar 08 00:00' => array('graph' => 0),
   'Mar 11 03:39' => array('graph' => 0),
   'Mar 14 07:19' => array('graph' => 10),
   'Mar 17 10:58' => array('graph' => 16),
   'Mar 20 14:38' => array('graph' => 68),
   'Mar 23 18:18' => array('graph' => 12),
   'Mar 26 21:57' => array('graph' => 0),
   'Mar 30 02:37' => array('graph' => 0),
   'Apr 02 06:17' => array('graph' => 0),
   'Apr 05 09:56' => array('graph' => 0)
)

6.2.4 Resultado estático

Static bar.png

6.2.5 Resultado flot

Próximamente

6.3 Gráficas de áreas y líneas

Este tipo de gráficas aceptan gráficas combinadas. Se le envía por cada gráfica un identificador, una lista de valores y la lista de cadenas a las que irán asociados dichos valores.

6.3.1 Datos enviados

  • Identificador de gráfica
  • Lista de valores
  • Lista de cadenas

6.3.2 Formato

Un array con las cadenas como claves y en cada valor un array con los datos asociados a esa cadena para cada una de las gráficas, siendo los índices de esos arrays el identificador de la gráfica y el valor, su valor asociado.

6.3.3 Ejemplo

array (
  'monday' => array('graph1' => 12, 'graph2' => 30),
  'tuesday' => array('graph1' => 5, 'graph2' => 23),
  'wednesday' => array('graph1' => 10, 'graph2' => 13),
  'thursday' => array('graph1' => 16, 'graph2' => 45),
  'friday' => array('graph1' => 68, 'graph2' => 0),
  'saturday' => array('graph1' => 12, 'graph2' => 5),
  'sunday' => array('graph1' => 0, 'graph2' => 23)
)

6.3.4 Resultado estático

6.3.4.1 Area

Static area.png

6.3.4.2 Línea

Static line.png

6.3.5 Resultado flot

6.3.5.1 Area

Flot area.png

6.3.5.1.1 Area Zoom

Flot area zoom.png

6.3.5.2 Línea

Flot line.png

6.3.5.2.1 Línea Zoom

Flot line zoom.png

6.4 Gráficas de histograma

Estas gráficas son de las más simples. Es un histograma muy básico.

6.4.1 Datos enviados

  • Lista de valores
  • Lista de cadenas

6.4.2 Formato

Un array con las cadenas como claves y en cada valor un número correspondiente a esa clave.

6.4.3 Ejemplo

array (
  'bar_a' => 34,
  'bar_b' => 22,
  'bar_c' => 0,
  'bar_d' => 10
)

6.4.4 Resultado

Gd histogram.png

7 Datos opcionales

Existen una lista de opciones que se pueden pasar a la creación de una gráfica para enrriquecer su aspecto aunque no son obligatorias.

7.1 Colores y transparencia

Si no se pasa ningún color ni valor de transparencia (alpha), se tomarán unos colores y transparencias por defecto según el tipo de gráfica. En cambio se puede personalizar de una forma sencilla enviando los valores deseados asociados al identificador de cada gráfica.

Los colores se pasarán en formato hexadecimal compatible con HTML, es decir #000000 para el color negro y #FFFFFF para el blanco. También acepta los formatos #000, 000000 y 000.

La transparencia (valor alpha) será un valor numérico del 0 al 100, siendo 0 invisible y 100 totalmente opaco.

7.1.1 Datos enviados
  • Identificador de gráfica
  • Color para cada gráfica
  • Color del borde para cada gráfica
  • Transparencia para cada gráfica
7.1.2 Formato
array (
  'graph1' => array('color' => '#FF0043', 'border' => '#000000', 'alpha' => 50),
  'graph2' => array('color' => '#34FF00', 'border' => '#000000', 'alpha' => 100),
  'graph3' => array('color' => '#00DD0F', 'border' => '#000000', 'alpha' => 100)
)

7.2 Colores finos

En las gráficas de barras surge la necesidad de poder dar un color a cada barra dentro de la misma gráfica. Con el formato estándar de colores asignábamos un color a cada gráfica, por lo que se ha creado otro sistema para estos casos: los colores finos.

Si activar los colores finos para que se coloreen las barras con una serie de colores por defecto o bien pasarle nuestros propios colores.

Tanto los colores por defecto como los que le podamos pasar serán unos colores cíclicos, es decir, si se dibujan 10 barras pero solo han sudo pasado 8 colores, una vez dibujadas las 8 primeras barras se volverá a empezar por el primer color con las siguientes.

Tanto si activamos los colores finos como si le enviamos colores finos personalizados, los colores generales (un color para cada gráfica) serán ignorados.

7.2.1 Datos enviados
  • Identificador de gráfica
  • true (si queremos activarlas solamente) ó una lista de cadenas con los colores personalizados
7.2.2 Formato para activarlos
array (
  'graph1' => array('fine' => true)
)
7.2.3 Formato para personalizarlos
array (
  'graph1' => array('fine' => array('#FF0043', '23DD00', '#FFFF02', '#04FA1A', '#00D000', '#2000FF'))
)

7.3 Leyenda

A una gráfica se le puede pasar una leyenda para mejorar su entendimiento. Simplemente se le enviará una cadena por cada gráfica.

7.3.1 Datos enviados
  • Identificador de gráfica
  • Una cadena asociada a cada gráfica
7.3.2 Formato
array ('graph1' => 'Graph 1', 'graph2' => 'Graph 2');

7.4 Nombre de los ejes

Se puede personalizar el nombre de los ejes para que aparezca junto al eje.

7.4.1 Datos enviados
  • Identificador de gráfica
  • Nombre del eje x
  • Nombre del eje y
7.4.2 Formato

Una cadena con el nombre del eje deseado.

Ejemplo:

'Week days'

7.5 Gráfica sin datos

Si no se envían datos a una gráfica se mostrará una imágen genérica avisándolo.

Esta imagen se puede personalizar enviando la ruta de la imagen que queramos que se muestre en ese caso.

7.5.1 Datos enviados
  • Ruta de la imagen
7.5.2 Formato

Una cadena con la ruta de la imagen

Ejemplo:

'images/no_data.png'