Options API

Ya vimos cómo crear una página de administración para nuestro plugin, pero todavía no podemos guardar opciones a través de esa página. Para poder gestionar nuestras opciones, WordPress nos ofrece la Options API, un conjunto de funciones muy sencillas para manipular configuraciones internamente en nuestros plugins.

Para poder ingresar información desde nuestra página de opciones, primero tenemos que ofrecer algún campo con el que el usuario quiera interactuar. Por el momento vamos a agregar una única opción: la de mostrar proyectos solo a usuarios registrados. Para eso, vamos a retomar la función que usamos para mostrar la página de administración:

<?php
function portfolio_menu_page() {
    $settings = get_option( 'portfolio_settings' );
    $checked  = isset( $settings['show_logged_only'] ) ? $settings['show_logged_only'] : false;

    wp_nonce_field( '_portfolio_settings', '_portfolio_settings_nonce' );

    ?>
        <form method="post">
            <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>

            <input type="submit" class="button button-save" value="<?php _e( 'Save options', 'portfolio' ); ?>" />
        </form>
    <?php
}

Al actualizar la página vamos a ver aparecer la opción. Nótese como, en las dos primeras líneas de esta función, chequeamos si nuestro plugin guardó datos previamente, y a partir de eso decidimos si el checkbox tiene que mostrarse marcado. También creamos el nonce que nos va a permitir validar los datos cuando se envíen.

Ahora continuación necesitamos crear el proceso para guardar esos datos. Esto es muy parecido a lo que hacíamos con las meta boxes.

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

function portfolio_save_settings() {
    // Si no se aprueba el chequeo de seguridad, salir de la función.
    if ( ! isset( $_POST['_portfolio_settings_nonce'] ) || ! wp_verify_nonce( $_POST['_portfolio_settings_nonce'], '_portfolio_settings' ) ) {
        return;
    }

    // Si el usuario actual no tiene permisos para actualizar la configuración, salir de la función.
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }

    // Chequeamos si el dato se envió para decidir si mostramos los proyectos a todos los usuarios o no.
    if ( isset( $_POST['portfolio_settings']['show_logged_only'] ) ) {
        // Si el valor se envió, chequeamos si tiene un valor permitido. Si lo tiene, mostramos proyectos solo a usuarios registrados.
        $accepted_values = array( true, 'true' );
        $show_logged_only = in_array( $_POST['portfolio_settings']['show_logged_only'], $accepted_values );
    } else {
        // Si el valor no se envió, mostramos proyectos a todos los usuarios.
        $show_logged_only = false;
    }

    // Creamos un flag para evaluar si ya tenemos la configuración guardada en la base de datos.
    $settings_empty = false;

    // Obtenemos la configuración del plugin, si existe.
    $settings = get_option( 'portfolio_settings' );

    // Si no hay una configuración previa guardada en la base de datos, lo indicamos, y creamos un array vacío para contenerla.
    if ( empty( $settings ) ) {
        $settings_empty = true;
        $settings = array();
    }

    // Si el valor de la configuración que estamos modificando no existe o es diferente al que evaluamos, lo cambiamos por el nuevo valor.
    if ( ! isset( $settings['show_logged_only'] ) || $settings['show_logged_only'] != $show_logged_only ) {
        $settings['show_logged_only'] = $show_logged_only;
    }

    if ( $settings_empty ) {
        // Si la configuración está vacía, la creamos.
        add_option( 'portfolio_settings', $settings );
    } else {
        // Si la configuración no está vacía, la actualizamos.
        update_option( 'portfolio_settings', $settings );
    }
}

Con estos chequeos y el uso de add_option() y update_option() podemos crear y modificar la configuración de nuestro plugin. Es importante tener en cuenta que cada opción manejada por estas funciones genera una nueva entrada en la base de datos, y si para cada configuración que necesitemos en nuestro plugin creamos una entrada nueva, estamos complejizando la base de datos. Esto, a la larga, puede llevar a problemas de rendimiento para sitios web con bases de datos grandes. Por eso lo que hacemos es usar una sola opción para guardar nuestra configuración, e incluir todos los datos que necesitamos dentro de un array.

Ahora bien, necesitamos ver cómo reflejar en el front-end estos cambios que introdujimos. Para eso vamos a volver a asignar una función a the_content, como en los ejemplos anteriores, pero en vez agregarle cosas al contenido, lo vamos a modificar por completo en caso de que el usuario no esté logueado, y que solo queramos mostrar proyectos a usuarios registrados. Para eso vamos a usar una prioridad con un número alto, y así asegurarnos de que la función se ejecute lo más tarde posible.

<?php
add_filter( 'the_content', 'portfolio_project_show_logged_in_only', 999 );

function portfolio_project_show_logged_in_only( $content ) {
    $settings = get_option( 'portfolio_settings' );

    // Si se elige mostrar solo a usuarios registrados y el usuario actual no está logueado, reemplazamos el contenido por un mensaje.
    if ( ! empty( $settings['show_logged_in_only'] ) && ! is_user_logged_in() ) {
        $content = __( 'You don\'t have permissions to view this content.', 'portfolio' );
    }

    return $content;
}

De todas maneras, si bien la Options API es la herramienta que WordPress usa internamente y recomienda para manejar configuraciones propias, a la hora de manejar el guardado de datos y generación de campos en menús de administración, no es la mejor solución que tenemos a nuestro alcance, ya que tiene una gran cantidad de limitaciones. Es importante entender cómo funciona y cuáles son sus funciones principales, porque en desarrollo de plugins es casi inevitable usarla, pero para lo que acabamos de hacer, la mejor solución que nos ofrece WordPress es la Settings API, que es el tema del próximo capítulo.