Usando HighCharts en WP-Admin

() translation by (you can also view the original English article)

Los gráficos son una excelente manera de presentar datos. Hacen que los datos sean más digeribles al hacerlos visualmente atractivos. En WordPress, no existe un método integrado para obtener publicaciones y datos de páginas en forma gráfica.

Aunque, hay ciertos complementos disponibles que integran Google Analytics con WordPress, pero son exagerados si deseas obtener solo una parte de esos datos.

Además, nada debe impedirte aprender nuevas técnicas y sumergirte directamente en el tema, es la mejor manera de aprender.

Lo que vamos a hacer

Este tutorial está dirigido a los nuevos desarrolladores de WordPress que desean obtener información sobre algunas técnicas útiles que podemos utilizar en nuestro proceso de desarrollo. En este tutorial, crearemos nuestro propio complemento simple que nos presentará los datos gráficamente dentro del administrador de WordPress. Utilizaremos las clases y funciones estándar de WordPress para obtener datos y luego mostrarlos gráficamente en el administrador de WordPress con la ayuda de un complemento jQuery llamado HighCharts.

Prepararemos nuestro complemento básico, agregaremos una página en el wp-admin y luego colocaremos el JavaScript de nuestro complemento solo en esa página. Luego pasaremos los datos que obtuvimos a un script externo mediante el uso de wp_localize_script. A su vez, el script mostrará nuestros datos gráficamente.

Las estadísticas que planeamos mostrar son:

Publicaciones más populares
Las cinco categorías principales por número de publicaciones
Desglose de categorías por publicaciones

HighCharts

Según su sitio:

Highcharts es una biblioteca de gráficos escrita en HTML5/JavaScript puro, que ofrece gráficos interactivos e intuitivos para tu sitio web o aplicación web. Highcharts actualmente admite líneas, splines, áreas, splines de áreas, columnas, barras, sectores, dispersiones, medidores angulares, rango de áreas, rango de líneas de áreas, rangos de columnas, burbujas, gráficos de cuadros, barras de error, embudo, cascada y tipos de gráficos polares.

Puedes obtener una copia desde su sitio web.

Dicho esto, comencemos a trabajar en nuestro complemento.

Comenzando con nuestro complemento

Configuración inicial

Primero crearemos un directorio dentro de nuestra carpeta wp-content/plugins llamado "admin-charts". Dentro de eso, hagamos la estructura de directorio inicial para nuestro complemento.

Copia el archivo highcharts.js del directorio en el archivo ZIP que descargaste del sitio web oficial, a una carpeta js:

En el directorio raíz, crearemos un archivo index.php y dentro de eso agregaremos la declaración inicial para nuestro complemento:


<?php
/*
Plugin Name: Admin Charts
Plugin URI: http://dev.imbilal.com/wpadmincharts
Description: JavaScript charts for WordPress admin. These charts show different statistics in the WordPress admin.
Version: 1.0
Author: Bilal Shahid
Author URI: http://www.imbilal.com
License: GPLv2 or later
*/
?>

Ahora, si vas a WP-Admin > Plugins, notarás que el complemento se muestra allí, pero aún no funciona.

También agregaremos algunos estilos dentro de nuestro admin_charts.css:


#admin_chart_form {
	margin: 30px 0;
}

#admin_chart_form label {
	display: inline-block;
	width: 250px;
}

Agregar una página del complemento

Nuestro siguiente paso sería agregar una página para el complemento dentro del administrador donde realizaríamos todas las operaciones. Para eso, utilizaremos la acción admin_menu de WordPress. Esta acción se activa después de que la estructura básica del menú del panel de administración está en su lugar y, por lo tanto, se puede usar para agregar más menús o submenús en el administrador. El uso básico es el siguiente:

1
2	<?php add_action( 'admin_menu', 'function_name' ); ?>

Agregaríamos una función chart_add_admin_page dentro de nuestro index.php y luego la engancharemos a esta acción:

