Crea una página de ajustes para tu plugin de WordPress



En artículos anteriores he estado enseñando como crear plugin de WordPress. Ahora voy a explicar cómo crear una página para ingresar datos de ajustes o configuración de tu plugin.

Vamos a trabajar con el ejemplo del plugin para insertar el código de Google Analytics, pero ahora el código se seguimiento podrá ser ingresado desde la página de administración de WordPress.

Vamos a trabajar con un plugin desde cero, pero voy a saltar las explicaciones básicas, si nunca has creado un plugin, te recomiendo que leas primero este artículo muy breve, pero completo sobre cómo crear un plugin para WordPress.

Estos son los temas que veremos:

Crear un campo de ajustes para un plugin de WordPress.

Primero necesitas crear o definir un campo para guardar y leer las opciones de tu plugin. La opción también debe tener un valor predeterminado y para definir un valor predeterminado debemos hacer una función que sea llamada en el momento en que el plugin se instala.

Una función que defina una opción predeterminada sería una como esta:

function cn_set_default_options() {
    // Revisar si ya se habia activado antes
    if ( get_option( 'cn_ga_cuenta' ) === false ) 
    {
        // Si no existe, crear esta opcion con
        // este valor predeterminado
        add_option( 'cn_ga_cuenta', 'UA-0000000-0' );
    }
}

Recuerda que la función debe tener un nombre único, por eso yo les pongo un prefijo a todas (en este caso el prefijo es cn_). En el código anterior primero uso la función get_option para obtener el valor de una configuración que se guarda, en este caso con el nombre cn_ga_cuenta (este nombre también debe ser único) y si lo que regresa es igual a false entonces la opción aún no ha sido creada.

Entonces la creo usando la función add_option con el nombre de la opción y el valor predeterminado. Ahora necesitamos una forma de hacer que esta función se ejecute en 3 momentos:

  • Al activar el plugin por primera vez: Cuando por primera vez alguien descarga nuestro plugin y lo activa.
  • Al actualizar: Cuando alguien actualiza tu plugin, en caso de que decidas agregar una opción nueva.
  • Al volver a activar: En caso de que hayan borrado la opción en la base de datos.

Podemos hacerlo usando la función de WordPress register_activation_hook. El código final se verá como este:

<?php
/*
Plugin Name: Plugin con parametros
Plugin URI: https://www.codigonaranja.com
Description: Pantalla de parametros
Version: 1.0
Author: Luis Cruz
Author URI: https://www.codigonaranja.com
License: GPLv2
*/
//Este Script se correra en 3 momentos: Al activar por primera vez, al actualizar, al reactivar
register_activation_hook( __FILE__, 'cn_set_default_options' );
function cn_set_default_options() {
    // Revisar si ya se habia activado antes
    if ( get_option( 'cn_ga_cuenta' ) === false ) {
        add_option( 'cn_ga_cuenta', 'UA-0000000-0' );
    }
}

Ahora ya hemos creado una opción para configurar el plugin, podemos leerla en cualquier momento usando la función get_option

Si en este momento activamos el plugin podremos revisar que en la base de datos de WordPress y en la tabla *_option hay un nuevo registro que guarda nuestra configuración.

Guardar ajustes de plugin en WordPress

Agregar un menú de ajustes para el plugin de WordPress

El siguiente paso será insertar un menú en los ajustes de WordPress, al seguir estos pasos lograrás algo como esto, en donde vamos a ingresar nuestro código de seguimiento de Google Analytics.

Agregar una opción en el menú de ajustes de WordPress

En el archivo anterior vamos a agregar estas líneas de código al final:

function cn_menu_ajustes() {
    add_options_page( 'Configuracion Google Analytics', //Titulo de la pagina
                      'Codigo de Google Analytics', //Nombre del menu
                      'manage_options', //Nivel de acceso, solo usuarios
                      'cn-conf-ga', // slug
                      'cn_genera_pagina' ); //Funcion que procesara todo
}

Como puedes ver solo he creado una función llamada cn_menu_ajustes y la función solo llama a la función de WP add_options_page. Esta última función recibe 5 parámetros:

El primero es el título de la página, este se mostrará en el título de la pestaña del navegador. El segundo, es el nombre que se mostrará en el menú Ajustes de WordPress.

