Guidelines:Graphics_es

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.

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.

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:

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.

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.

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

Tenemos a nuestra disposición las siguientes funciones

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.

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

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)

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

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

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

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

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

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

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

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)

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

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

Gráfica de sectores en dos dimensiones

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)

Gráfica de sectores en dos dimensiones

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

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

Gráfica de kiviat con forma de diamante.

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

Gráfica de kiviat redonda.

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

Gráfica de segmentos horizontal.

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');

Estas funciones tienen dos modos de uso:

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

Barra de progreso.

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')

Grafica simple de histograma (barras horizontales)

• 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

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

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).

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.

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

• Lista de valores
• Lista de cadenas

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

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)

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.

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

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.

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)
)

Próximamente

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.

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

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.

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)
)

Area Zoom

Línea Zoom

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

• Lista de valores
• Lista de cadenas

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

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

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.

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.

• Identificador de gráfica
• Color para cada gráfica
• Color del borde para cada gráfica
• Transparencia para cada gráfica

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)
)

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.

• Identificador de gráfica
• true (si queremos activarlas solamente) ó una lista de cadenas con los colores personalizados

array (
  'graph1' => array('fine' => true)
)

array (
  'graph1' => array('fine' => array('#FF0043', '23DD00', '#FFFF02', '#04FA1A', '#00D000', '#2000FF'))
)

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

• Identificador de gráfica
• Una cadena asociada a cada gráfica

array ('graph1' => 'Graph 1', 'graph2' => 'Graph 2');

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

• Identificador de gráfica
• Nombre del eje x
• Nombre del eje y

Una cadena con el nombre del eje deseado.

Ejemplo:

'Week days'

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.

• Ruta de la imagen

Una cadena con la ruta de la imagen

Ejemplo:

'images/no_data.png'