1
2	add_action( 'admin_menu', 'chart_add_admin_page' );

Dentro de nuestra función chart_add_admin_page llamaremos a la función nativa de WordPress add_plugins_page:


function chart_add_admin_page() {
	add_plugins_page(
		'Charts For Wordpress',
		'Admin Charts',
		'administrator',
		'admin-charts',
		'render_admin_charts_page'
	);
}

El primer argumento es el título de la página que se mostrará en las etiquetas <title></title> de la página. El segundo argumento es el título del menú. Los argumentos tercero y cuarto son la capacidad del usuario y el slug único para referirse a este menú. El último argumento es el nombre de la función de devolución de llamada que se utilizará para representar el contenido de esta página.

Ahora, si activas el complemento y pasas el mouse sobre el menú "Complementos", notarás que hemos agregado con éxito un menú para nuestro complemento:

Representación del contenido de la página del complemento

En esta etapa, hemos agregado con éxito una página vacía para nuestro complemento. Es hora de hacerlo funcional generando contenido.

En nuestra llamada anterior a add_plugins_page nos hemos referido a una función de devolución de llamada render_admin_charts_page. Esta es la función que hemos planeado para generar todo el contenido que queremos tener en nuestra página. Entonces, escribamos la función.

Debajo de la función chart_add_admin_page, agrega el siguiente código:


function render_admin_charts_page() {
	?>
	<div class="wrap">
		<h2>Admin Charts</h2>
		<form action="#" method="post" name="admin_chart_form" id="admin_chart_form">
			<p>
				<label for="chart_data_type">What type of data do you want to show?</label>
				<select name="chart_data_type" id="chart_data_type">
					<option value="chart_most_popular">Most Popular Post</option>
				</select>
			</p>
			<input type="submit" class="button-primary" value="Display Data" id="show_chart" name="show_chart" />
		</form>
		<div id="chart-stats" class="chart-container" style="width:900px; height:500px;"></div>
	</div>
	<?php
}
?>

Solo estamos agregando HTML simple aquí. Hemos agregado un encabezado y un formulario dentro de la clase CSS "wrap" nativa de WordPress.

Dentro del formulario, hemos agregado un cuadro de selección que actualmente solo tiene una opción para mostrar las publicaciones más populares por conteo de comentarios. Debajo del formulario, hemos agregado un contenedor div para nuestros gráficos.

Nuestra página ahora está tomando forma:

Consejo: Siempre debes intentar integrar la interfaz de usuario nativa de WordPress. Tenemos una gran serie de Stephen Harris que cubre el tema.

Es hora de registrar los scripts y estilos necesarios para que podamos ponerlos en cola más adelante. Para eso, utilizaremos las funciones wp_register_script y wp_register_style que funcionan en colaboración con el hook de acción admin_enqueue_scripts si queremos ponerlas en cola en el lado de administración.

Pero antes de eso, agreguemos una constante para nuestro directorio raíz del complemento para que podamos consultarlo más adelante cuando definamos rutas para nuestros scripts y estilos. Entonces, en la parte superior de la página debajo de la declaración del complemento, agrega este bit de código:

1
2	define( 'ROOT', plugin_dir_url( __FILE__ ) );

Ahora podemos definir nuestra función para registrar nuestros scripts y estilos:


add_action( 'admin_enqueue_scripts', 'chart_register_scripts' );
function chart_register_scripts() {
	wp_register_script(
		'highCharts',
		ROOT . 'js/highcharts.js',
		array( 'jquery' ),
		'3.0',
		true
	);
	wp_register_script(
		'adminCharts',
		ROOT . 'js/admin_charts.js',
		array( 'highCharts' ),
		'1.0',
		true
	);
	wp_register_style(
		'adminChartsStyles',
		ROOT . 'css/admin_chart.css'
	);
}

Primero, hemos registrado el script HighCharts que habíamos descargado anteriormente. Le hemos dado un identificador "highCharts". Para el siguiente argumento, hemos definido la ruta donde existe.