El tercero es el nivel de acceso o permisos, WordPress maneja usuarios y roles. Cada rol tiene ciertos permisos de forma predefinida y en este caso estamos permitiendo que cualquier usuario con el acceso manage_options pueda ingresar a esta opción. Si quieres conocer una lista de accesos por rol, puedes consultar este enlace.

El cuarto es el slug o la parte final de la url con la que se puede acceder a esta configuración. El quinto parámetro es la función que va a generar el código HTML de la página de configuración.

Ahora para que el menú se genere necesitamos hacer que WordPress llame a nuestra función, para ello podemos agregar esta línea de código:

add_action( 'admin_menu', 'cn_menu_ajustes' );

también tenemos que definir la función que colocamos como el quinto parámetro, ¿recuerdas?, la nombre cn_genera_pagina. Por el momento la función estará vacía.

//Generar el codigo de la pagina de actualización
function cn_genera_pagina() {
  //Codigo pendiente.....
}

Hasta ahora el código completo debe verse así:

<?php
/*
Plugin Name: Plugin con parametros
Plugin URI: https://www.codigonaranja.com
Description: Pantalla de parametros
Version: 1.0
Author: Luis Cruz
Author URI: https://www.codigonaranja.com
License: GPLv2
*/
# Agregar informacion predeterminada al activar el plugin
//Este Script se correra en 3 momentos: Al activar por primera vez, al actualizar, al reactivar
register_activation_hook( __FILE__, 'cn_set_default_options' );
function cn_set_default_options() {
    // Revisar si ya se habia activado antes
    if ( get_option( 'cn_ga_cuenta' ) === false ) {
        add_option( 'cn_ga_cuenta', 'UA-0000000-0' );
    }
}
#Agregar esta condiguracion al menu
function cn_menu_ajustes() {
    add_options_page( 'Configuracion Google Analytics', //Titulo de la pagina
                      'Codigo de Google Analytics', //Nombre del menu
                      'manage_options', //Nivel de acceso, solo usuarios
                      'cn-conf-ga', // slug
                      'cn_genera_pagina' ); //Funcion que procesara todo
}
add_action( 'admin_menu', 'cn_menu_ajustes' );
//Generar el codigo de la pagina de actualización
function cn_genera_pagina() {
  //Codigo pendiente.....
}

Ya puedes probar el plugin y verás que ya aparece una opción nueva en el menú de ajustes de WordPress. Aunque la página de configuración estará en blanco.

Generar una página para modificar los ajustes del plugin de WordPress

Ahora vamos a escribir el código HTML para la página de ajustes de nuestro plugin y lo haremos escribiendo el código para la función cn_genera_pagina, la cual quedará de esta forma:

//Generar el codigo de la pagina de actualización
function cn_genera_pagina() {
    // Conseguir el valor de GA
    $codigo_ga = get_option( 'cn_ga_cuenta' ) ;
    ?>
    <div class="wrap">
    <h2>Google Analytic</h2>
    <form method="post" action="admin-post.php">
      <input type="hidden" name="action"  value="guardar_ga" />
      <!-- mejorar la seguridad -->
      <?php wp_nonce_field('token_ga'); ?>
      Código de Google Analytic:
      <input type="text" name="codigo_ga"
          value="<?php echo esc_html($codigo_ga);
          ?>"/>
       <br />
      <input type="submit" value="Guardar" class="button-primary"/>
    </form>
    </div>
<?php
}

Lo que el código anterior hace, es básicamente generar el código HTML del formulario e imprimirlo directamente (no lo guarda, ni regresa como valor de retorno). Primero recupera el valor de la opción que creamos al inicio de este artículo, luego crea un formulario con un campo escondido que nos servirá después para llamar a la función que procese los datos del formulario.

También creamos un token de seguridad con la función wp_nonce_field de WordPress.

Ahora vamos a encargarnos de procesar el valor capturado en el formulario anterior. Cuando definimos el campo oculto con el valor guardar_ga, estábamos definiendo el hook que WP va a usar para procesar el formulario, WP siempre le agrega el texto admin_post_ y crea un hook.

Procesar los valores ingresados en el formulario de ajuste del plugin de WP

Entonces vamos a usar la función add_action, para decirle a WP qué función debe ejecutar con este hook.

add_action( 'admin_post_guardar_ga', 'cn_guardar_ga' );

Y vamos a definir el código de la función que guardará el valor del formulario en la base de datos de WordPress.

