Plugins (X) Creando la página de opciones para un menú superior

WordPress dispone de una API de ajustes que por medio de un conjunto de funciones puede guardar opciones de forma segura y sencilla, controlando las comprobaciones de seguridad y no es necesario introducir el once en el formulario la página de opciones.

Para este método hay que recordar lo que vimos ya en la entrada sobre como crear un menú de nivel superior, en la que vimos que al utilizar las funciones add_menu_page() y add_submenu_page() definimos el nombre de la función de elemento de menú que mostrar en la página de opciones. De modo que nuestro objetivo será crear esa función para mostrar sus opciones, por medio de una serie de pasos…

En primer lugar debemos de establecer el menú del plugin tal y como vimos:

//preparamos la accion para que cargue la función  de crar menú
add_action ('admin_menu', 'prowp_crear_menu');
//hacemos la función que cargará el menú
function prowp_crear_menu(){
  //creamos el menú de nivel superior
  add_menu_page('Plugin de muestra', 'Pluginde muestra', 'manage_options', 'prowp_main_menu', 'prowp_settings_page', plugins_url('/images/icono.png', __FILE__));
  //llamada a la funcion que registra los cambios...
  add_action( 'admin_init', 'prowp_register_settings' );
}

Lo único que hemos cambiado ha sido añadir un nuevo conector en la línea 8 para admin_init y ejecutar la función prowp_register_settings() que se añade en el siguiente código:

function prowp_register_settings() {
    //registra los cambios
    register_setting( 'prowp-settings-group', 'prowp_options', 'prowp_sanitize_options' );
  
}

En esta función se define la opción que vamos a ofrecer en la página de opciones del plugin, y aunque la página tendrá tres opciones, se van a almacenar en una matriz y registrar de este modo un único ajuste.

Estudiando la función register_settings() vemos que tiene tres parámetros:

  • El primero es el nombre del grupo de opciones, es obligatorio y debe de ser un nombre de grupo para identificar todas las opciones.
  • es el nombre exclusivo de la opción
  • Es una función de retrollamada para sanear los valores de las opciones.

Una vez que tenemos registradas las opciones debemos de generar la página de opciones:

function prowp_settings_page() {
?>
<div class="wrap">
<h2>Plugin Options</h2>
<form method="post" action="options.php">
    <?php settings_fields( 'prowp-settings-group' ); ?>
    <?php $prowp_options = get_option( 'prowp_options' ); ?>
<table class="form-table">
<tr valign="top">
<th scope="row">Nombre</th>
<td><input type="text" name="prowp_options[option_name]" value="<?php echo esc_attr( $prowp_options['option_name'] ); ?>" /></td>
      </tr>
<tr valign="top">
<th scope="row">Email</th>
<td><input type="text" name="prowp_options[option_email]" value="<?php echo esc_attr( $prowp_options['option_email'] ); ?>" /></td>
      </tr>
<tr valign="top">
<th scope="row">URL</th>
<td><input type="text" name="prowp_options[option_url]" value="<?php echo esc_url( $prowp_options['option_url'] ); ?>" /></td>
      </tr>
    </table>
    <span class="submit">
      <input type="submit" class="button-primary" value="Save Changes" />
    </span>
  </form>
  </div>
<?php 
}

Básicamente se trata de un formulario normal aunque tenemos que cumplir algunas normas adicionales:

  • En la etiqueta form debemos de establecer el method como post y el action como options.php
  • Se debe de definir el grupo de ajustes que se estableció anteriormente, en nuestro caso prowp-settings-group, definiendo el vinculo entre las opciones y sus valores. (Como vemos en la línea 6)
  • A continuación se carga la matriz de opciones en la variable $prowp_options mediante la función get_option(), que se utiliza para mostrar las opciones existentes definidas en el formulario.
  • Tras esto se crea una tabla para mostrar las opciones del formulario, que también puede diseñarse por medios de divs, articulos… Pero hay que recordar que el campo del formulario debe de tener el formato nombre_opción[nombre_campo]. (Líneas 10, 16 y 21)
  • Tras esto creamos el botón de envío.

Una vez que tenemos todo esto desarrollado todo esto, solo nos falta crear la función prowp_sanitize_options(), llamada en prowp_register_settings() desde register_settings(), que permite sanear los datos remitidos en los ajustes del plugin antes de guardarlos en la BBDD. Esto es un paso fundamental, ya que nos permite sanear los datos que podrían suponer un problema para la seguridad en el plugin.

function prowp_sanitize_options( $input ) {
    $input['option_name'] = sanitize_text_field( $input['option_name'] );
    $input['option_email'] = sanitize_email( $input['option_email'] );
    $input['option_url'] = esc_url( $input['option_url'] );
    return $input;
}

Los valores de las opciones se sanean por medio de una función especifica según el caso, por ejemplo sanitize_text_field() elimina las etiquetas HTML, XML y PHP del valor remitido.

Con todo esto el plugin ya guarda las opciones que luego utilizaremos para su funcionamiento.

Resumiendolo en la siguiente imagen, podemos ver como se declaran las funciones en el desarrollo y como se despliegan en la producción, para poder entenderlo mejor

página de opciones

Finalmente y a modo de extra, presento el código completo para el desarrollo de la página de configuración de nivel superior:

//preparamos la accion para que cargue la función  de crar menú
add_action ('admin_menu', 'prowp_crear_menu');
//hacemos la función que cargará el menú
function prowp_crear_menu(){
  //creamos el menú de nivel superior
  add_menu_page('Plugin de muestra', 'Pluginde muestra', 'manage_options', 'prowp_main_menu', 'prowp_settings_page', plugins_url('/images/icono.png', __FILE__));
  //llamada a la funcion que registra los cambios...
  add_action( 'admin_init', 'prowp_register_settings' );
}


function prowp_register_settings() {
    //registra los cambios
    register_setting( 'prowp-settings-group', 'prowp_options', 'prowp_sanitize_options' );
  
}

function prowp_sanitize_options( $input ) {

    $input['option_name'] = sanitize_text_field( $input['option_name'] );
    $input['option_email'] = sanitize_email( $input['option_email'] );
    $input['option_url'] = esc_url( $input['option_url'] );

    return $input;

}


function prowp_settings_page() {
?>
<div class="wrap">
<h2>Plugin Options</h2>
<form method="post" action="options.php">
    <?php settings_fields( 'prowp-settings-group' ); ?>
    <?php $prowp_options = get_option( 'prowp_options' ); ?>
<table class="form-table">
<tr valign="top">
<th scope="row">Nombre</th>
<td><input type="text" name="prowp_options[option_name]" value="<?php echo esc_attr( $prowp_options['option_name'] ); ?>" /></td>
      </tr>
<tr valign="top">
<th scope="row">Email</th>
<td><input type="text" name="prowp_options[option_email]" value="<?php echo esc_attr( $prowp_options['option_email'] ); ?>" /></td>
      </tr>
<tr valign="top">
<th scope="row">URL</th>
<td><input type="text" name="prowp_options[option_url]" value="<?php echo esc_url( $prowp_options['option_url'] ); ?>" /></td>
      </tr>
    </table>
   <span class="submit">
      <input type="submit" class="button-primary" value="Save Changes" />
    </span>
  </form>
  </div>
<?php 
}