Settings API

Ya vimos cómo se maneja la Options API para guardar la configuración de nuestro plugin, y recomendamos usar una única opción para guardar todos nuestros datos, construyendo un array. También vimos que para guardar nuestra configuración tenemos que hacer una serie de chequeos de seguridad que pueden llegar a ser tediosos, o pueden volver nuestras funciones muy largas y complicadas de mantener.

Todos estos problemas se pueden resolver usando la Settings API. Lo que nos permite esta API es sacarnos de encima gran parte de los procesos de seguridad y validación que necesitamos para guardar nuestros datos, y en consecuencia vuelve nuestro código más estable, más sencillo de mantener, y más extensible.

Una diferencia que vamos a tener con respecto a lo visto anteriormente es que no vamos a imprimir de manera directa el HTML que genera nuestros campos. En cambio, nuestros campos tienen que ser registrados en la Settings API, y asignados a una sección.

<?php
add_action( 'admin_init', 'portfolio_settings_api_init' );

function portfolio_settings_api_init() {
     // Registramos una sección para nuestro campo.
     add_settings_section(
        'portfolio-general-settings-section',          // Texto del tag `id` de la sección.
        __( 'General Settings', 'portfolio' ),         // Título de la sección.
        'portfolio_general_settings_section_callback', // Nombre de la función que imprime el HTML de la sección.
        'portfolio-settings'                           // Slug del menú donde debe aparecer la sección.
    );

     // Registramos un campo asociado a la sección.
     add_settings_field(
        'portfolio-settings-show-logged-only-setting',              // Texto del tag `id` del campo.
        __( 'Only show projects to logged-in users', 'portfolio' ), // Título del campo.
        'portfolio_settings_show_logged_only_callback',             // Nombre de la función que imprime el HTML del campo.
        'portfolio-settings',                                       // Slug del menú donde debe aparecer el campo.
        'portfolio-general-settings-section'                        // ID de la sección a la que pertenece el campo.
    );

    // Registramos nuestro campo como setting.
    // El primer parámetro es el nombre de la opción que estamos usando para guardar la configuración.
    // El segundo parámetro es el identificador de nuestra setting dentro del array de opciones.
    // El tercer parámetro es el nombre de la función que va a sanitizar los datos de la opción.
    // Esta función se ocupa de validar nuestros datos por medio de nonces.
     register_setting( 'portfolio_settings', 'show_logged_only', 'portfolio_sanitize_show_logged_only' );
}

// Callback para la sección.
function portfolio_general_settings_section_callback() {
    _e( 'Configure the general plugin settings here' );
}

// Callback para el campo. Solamente imprimimos el input y su label, no el tag form ni el botón de confirmación.
function portfolio_settings_show_logged_only_callback() {
    $settings  = get_option( 'portfolio_settings' );
    $checked = isset( $settings['show_logged_only'] ) ? $settings['show_logged_only'] : false;

    ?>
        <input id="portfolio-settings-show-logged-only" name="portfolio_settings[show_logged_only]" type="checkbox" value="true" <?php checked( $checked ); ?>/> 
        <label for="portfolio-settings-show-logged-only"><?php _e( 'Only show projects to logged-in users', 'portfolio' ); ?></label>
    <?php
}

// Función de sanitización para nuestro campo.
function portfolio_sanitize_show_logged_only( $data ) {
    // Chequeamos si el valor ingresado está permitido. Si lo está, mostramos proyectos solo a usuarios registrados.
    $accepted_values = array( true, 'true' );
    $show_logged_only = in_array( $data, $accepted_values );

    return $show_logged_only;
}

Con este código ya podemos guardar nuestros datos automáticamente, sin necesidad de interactuar de manera directa con la Options API ni de chequear nonces. Sin embargo, todavía no podemos usarlo, porque lo que hicimos aún no se ve reflejado en la página de administración. Para eso necesitamos modificar nuestra función portfolio_menu_page() de la siguiente manera:

<?php
function portfolio_menu_page() {
    ?>
        <form action="options.php" method="POST">
            <?php settings_fields( 'portfolio_settings' ); // Imprime el HTML necesario para las validaciones. ?>
            <?php do_settings_sections( 'portfolio-general-settings-section' ); // Imprime nuestra sección y los campos asociados. ?>
            <?php submit_button(); // Imprime el botón de confirmación. ?>
        </form>
    <?php
}

Una vez que actualizamos a este código, pasan varias cosas: nuestra antigua función de guardado, portfolio_save_settings() ya no se usa más, ya que todas las validaciones son hechas por la Settings API. Por lo tanto, podemos eliminar nuestra vieja función. También contamos con más funciones que antes, pero más chicas y más fáciles de mantener. Además, la sanitización de datos está desacoplada del proceso de guardado. Como toda la registración de secciones y de campos es manejada internamente por WordPress, con mirar un poco la documentación oficial de la API y sus otras funciones podemos ver que es muy fácil mostrar o no mostrar nuevas opciones condicionalmente, según el contexto en el que estemos, qué usuario está viendo la página, en qué menú estamos, etc. Es una mejora sustancial sobre el método anterior, con el que las cosas no se podían hacer de manera tan automática.