A continuación, hemos pasado una serie de scripts de los que depende nuestro script, en este caso es jQuery ya que estaríamos manipulando el DOM a través de jQuery. De esta manera, no tendremos que preocuparnos por poner en cola jQuery, se pondrá en cola automáticamente cada vez que agreguemos a la cola el script highCharts.

Para el tercer argumento, hemos definido un número de versión y para el último argumento, le hemos dicho al wp_register_script que ponga en cola el script en el pie de página de la página después del contenido principal. De la misma manera, hemos registrado nuestro segundo script donde estaríamos agregando todo nuestro código JavaScript necesario.

Ahora podemos poner en cola nuestros scripts y estilos en nuestra página de complementos, pero no queremos que se pongan en cola en cada página del administrador donde no sean necesarios.

Por esa razón, verificaremos una condición antes de poner en cola nuestros scripts:


add_action( 'admin_enqueue_scripts', 'chart_add_scripts' );
function chart_add_scripts( $hook ) {

	if ( 'plugins_page_admin-charts' == $hook ) {

		wp_enqueue_style( 'adminChartsStyles' );
		wp_enqueue_script( 'adminCharts' );

	}
}

La función que enlazamos con admin_enqueue_scripts en realidad recibe un parámetro para la página de administración en la que estamos actualmente. En nuestro caso, es "plugins_page_admin-charts". Siempre puedes verificar este parámetro haciéndole 'echo' en tu proceso de desarrollo.

Ahora que hemos preparado una base para nuestro complemento, podemos comenzar a trabajar en nuestro objetivo central, es decir, obtener datos y mostrar estadísticas.

Obteniendo y mostrando estadísticas

Queremos obtener tres tipos de datos:

Publicaciones más populares (gráfico de columnas)
Las cinco categorías principales por número de publicaciones (gráfico de columnas)
Desglose de categorías por publicaciones (gráfico circular)

Publicaciones más populares

Para este tipo de datos, podemos usar la clase WP_Query para obtener cinco publicaciones que tengan el mayor número de comentarios. La clase WP_Query es útil cuando necesitamos buscar publicaciones según diferentes criterios. Con esta clase, podemos enumerar las publicaciones de la forma que queramos. La consulta para buscar publicaciones con el mayor número de comentarios se puede escribir como:


$posts = new WP_Query(
	array(
		'post_type'      => 'post',
		'orderby'        => 'comment_count',
		'order'          => 'DESC',
		'posts_per_page' => 5
	)
);

Ahora tenemos cinco publicaciones que tienen el mayor número de comentarios, en forma de objetos dentro de la matriz $posts. Siempre puedes hacer echo de la variable para ver con qué estás trabajando.

Necesitamos pasar este objeto junto con otros datos esenciales al JavaScript. Para ese propósito, primero prepararemos una matriz que contendrá el tipo de datos, el tipo de gráfico que necesitamos dibujar y, finalmente, las publicaciones que acabamos de obtener a través de WP_Query.


$data = array(
	'data_type'  => 'chart_most_popular',
	'chart_type' => 'column',
	'post_data'  => $posts->posts
);

Podemos pasar esta variable a JavaScript a través de wp_localize_script:

1
2	wp_localize_script( 'adminCharts', 'data', $data );

El primer argumento en la llamada de función es el identificador del script al que necesitamos pasar los datos. Habíamos registrado este script anteriormente. El segundo argumento es el nombre del objeto que estará disponible en JavaScript y el argumento final son los datos en sí mismos que necesitamos pasar. El index.php final debería verse así:


<?php
/*
Plugin Name: Admin Charts
Plugin URI: http://dev.imbilal.com/wpadmincharts
Description: Javascript charts for wordpress admin. These charts graphically show different statistics in the wordpress admin.
Version: 1.0
Author: Bilal Shahid
Author URI: http://www.imbilal.com
License: GPLv2 or later
*/