function cn_guardar_ga() {
    // Revisar el permiso de autorización
    if ( !current_user_can( 'manage_options' ) ) {
        wp_die( 'Not allowed' );
    }
    // Revisar el token que creamos antes
    check_admin_referer( 'token_ga' );
    //Limpiar valor, para prevenir problemas de seguridad
    $codigo_ga = sanitize_text_field( $_POST['codigo_ga'] );
    // Guardar el valor en la base datos
    update_option( 'cn_ga_cuenta', $codigo_ga );
    // Regresamos a la pagina de ajustes
    wp_redirect( add_query_arg( 'page',
                                'cn-conf-ga',
                            admin_url( 'options-general.php' ) ) );
    exit;
}

Primero nos aseguramos de que el usuario tiene acceso a manage_options. Luego verificamos que recibimos el token que generamos en el formulario, esto se hace para validar que fuimos nosotros los que llenamos el formulario y no estamos haciendo clic sobre algún enlace que recibimos por correo.

Después recuperamos el valor del código de GA de la variable POST de PHP y usamos la función de WP update_option para guardarlo en la base de datos.

Finalmente, redirigimos al usuario de nuevo a la página de ajustes que creamos. En la función wp_redirect solo debes cambiar cn-conf-ga por el slug que usaste al inicio cuando registrarte la opción en el menú de ajustes.

Conclusiones

Con esto ya tienes la base para crear una página de ajustes en tu plugin, pero en un ambiente de producción necesitas ingresar más código para validaciones, por ejemplo, que un valor no este vacío o que este dentro de un rango, etc.

Aquí está el código completo, por si tienes algún problema.

<?php
/*
Plugin Name: Plugin con parametros
Plugin URI: https://www.codigonaranja.com
Description: Pantalla de parametros
Version: 1.0
Author: Luis Cruz
Author URI: https://www.codigonaranja.com
License: GPLv2
*/
# Agregar informacion predeterminada al activar el plugin
//Este Script se correra en 3 momentos: Al activar por primera vez, al actualizar, al reactivar
register_activation_hook( __FILE__, 'cn_set_default_options' );
function cn_set_default_options() {
    // Revisar si ya se habia activado antes
    if ( get_option( 'cn_ga_cuenta' ) === false ) {
        add_option( 'cn_ga_cuenta', 'UA-0000000-0' );
    }
}
#Agregar esta condiguracion al menu
function cn_menu_ajustes() {
    add_options_page( 'Configuracion Google Analytics', //Titulo de la pagina
                      'Codigo de Google Analytics', //Nombre del menu
                      'manage_options', //Nivel de acceso, solo usuarios
                      'cn-conf-ga', // slug
                      'cn_genera_pagina' ); //Funcion que procesara todo
}
add_action( 'admin_menu', 'cn_menu_ajustes' );
//Generar el codigo de la pagina de actualización
function cn_genera_pagina() {
    // Conseguir el valor de GA
    $codigo_ga = get_option( 'cn_ga_cuenta' ) ;
    ?>
    <div class="wrap">
    <h2>Google Analytic</h2>
    <form method="post" action="admin-post.php">
      <input type="hidden" name="action"  value="guardar_ga" />
      <!-- mejorar la seguridad -->
      <?php wp_nonce_field('token_ga'); ?>
      Código de Google Analytic:
      <input type="text" name="codigo_ga"
          value="<?php echo esc_html($codigo_ga);
          ?>"/>
       <br />
      <input type="submit" value="Guardar" class="button-primary"/>
    </form>
    </div>
<?php
}
add_action( 'admin_post_guardar_ga', 'cn_guardar_ga' );
function cn_guardar_ga() {
    // Revisar el permiso de autorización
    if ( !current_user_can( 'manage_options' ) ) {
        wp_die( 'Not allowed' );
    }
    // Revisar el token que creamos antes
    check_admin_referer( 'token_ga' );
    //Limpiar valor, para prevenir problemas de seguridad
    $codigo_ga = sanitize_text_field( $_POST['codigo_ga'] );
    // Guardar en la base de datos
    update_option( 'cn_ga_cuenta', $codigo_ga );
    // Regresamos a la pagina de ajustes
    wp_redirect( add_query_arg( 'page',
                                'cn-conf-ga',
                            admin_url( 'options-general.php' ) ) );
    exit;
}

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *