Crear una página de opciones en WordPress con React – Parte 1

A pesar de los avances en Gutenberg que hemos visto los últimos años, con la idea de que las opciones de un post (o una página) deben ser manejadas dentro del propio editor de WordPress (a.k.a Gutenberg). Muchas veces aún nos vemos en la necesidad de tener una página en donde podamos manejar todas nuestras opciones globales, fuera de cada post en específico. A continuación mostraré como crear una página de opciones en WordPress con React.

#Tabla de Contenido

• Introducción
• Paso 1: Creando el ambiente local
• Paso 2: Crear una página de opciones en WordPress
• Paso 3: Registrar nuestros scripts
• Conclusión

#Decisiones, decisiones…

Como todo en WordPress (y en desarrollo en general), tenemos varias opciones, una de ellas es utilizar Customizer, o utilizamos una página de opciones. ¿Cuáles son las diferencias entre estas?

Opción 1: Customizer

Customizer es la parte de WordPress que ha sido creada para personalizar nuestro sitio (“customise”), fue creada precisamente para ello, y con ello tienes sus pros y sus contras:

Pros

• Fue diseñada especificamente para este fin
• Cada opción puede ser agregada a su panel personalizado, o a uno general
• Ofrece live preview para ver los cambios al momento
• Ofrece una gama de controles existentes para hacer el trabajo más fácil

Cons

• Será descontinuado en un futuro no muy lejano
• Su biblioteca de controles no es muy amplia
• Los controles más personalizados puedes ser difíciles de implementar

Opción 2: Página de opciones

En cambio, si creamos nuestra propia página de opciones, tenemos más control sobre nuestro resultado; sin embargo, al mismo tiempo, tenemos que crear todo nosotros mismos¹.

Pros

• Control total sobre lo que hacemos
• Puede vivir en cualquier parte de la administración
• Podemos usar la Settings API para facilitar el trabajo

Cons

• Requiere más código

Para propositos de este tutorial, utilizaré la opción dos, pero con una diferencia importante. No utilizaré la mencionada Settings API, si no que en su lugar utilizaré React, con ayuda de los componentes existentes en Gutenberg.

Ahora si, después de esta enorme introducción (¡lo siento!) podemos comenzar con el tutorial.

#Paso 1: Creando el ambiente local

Debido a que este es un tutorial técnico, asumiré que tienes cierto conocimiento sobre como iniciar un proyecto local, normalmente diría que puedes usar cualquier ambiente que desees, y sigo diciéndolo, unicamente pediré que sea capaz de utilizar node e instales el paquete @wordpress/scripts (como en mi tutorial Compilando CSS y Javascript con wp-scripts).

Después de tener nuestro ambiente local, podemos crear nuestro plugin, en éste caso necesitamos uno muy sencillo, simplemente una clase que iniciaremos para poder registrar nuestra página:

mah-settings.php

1<?php
2/**
3 * Plugin Name: Mah Settings
4 * Description: Tutorial para crear una página de opciones con React
5 * Version: 1.0.0
6 * Author: Mario Aguiar
7 * Author URI: https://marioaguiar.net
8 * License: GPLv2 or later
9 * Text Domain: mah-settings
10 */
11namespace Mah_Settings;
12
13require_once __DIR__ . '/php/class-mah-settings.php';
14
15use Mah_Settings\Settings;
16
17// Exit if accessed directly.
18if ( ! defined( 'ABSPATH' ) ) {
19    exit;
20}
21
22$settings = new Settings();
23$settings->init();
24

php/class-mah-settings.php

1<?php
2/**
3 * @package Mah_Settings
4 */
5namespace Mah_Settings;
6/**
7 * Maneja la página de opciones
8 */
9class Settings {
10    /**
11     * Registra los hooks.
12     *
13     * @return void
14     */
15    public function init(): void {
16        var_dump( 'Mi página' );
17    }
18}
19

Una vez creados estos archivos podremos entrar en nuestro sitio y ver Mi página en la parte superior, esto significa que nuestro plugin está funcionando.

#Paso 2: Crear una página de opciones en WordPress

Una vez que tenemos nuestro plugin functionando, reemplazaremos el contenido de la función init por el hook admin_menu, que nos ayuda a registrar nuestra página en el menú:

1/**
2 * @var string
3 */
4private $plugin_path = '';
5
6/**
7 * Menu slug.
8 *
9 * @var string
10 */
11private $menu_slug = '';
12
13public function __construct( string $plugin_file ) {
14    $this->plugin_path = plugin_dir_path( $plugin_file );
15}
16
17/**
18 * Registra los hooks.
19 *
20 * @return void
21 */
22public function init(): void {
23    add_action( 'admin_menu', [ $this, 'add_menu_page' ] );
24}
25
26/**
27 * Registra la página de opciones.
28 *
29 * @return void
30 */
31 public function add_menu_page(): void {
32    $this->menu_slug = add_menu_page(
33        __( 'Mah Settings', 'mah-settings' ),
34        __( 'Mah Settings', 'mah-settings' ),
35        'manage_options',
36        'mah-settings',
37        [ $this, 'render_settings_page' ],
38        'dashicons-admin-generic',
39        99
40    );
41 }
42
43/**
44 * Renderiza la página de opciones.
45 *
46 * @return void
47 */
48public function render_settings_page(): void {
49    ?>
50    <div class="wrap">
51        <h1><?php esc_html_e( 'Mah Settings', 'mah-settings' ); ?></h1>
52        <div id="mah-settings"></div>
53    </div>
54    <?php
55}
56

Hay un par de cosas importantes sucediendo aquí, trataré de explicarlas brevemente:

1. La función add_menu_page simplemente registra un enlace en el menu izquierdo de la administración, en ella agregamos el título, las capabilidades (o permisos) requeridos para ver ese menú, y especificamos que función debe ser ejecutada cuando se accede a ese menú, que en este caso será render_settings_page. Esta función regresa el hook de esta nueva página, el cual guardaremos para después.
2. En la función render_settings_page, que será mostrada cuando se acceda a esta página, simplemente agregamos un título (opcional) y un contenedor vacío. ¿Por qué agregamos esto? Porque será llenado con React.

#Paso 3: Registrar nuestros scripts

Para poder registrar nuestros scripts dentro de la página, primero necesitamos crearlos, para ello comenzaremos con utilizar el paquete @wordpress/scripts del que hablamos anteriormente, así que, en una terminal corremos:

1npm install --save-dev @wordpress/scripts
2

Después de esto podemos actualizar la configuración para que compile nuestros nuevos archivos, ya sea dentro el mismo package.json o con un simple archivo de configuración de webpack, así que creamos un archivo llamado webpack.config.js y colocamos lo siguiente:

webpack.config.js

1const defaultConfig = require('@wordpress/scripts/config/webpack.config');
2
3module.exports = {
4  ...defaultConfig,
5  entry: {
6    ...defaultConfig.entry(),
7    settings: './js/src/settings.js',
8  },
9};
10

package.json

1"scripts": {
2  "test": "echo \"Error: no test specified\" && exit 1",
3  "start": "wp-env start",
4  "stop": "wp-env stop",
5  "build": "wp-scripts build",
6  "dev": "wp-scripts start"
7}
8

js/src/settings.js

1console.log('Hello settings');
2

Básicamente estamos extendiendo la configuración por defecto que provee WordPress para agregar un nuevo archivo: settings.js, después de esto podemos correr npm run dev para que nuestro archivo sea vigilado y cada nuevo cambio sea compilado.

Después de tener nuestros archivos creados, podemos registrarlos con el hook admin_enqueue_scripts

1public static function init(): void {
2    add_action( 'admin_menu', [ $this, 'add_menu_page' ] );
3    add_action( 'admin_enqueue_scripts', [ $this, 'enqueue_scripts' ] );
4}
5

1/**
2 * Registra los scripts y estilos.
3 *
4 * @return void
5 */
6public function enqueue_scripts(): void {
7    $screen = get_current_screen();
8    if ( $screen->id !== $this->menu_slug ) {
9        return;
10    }
11    $asset = include $this->plugin_path . '/build/settings.asset.php';
12    wp_enqueue_script(
13        'mah-settings',
14        plugins_url() . '/mah-settings-react/build/settings.js',
15        $asset['dependencies'],
16        $asset['version'],
17        true
18    );
19}
20

Ahora explicaré un poco lo que sucede aquí:

1. Conseguimos la información de la página actual utilizando get_current_screen
2. Comparamos el ID de la página actual con el hook que guardamos cuando creamos la página, si es el mismo, continuamos; si no, aquí terminamos.
3. Finalmente registramos nuestro nuevo script utilizando las dependencias que se agregan al archivo (gracias a @wordpress/scripts)

Si todo salió bien, tendremos nuestro archivo funcionando en la página:

#¿Qué sigue?

En la parte 2 de este tutorial, explicaré como podemos agregar la parte React a nuestro sitio utilizando los componentes de @wordpress/components. Por ahora, espero que esta introducción haya sido útil para crear una página de opciones en WordPress con React y por favor hazme saber cualquier duda que tengas. Si quieres ver el código fuente que utilicé en este tutorial puedes hacerlo mi repositorio:

#Leer más…

• Creating a WordPress options page using React and Gutenberg
• @wordpress/scripts
• @wordpress/env