/********************************* Adding some constants for later use *********************************/
define( 'ROOT', plugin_dir_url( __FILE__ ) );

/********************************* Adding the admin page for the plugin *********************************/
add_action( 'admin_menu', 'chart_add_admin_page' );
function chart_add_admin_page() {
	add_plugins_page(
		'Charts For Wordpress',
		'Admin Charts',
		'administrator',
		'admin-charts',
		'render_admin_charts_page'
	);
}

function render_admin_charts_page() {
	?>
	<div class="wrap">
		<h2>Admin Charts</h2>
		<form action="#" method="post" name="admin_chart_form" id="admin_chart_form">
			<p>
				<label for="chart_data_type">What type of data do you want to show?</label>
				<select name="chart_data_type" id="chart_data_type">
					<option value="chart_most_popular" <?php selected_option('chart_most_popular'); ?>>Most Popular Post</option>
				</select>
			</p>
			<input type="submit" class="button-primary" value="Display Data" id="show_chart" name="show_chart">
		</form>
		<div id="chart-stats" class="chart-container" style="width:900px; height:500px;"></div>
	</div>
	<?php
}

/********************************* Adding necessary scripts/styles needed *********************************/
add_action( 'admin_enqueue_scripts', 'chart_register_scripts' );
function chart_register_scripts() {
	wp_register_script(
		'highCharts',
		ROOT . 'js/highcharts.js',
		array( 'jquery' ),
		'3.0',
		true
	);
	wp_register_script(
		'adminCharts',
		ROOT . 'js/admin_charts.js',
		array( 'highCharts' ),
		'1.0',
		true
	);
	wp_register_style(
		'adminChartsStyles',
		ROOT . 'css/admin_chart.css'
	);
}

add_action( 'admin_enqueue_scripts', 'chart_add_scripts' );
function chart_add_scripts( $hook ) {
	if ( 'plugins_page_admin-charts' == $hook ) {

		wp_enqueue_style( 'adminChartsStyles' );
		wp_enqueue_script( 'adminCharts' );

		// checking what type of data we are displaying
		if ( 'chart_most_popular' == $_POST['chart_data_type'] ) {
			$posts = new WP_Query(
				array(
					'post_type'      => 'post',
					'orderby'        => 'comment_count',
					'order'          => 'DESC',
					'posts_per_page' => 5
				)
			);
			$data = array(
				'data_type'  => 'chart_most_popular',
				'chart_type' => 'column',
				'post_data'  => $posts->posts
			);
			wp_localize_script( 'adminCharts', 'data', $data );
		}
	}
}
?>

Pero debemos asegurarnos de que WP_Query y wp_localize_script solo reciban una llamada cuando hayamos enviado el formulario; por lo tanto, los adjuntamos dentro de otra declaración if que verifica si se ha enviado el formulario:


if ( isset( $_POST['show_chart'] ) ) {

	if ( 'chart_most_popular' == $_POST['chart_data_type'] ) {

		$posts = new WP_Query(
			array(
				'post_type'      => 'post',
				'orderby'        => 'comment_count',
				'order'          => 'DESC',
				'posts_per_page' => 5
			)
		);

		$data = array(
			'data_type'  => 'chart_most_popular',
			'chart_type' => 'column',
			'post_data'  => $posts->posts
		);

		wp_localize_script( 'adminCharts', 'data', $data );

	}

}

Lo único que queda ahora es tomar los datos dentro de nuestro archivo JavaScript y dibujar el gráfico. Dentro del archivo js/admin_charts.js, agrega el siguiente código:


(function($){

	if ( 'chart_most_popular' == data.data_type ) {

		var post_titles = [],
		post_comment_count = [];

		$( data.post_data ).each(function() {

			post_titles.push( this.post_title );
			post_comment_count.push( parseInt( this.comment_count ) );

		});

		$('#chart-stats').highcharts({
			chart: {
				type: data.chart_type
			},
			title: {
				text: 'Most Popular Posts (by number of comments)'
			},
			xAxis: {
				categories: post_titles
			},
			yAxis: {
				title: {
					text: 'Number of Comments'
				}
			},
			series: [
				{
					name: 'Comments Count',
					data: post_comment_count
				}
			]
		});
	}
}(jQuery));

La matriz $data que habíamos pasado a través de index.php se ha convertido en un objeto dentro de JavaScript. Así podemos manipularlo como cualquier otro objeto JavaScript.

Primero estamos verificando el tipo de datos que ingresa:

1
2	if ( 'chart_most_popular' == data.data_type ) {

Luego, hemos inicializado dos matrices vacías para títulos de publicaciones y recuento de comentarios de publicaciones respectivamente:

1
2	var post_titles = [],
3	post_comment_count = [];

Y finalmente hemos iterado a través de las publicaciones y hemos tomado los títulos y el recuento de comentarios en las matrices que hemos inicializado:


$( data.post_data ).each(function() {

	post_titles.push( this.post_title );
	post_comment_count.push( parseInt( this.comment_count ) );

});

Ahora es el momento de dibujar el gráfico utilizando los datos que hemos obtenido, para eso hemos utilizado la API HighCharts:


$('#chart-stats').highcharts({
	chart: {
		type: data.chart_type
	},
	title: {
		text: 'Most Popular Posts (by number of comments)'
	},
	xAxis: {
		categories: post_titles
	},
	yAxis: {
		title: {
			text: 'Number of Comments'
		}
	},
	series: [
		{
			name: 'Comments Count',
			data: post_comment_count
		}
	]
});

Ahora regresa a Plugins > Admin Charts y después de seleccionar una opción en el menú desplegable, haz clic en el botón Enviar, ahora deberías tener un gráfico de columnas en funcionamiento.

Es posible que desees volver a tus publicaciones, agregar algunos comentarios y luego regresar para ver las estadísticas actualizadas:

Ahora podemos agregar soporte para más tipos de datos en nuestro complemento.

Las cinco categorías principales por número de publicaciones

Todo lo que tenemos que hacer ahora es obtener cinco categorías que tengan la mayor cantidad de publicaciones asociadas. Pero antes de eso, agreguemos una opción para este tipo de datos en nuestro menú desplegable de selección. Regresa a la función render_admin_charts_page que habíamos definido anteriormente y actualízala de la siguiente manera:


<select name="chart_data_type" id="chart_data_type">
	<option value="chart_most_popular">Most Popular Post</option>
	<option value="chart_top_cat">Top 5 Categories by Posts</option>
</select>

Podemos usar la función nativa de WordPress get_categories y pasar algunos argumentos:


$categories = get_categories(
	array(
		'orderby' => 'count',
		'order'   => 'desc'
	)
);

Luego recuperamos nuestros datos de la misma manera que lo habíamos hecho antes:


$data = array(
	'data_type'  => 'chart_top_cat',
	'chart_type' => 'column',
	'post_data'  => $categories
);

Entonces, el código final debería ser así:


if ( 'chart_cat_break' == $_POST['chart_data_type'] ) {

	$categories = get_categories(
		array(
			'orderby' => 'count',
			'order' => 'desc'
		)
	);

	$data = array(
		'data_type'  => 'chart_cat_breakup',
		'chart_type' => 'pie',
		'post_data'  => $categories
	);

	wp_localize_script( 'adminCharts', 'data', $data );

}

En admin_charts.js, inserta este código después de la instrucción if:


else if ( 'cart_top_cat' == data.data_type ) {

	var cat_titles = [],
	cat_count = [];

	$( data.post_data ).each(function() {

		cat_titles.push( this.name );
		cat_count.push( parseInt( this.count ) );

	});

	$('#chart-stats').highcharts({
		chart: {
			type: data.chart_type
		},
		title: {
			text: 'Top 5 Categories by Posts'
		},
		xAxis: {
			categories: cat_titles
		},
		yAxis: {
			title: {
				text: 'Number of Posts'
			},
			tickInterval: 5
		},
		series: [
			{
				name: 'Post Count',
				data: cat_count
			}
		]
	});
}

Estamos haciendo lo mismo que antes, pero esta vez hemos cambiado el título del gráfico y los títulos de los ejes. Ahora deberíamos tener otro gráfico que muestre las cinco categorías principales con la mayor cantidad de publicaciones:

Desglose de categorías por publicaciones

Nuestro último tipo de datos es la división de categorías por número de publicaciones. Para este tipo de datos, utilizaremos el gráfico circular como sea más apropiado en este caso. También ten en cuenta que una sola publicación puede pertenecer a varias categorías.

Utilizaremos la misma función get_categories, pero esta vez no estamos limitando el número de categorías que obtenemos, sino que necesitamos obtener todas las categorías para mostrar la separación.

Entonces, comenzaremos verificando si la opción ha sido seleccionada para este tipo de datos y luego llamaremos a nuestra función para recuperar las categorías, preparar nuestra matriz y luego pasarla al JavaScript:


if ( 'chart_cat_breakup' == $_POST['chart_data_type'] ) {
	$categories = get_categories(
		array(
			'orderby' => 'count',
			'order'   => 'desc'
		)
	);
	$data = array(
		'data_type'  => 'chart_cat_breakup',
		'chart_type' => 'pie',
		'post_data'  => $categories
	);
	wp_localize_script( 'adminCharts', 'data', $data );
}

Es relativamente simple dibujar un gráfico circular. En admin_charts.js, agrega el siguiente código después de la instrucción else-if existente:


else if ( 'chart_cat_breakup' == data.data_type ) {
	var number_posts  = [];
	$( data.post_data ).each(function() {
		number_posts.push( [ this.name, parseInt( this.count ) ] );
	});
	$('#chart-stats').highcharts({
		title: {
			text: 'Breakup of Categories by Number of Posts'
		},
		tooltip: {
			pointFormat: 'Number {series.name}: <b>{point.y}</b><br>{series.name} Share: <b>{point.percentage:.1f}%</b>'
		},
		series: [{
			type: 'pie',
			name: 'Posts',
			data: number_posts
		}]
	});
}

Ten en cuenta que hemos formateado la información sobre herramientas para mostrar el porcentaje en lugar de un entero. Ya casi hemos terminado, excepto por una pequeña función de utilidad que podemos agregar a cada una de nuestras opciones de selección para que persista cuando la página se carga después de enviar el formulario.

Agrega este pequeño código dentro de index.php después de la función render_admin_charts_page:


function selected_option( $option ) {
	if ( $otpion == $_POST['chart_data_type'] ) {
		echo 'selected="selected"';
	}
}

Y luego llama a la función dentro de cada una de nuestras opciones seleccionadas:


<select name="chart_data_type" id="chart_data_type">
	<option value="chart_most_popular" <?php selected_option( 'chart_most_popular' ); ?>>Most Popular Post</option>
	<option value="chart_top_cat" <?php selected_option( 'chart_top_cat' ); ?>>Top 5 Categories by Posts</option>
	<option value="chart_cat_breakup" <?php selected_option( 'chart_cat_breakup' ); ?>>Breakup of Categories by Posts</option>
</select>

Nuestro complemento ahora está completo y ahora tiene tres gráficos de trabajo para diferentes tipos de datos. Siéntete libre de jugar y agregar más gráficos para obtener más tipos de datos.

Conclusión

En este tutorial creamos nuestro propio complemento desde cero y agregamos una página separada en wp-admin. También hemos analizado algunas de las técnicas que pueden ser útiles al desarrollar para WordPress.

Estos incluyen diferentes formas de obtener la información requerida sobre las publicaciones y categorías y luego pasarla al JavaScript para que podamos usarla para diferentes propósitos.

Espero que hayas encontrado útil este tutorial y no olvides dar tu opinión constructiva en los comentarios.