Spanish (Español) translation by Rafael Chavarría (you can also view the original English article)
En una serie anterior publiqué una guía para trabajar con la API de Ajustes de WordPress en profundidad. Para aquellos que son nuevos en WordPress o quienes han estado usando otras herramientas tales como The Customizer para manejar varias opciones, podría ser algo que no has tenido que usar en tu tema o desarrollo de complemento.
Como se declara en el Codex:
La API de Ajustes, agregada en WordPress 2.7, permite a las páginas de administración contener formularios de ajustes para ser administrados de manera semi-automática. Te permite definir páginas de ajustes, secciones dentro de esas páginas y campos dentro de las secciones.
No creo que sea algo que se requiera aprender, pero es algo que deberías saber que existe y cómo trabajar con ello si necesitas introducir páginas de opción en el área de administración de WordPress.
Es una API poderosa, aunque algo compleja, que nos proporciona mucha funcionalidad. Por último, nos permite hacer mucho trabajo en el lado del servidor y trabajo mínimo en el lado del cliente.
Pero qué sobre las veces cuando estamos trabajando con una solución personalizada para clientes y necesitamos un poco más de flexibilidad que la que proporciona la API de Ajustes? Por ejemplo, ¿digamos que necesitamos construir un complemento que tendrá una página de ajustes pero necesita un conjunto más flexible de opciones y funcionalidad de validación a la medida?
En esos casos, es posible escribir nuestras propias páginas personalizadas de administración de WordPress. En esta serie, vamos a echar un vistazo a cómo hacer exactamente eso.
Antes de Empezar
Como con la mayoría de tutoriales como este, es importante estar seguro de que dispones de todo lo necesario para seguir adelante para que puedas trabajar con el código fuente que veremos a lo largo de esta serie.
Para este tutorial asumo que:
- Tienes un entorno de desarrollo local configurado de acuerdo a tu sistema operativo.
- Tienes una copia de WordPress instalada y preparada para usarla para instalar un plugin.
- Estás familiarizado con las prácticas de desarrollo de plugins WordPress.
- Te sientes cómodo trabajando con PHP y HTML.
Si no estás familiarizado con la configuración de un entorno de desarrollo local que incluya WordPress, mira esta serie para saber como hacerlo.
Y si te sientes relativamente confortable con PHP aunque sólo sea leyendo el lenguaje entonces yo lo haré lo mejor que pueda para darte instrucciones y comentarios para cada trozo de código que compartimos.
Una vez que tenemos todo listo, estamos preparados para empezar a trabajar con nuestro plugin.
Ajustes de Administración Personalizada en WordPress
Al final de la serie, vamos a tener un complemento que reúne los siguientes requerimientos:
- Agrega un elemento de submenú al al sistema de menú existente de WordPress.
- Agrega una nueva página de ajustes que corresponde al nuevo elemento de sub-menú.
- Limpia y serializa opciones en la página.
- Valida y regresa los valores que guardamos y los genera de manera acorde.
Además, nos aseguraremos de que nos aproximamos a esto en la manera más modular posible usando los Estándares de Codificación WordPress y prácticas similares para hacer la lectura, escritura y mantenimiento de nuestro complemento tan fácil como sea posible.
1. El Complemento Boostrap
La primera cosa que necesitamos hacer es crear el complemento bootstrap. Esto incluirá crear un directorio para contener todos los archivos del complemento, un LÉEME básico, una copia de la licencia, un archivo bootstrap que eventualmente será usado para iniciar el complemento, y un directorio que será usado para contener las clases relacionadas a la funcionalidad administrativa.
Los archivos están disponibles para descarga como un adjunto a este artículo pero, mientras tanto, puedes ver cómo luce mi directorio abajo:
Además, los contenidos del complemento bootstrap son simples. Revisa el siguiente código para el archivo PHP custom-admin-settings.php, y después lo discutiré en más detalle abajo del bloque.
1 |
<?php
|
2 |
/**
|
3 |
* The plugin bootstrap file
|
4 |
*
|
5 |
* This file is read by WordPress to generate the plugin information in the
|
6 |
* plugin admin area. This file also defines a function that starts the plugin.
|
7 |
*
|
8 |
* @link https://code.tutsplus.com/tutorials/creating-custom-admin-pages-in-wordpress-1
|
9 |
* @since 1.0.0
|
10 |
* @package Custom_Admin_Settings
|
11 |
*
|
12 |
* @wordpress-plugin
|
13 |
* Plugin Name: Custom Admin Settings
|
14 |
* Plugin URI: http://code.tutsplus.com/tutorials/creating-custom-admin-pages-in-wordpress-1
|
15 |
* Description: Demonstrates how to write custom administration pages in WordPress.
|
16 |
* Version: 1.0.0
|
17 |
* Author: Tom McFarlin
|
18 |
* Author URI: https://tommcfarlin.com
|
19 |
* License: GPL-2.0+
|
20 |
* License URI: http://www.gnu.org/licenses/gpl-2.0.txt
|
21 |
*/
|
22 |
|
23 |
// If this file is called directly, abort.
|
24 |
if ( ! defined( 'WPINC' ) ) { |
25 |
die; |
26 |
}
|
27 |
|
28 |
add_action( 'plugins_loaded', 'tutsplus_custom_admin_settings' ); |
29 |
/**
|
30 |
* Starts the plugin.
|
31 |
*
|
32 |
* @since 1.0.0
|
33 |
*/
|
34 |
function tutsplus_custom_admin_settings() { |
35 |
|
36 |
}
|
Nota que en el código de arriba, realmente hay muy poco código. En su lugar, son muchos comentarios. El bloque principal de comentarios en la parte superior del archivo explica lo que hace el archivo.
El área debajo de la etiqueta @wordpress-plugin es lo que WordPress leerá para generar el título del complemento, descripción y enlaces relativos en el tablero del complemento de WordPress.
Después, prevenimos a cualquiera de acceder al archivo directamente. Y, finalmente, creamos una función personalizada para ser disparada con el gancho plugins_loaded. Esta función es lo que será usado para comenzar el complemento.
En este punto, deberías poder iniciar sesión en WordPress, navegar al Tablero del Complemento, y después ver el complemento disponible para activar. Continúa y da clic en Activar.
Nada sucederá aún, pero comenzaremos agregando funcionalidad mientras trabajamos en este tutorial.
2. Creando el Elemento de Sub-Menú
Para comenzar a trabajar en el complemento, primero introduciremos un elemento de sub-menú. Para hacer esto, necesitamos sacar ventaja de la función add_options_page de la API de WordPress. Esta función requerirá cinco parámetros:
- el texto a mostrar como el título de la página de opciones correspondiente
- el texto a mostrar como el texto de sub-menú para el elemento de menú
- las capacidades necesarias para acceder a este elemento de menú
- la ficha de menú que es usado para identificar a este elemento de sub-menú
- una llamada de retorno a una función que es responsable de generar la página de administración
Nota que estaré usando clases para organizar nuestra funcionalidad, de manera que mucho de lo que estamos haciendo será orientado a objetos.
Primero, creemos una clase en el directorio de administración llamado class-submenu.php. Ya que esta clase es responsable de introducir un nuevo sub-menú, la nombraremos de manera descriptiva.
Los contenidos de la clase deberían lucir así:
1 |
<?php
|
2 |
/**
|
3 |
* Creates the submenu item for the plugin.
|
4 |
*
|
5 |
* @package Custom_Admin_Settings
|
6 |
*/
|
7 |
|
8 |
/**
|
9 |
* Creates the submenu item for the plugin.
|
10 |
*
|
11 |
* Registers a new menu item under 'Tools' and uses the dependency passed into
|
12 |
* the constructor in order to display the page corresponding to this menu item.
|
13 |
*
|
14 |
* @package Custom_Admin_Settings
|
15 |
*/
|
16 |
class Submenu { |
17 |
|
18 |
/**
|
19 |
* A reference the class responsible for rendering the submenu page.
|
20 |
*
|
21 |
* @var Submenu_Page
|
22 |
* @access private
|
23 |
*/
|
24 |
private $submenu_page; |
25 |
|
26 |
/**
|
27 |
* Initializes all of the partial classes.
|
28 |
*
|
29 |
* @param Submenu_Page $submenu_page A reference to the class that renders the
|
30 |
* page for the plugin.
|
31 |
*/
|
32 |
public function __construct( $submenu_page ) { |
33 |
$this->submenu_page = $submenu_page; |
34 |
}
|
35 |
|
36 |
/**
|
37 |
* Adds a submenu for this plugin to the 'Tools' menu.
|
38 |
*/
|
39 |
public function init() { |
40 |
add_action( 'admin_menu', array( $this, 'add_options_page' ) ); |
41 |
}
|
42 |
|
43 |
/**
|
44 |
* Creates the submenu item and calls on the Submenu Page object to render
|
45 |
* the actual contents of the page.
|
46 |
*/
|
47 |
public function add_options_page() { |
48 |
|
49 |
add_options_page( |
50 |
'Tuts+ Custom Administration Page', |
51 |
'Custom Administration Page', |
52 |
'manage_options', |
53 |
'custom-admin-page', |
54 |
array( $this->submenu_page, 'render' ) |
55 |
);
|
56 |
}
|
57 |
}
|
En este punto, el complemento aún no hará nada. Todavía necesitamos crear la clase Submenu_Page, y después necesitamos enlazar las clases al archivo bootstrap.
3. Creando la Página de Sub-Menú
Comencemos primero con la clase Submenu_Page. Crea otro archivo en el directorio admin llámalo class-submenu-page.php. Después, en el archivo, agrega el siguiente código.
1 |
<?php
|
2 |
/**
|
3 |
* Creates the submenu page for the plugin.
|
4 |
*
|
5 |
* @package Custom_Admin_Settings
|
6 |
*/
|
7 |
|
8 |
/**
|
9 |
* Creates the submenu page for the plugin.
|
10 |
*
|
11 |
* Provides the functionality necessary for rendering the page corresponding
|
12 |
* to the submenu with which this page is associated.
|
13 |
*
|
14 |
* @package Custom_Admin_Settings
|
15 |
*/
|
16 |
class Submenu_Page { |
17 |
|
18 |
/**
|
19 |
* This function renders the contents of the page associated with the Submenu
|
20 |
* that invokes the render method. In the context of this plugin, this is the
|
21 |
* Submenu class.
|
22 |
*/
|
23 |
public function render() { |
24 |
echo 'This is the basic submenu page.'; |
25 |
}
|
26 |
}
|
Cuando esta página se genera, simplemente mostrará el texto: "This is a basic submenu page." Eventualmente agregaremos nuevas opciones. Pero primero, traigamos a este complemento a la vida instanciándolo dentro de nuestro archivo bootstrap.
4. Generando el Menú y la Página
Después, abre el archivo custom-admin-settings.php que creamos anteriormente en este tutorial. Continuemos y escribamos el código necesario para introducir el nuevo elemento de sub-menú y su página asociada.
Recuerda, la clase Submenu requiere que una instancia de la clase Submenu_Page sea pasada a su constructor, y después necesitamos llamar al método init en la clase Submenu para poner todo en movimiento.
En código, esto luce como lo siguiente:
1 |
<?php |
2 |
|
3 |
// If this file is called directly, abort. |
4 |
if ( ! defined( 'WPINC' ) ) {
|
5 |
die; |
6 |
} |
7 |
|
8 |
// Include the dependencies needed to instantiate the plugin. |
9 |
foreach ( glob( plugin_dir_path( __FILE__ ) . 'admin/*.php' ) as $file ) {
|
10 |
include_once $file; |
11 |
} |
12 |
|
13 |
add_action( 'plugins_loaded', 'tutsplus_custom_admin_settings' ); |
14 |
/** |
15 |
* Starts the plugin. |
16 |
* |
17 |
* @since 1.0.0 |
18 |
*/ |
19 |
function tutsplus_custom_admin_settings() {
|
20 |
|
21 |
$plugin = new Submenu( new Submenu_Page() ); |
22 |
$plugin->init(); |
23 |
|
24 |
} |
En este punto, deberías poder refrescar tu instalación de WordPress, activar el complemento (si no está ya activiad), y después ver tu nueva página generada dentro del área de administración.
En el siguiente artículo, veremos cómo podemos comenzar a introducir ajustes reales en la pantalla. De manera adicional, veremos algunas de las mejores prácticas en términos de trabajar con nuestra plantilla y nuestros parciales de plantillas, y después veremos como pueden ser enlazadas a la API responsable no solo de guardarlas sino de como las limpiamos y validamos.
Pero antes de ir más lejos, quiero hablar un poco sobre el diseño de clase que hemos visto en este tutorial. Hablando de manera general, quiero hablar sobre por qué tenemos una clase para Submenu y la Submenu_Page y cómo se relaciona al archivo bootstrap.
Una Palabra sobre Responsabilidad de Clase
Para aquellos que están familiarizados con el Principio de Responsabilidad Única, esta sección podría no ser de interés alguno para ti. Pero si necesitas un recordatorio o quieres escuchar más, entonces sigue leyendo.
Reúne las cosas que cambian por las mismas razones. Separa aquellas cosas que cambian por distintas razones.
Hay mucho más sobre esto, pero si vieras a cada una de las clases (al menos las dos que tenemos hasta ahora), entonces es claro que las razones por las que nuestras clases pueden cambiar son como siguen:
- Los contenidos del sub-menú podrían cambiar. Cualquier cosa desde el título de la página al menú y todo en medio.
- La manera en que la página genera su contenido podría (y cambiará). Específicamente, justo ahora no hace nada más que imprimir una cadena de texto. Pronto, incluirá un archivo particular. Después de eso, podría necesitar incluir múltiples archivos.
Las dos razones de arriba son dos razones muy diferentes que las clases podrían cambiar, así que mantenerlas juntas en la misma clase violaría el principio de arriba.
Por último, menciono esto no solo para ayudar a arrojar luz sobre principios de ingeniería de software más grandes que pueden ser aplicados en WordPress, pero también para ayudarte a prepararte para algunas de las razones que vamos a estar desglosando aparte de ciertas cosas que son usualmente archivos grandes dentro del contexto de complementos.
Lo bueno sobre principios de aprendizaje es que pueden ser aplicados a múltiples proyectos y no solo a proyectos individuales. Los aprendes, practicas usándolos, y te vuelves mejor en la arquitectura de soluciones para otra gente.
La curva de aprendizaje podría parecer empinada, pero una vez que comienzas esa cuesta, se vuelve más fácil incorporar los principios en tu trabajo cotidiano. Después, el trabajo que estás proporcionando para otros se vuelve mucho más fácil de mantener a lo largo del tiempo.
Conclusión
No olvides que puedes descargar el complemento en su estado actual desde esta publicación. Mientras progresamos en la serie, haré disponible la versión más reciente en cada publicación así que podrás seguir a la par con el código cubierto en cada tutorial, juega con el, y prepara preguntas que podrías querer hacer en los comentarios.
Como nota adicional, si estás buscando otras utilidades para ayudarte a construir tu propio conjunto de herramientas crecientes para WordPress o para código para estudiar y convertirte mejor versado en WordPress, no olvides ver lo que tenemos disponible en Envato Market.
Recuerda, puedes ver todos mis cursos y tutoriales en mi página de perfil, y puedes seguirme en mi blog y/o Twitter @tommcfarlin en donde hablo sobre varias prácticas de desarrollo de software y cómo las empleo en WordPress.
Finalmente, no dudes en dejar cualquier pregunta o comentario en la sección de abajo. Hago lo mejor para participar y contestar todas la preguntas o críticas que ofreces y se relaciona a este proyecto.
Recursos
By
