No hay necesidad de preguntar por qué alguien querría escribir un plugin para WordPress. Es una de las principales características que hace que WordPress sea tan flexible y una buena opción para una amplia gama de proyectos. En la primera parte de nuestra serie creamos la base para un plugin de WordPress reconocible por el núcleo. Entonces, en la segunda parte aprendimos cómo alterar la funcionalidad predeterminada del núcleo. Hoy vamos a ver las opciones de complementos. Esta es una de las tareas más comunes que los complementos deben realizar.

Comúnmente necesitará crear un conjunto de parámetros (opciones) y le dará al usuario la capacidad de asignarles valores apropiados. Los valores se almacenan en la base de datos y se pueden recuperar a pedido. El complemento normalmente realizará diferentes acciones basadas en estos valores, produciendo diferentes resultados, por ejemplo.

¿Qué herramientas nos da WordPress para hacer posible este escenario? Nos permite registrar opciones con el sistema y recuperarlas por ID asignado - La API de Opciones es responsable de eso. WordPress también proporciona una API de configuración para crear una GUI de administrador para los diálogos de opciones. Además de eso, nos permite agregar elementos personalizados en el menú de administración para que el complemento pueda tener su propia página de configuración. Finalmente, WordPress se ocupa de la seguridad de los complementos y proporciona un conjunto de capacidades y métodos de limpieza para manejar la entrada del usuario de forma segura.

Echemos un vistazo detallado a cada parte.

API de opciones

los API de opciones es una forma estandarizada de almacenar datos personalizados en la base de datos. Todos los datos se guardan en la tabla wp_options bajo un nombre personalizado determinado y se puede acceder desde cualquier parte del código. Las funciones más importantes de la API son:

La función get_option simplemente extrae de la base de datos cualquier información almacenada con un nombre dado y la devuelve. La función update_option toma un nombre de opción y su valor y actualiza la entrada correspondiente en la base de datos. Si no hay tal entrada, se creará automáticamente. Ambas funciones pueden operar con arreglos y valores individuales. Eso significa que puede almacenar datos de matriz bajo un solo nombre en la base de datos y la API manejará las acciones de serialización y mineralización para usted. Esa es una práctica recomendada para complementos: almacene todas las opciones de plugins como una matriz bajo un solo nombre.

Página de opciones de complementos

Puede crear una página de configuración o un grupo de páginas para su complemento en el menú de administración. Si está creando un grupo de páginas, primero debe agregar una página de nivel superior:

Los valores de los parámetros son autoexplicativos, pero puede consultar el fuente para detalles. Ahora tiene que agregar páginas internas una por una de la siguiente manera:

Como parámetro $ parent_slug, debe usar el ID de la página de nivel superior; en el caso de una página de nivel superior personalizada, es el valor que proporcionó como $ menu_slug al registrarse. Si no necesita varias páginas, puede crear una única página de configuración debajo de una de las secciones existentes de nivel superior, comúnmente en "Configuración" (options-general.php debe usarse como $ parent_slug). Alternativamente, hay funciones de acceso directo para agregar subpáginas bajo ciertos elementos del menú de administración, en el caso de "Configuración" es add_options_page () .

Configuración API

los Configuración API le permite crear una interfaz para administrar la configuración del complemento; marque una página como página de configuración (para procesar la entrada automáticamente) y las secciones de salida en esa página y los campos dentro de cada sección para aceptar la entrada del usuario. Para lograr eso, su primer objetivo es registrar las configuraciones con el sistema y crear una estructura de campos de sección para ellas:

Referirse a Códice para una descripción detallada de los parámetros, pero la lógica es bastante simple: en primer lugar, registramos nuestro nombre de opciones (si hay muchas opciones, podrían organizarse en grupos); luego registramos sección (es) con una ID interna y un conjunto de campos para cada sección; la API nos da la capacidad de especificar devoluciones de llamadas personalizadas para validación de entrada y para mostrar cada campo y sección.

Después de registrar nuestras opciones y los campos correspondientes, debemos mostrarlos en la página de configuración; se deben llamar las siguientes funciones dentro del

etiqueta:

La función settings_fields se ocupa de los campos ocultos obligatorios para que el mecanismo de opciones nativas de WordPress funcione. Do_settings_sections en realidad saca campos y secciones previamente registradas.

Consideraciones de Seguridad

La regla de seguridad fundamental cuando se trata de opciones es muy simple: limpiar la entrada, escapar de la salida y cuidar de las capacidades. En otras palabras, si acepta la entrada de un usuario, debe verificar que su formato sea correcto y no incluya contenido malicioso (eso es validación), luego de eso puede pasar los datos para su posterior procesamiento. Al mostrar los datos extraídos de la base de datos, debe escaparse para generar caracteres especiales (especialmente HTML) correctamente. Para ambas tareas, WordPress proporciona funciones nativas que se pueden usar en diferentes contextos (lea más sobre el tema aquí )

Otro punto de preocupación son los permisos de los usuarios. WordPress tiene un mecanismo incorporado que controla los roles y capacidades de los usuarios que bloquea el acceso a ciertas áreas administrativas para los usuarios con permisos insuficientes. Solo los administradores están permitidos en todas partes. Al crear páginas de opciones, debe asignarles las capacidades correctas (normalmente es "opciones de administración") y no permite que los usuarios con privilegios bajos accedan a la página (para obtener más información sobre las funciones y capacidades de WordPress, consulte el Códice )

Ponlo todo en el trabajo

Veamos todo el escenario en acción.

Seguiremos desarrollando nuestro ejemplo de "Hola mundo" (iniciado en las partes anteriores de la serie) que muestra la información del autor invitado en una publicación con la ayuda de una taxonomía personalizada.

El marcado del bloque del autor estaba previamente codificado en el plugin. Ahora vamos a darle al usuario la capacidad de especificar una plantilla para ese marcado utilizando marcadores de posición para datos específicos del autor (nombre, url y descripción). Nuestro plugin ya tiene dos archivos PHP incluidos: core.php (que contiene el código principal) y admin.php (que contiene el código relacionado con el administrador).

¿Qué cambios necesitamos hacer?

1. Crea una página de opciones de complemento (en admin.php)

/* register menu item */function msp_helloworld_admin_menu_setup(){add_submenu_page('options-general.php','Helloworld Settings','Helloworld','manage_options','msp_helloworld','msp_helloworld_admin_page_screen');}add_action('admin_menu', 'msp_helloworld_admin_menu_setup'); //menu setup/* display page content */function msp_helloworld_admin_page_screen() {global $submenu;// access page settings$page_data = array();foreach($submenu['options-general.php'] as $i => $menu_item) {if($submenu['options-general.php'][$i][2] == 'msp_helloworld')$page_data = $submenu['options-general.php'][$i];}// output?>

'; return $ actions;} add_filter (' plugin_action_links ',' msp_helloworld_settings_link ', 2, 2);

En este fragmento, msp_helloworld_admin_menu_setup crea una subpágina en el menú 'Configuración' (debe ejecutarse en el gancho de acción 'admin_menu' para que funcione correctamente). A continuación, damos salida al formulario de configuración con msp_helloworld_admin_page_screen. Utiliza las funciones de la API de configuración para los campos y las funciones preconfiguradas de WordPress para otros elementos de la interfaz (como el botón Enviar). Tenga en cuenta el atributo de acción de la

etiqueta: debe apuntar a 'options.php' para procesar las opciones correctamente. Finalmente, el filtro msp_helloworld_settings_link crea un enlace de acceso directo a la página de opciones en la pantalla de administración del complemento.

2. Registre las opciones de complementos con el sistema y cree campos y reglas para ellos

/* register settings */function msp_helloworld_settings_init(){register_setting('msp_helloworld_options','msp_helloworld_options','msp_helloworld_options_validate');add_settings_section('msp_helloworld_authorbox','Author's box','msp_helloworld_authorbox_desc','msp_helloworld');add_settings_field('msp_helloworld_authorbox_template','Template','msp_helloworld_authorbox_field','msp_helloworld','msp_helloworld_authorbox');}add_action('admin_init', 'msp_helloworld_settings_init');/* validate input */function msp_helloworld_options_validate($input){global $allowedposttags, $allowedrichhtml;if(isset($input['authorbox_template']))$input['authorbox_template'] = wp_kses_post($input['authorbox_template']);return $input;}/* description text */function msp_helloworld_authorbox_desc(){echo "

Enter the template markup for author box using placeholders: [gauthor_name], [gauthor_url], [gauthor_desc] for name, URL and description of author correspondingly.

";}/* filed output */function msp_helloworld_authorbox_field() {$options = get_option('msp_helloworld_options');$authorbox = (isset($options['authorbox_template'])) ? $options['authorbox_template'] : '';$authorbox = esc_textarea($authorbox); //sanitise output?>

Debo señalar que todas las opciones de complementos se deben almacenar como una matriz. A pesar de que solo tenemos una opción (authorbox_template), la incluimos en una matriz y el campo correspondiente en la sección para fines de demostración. La función de registro msp_helloworld_settings_init debe ejecutarse en el gancho 'admin_init'. La función msp_helloworld_options_validate se encarga de la entrada del usuario limpiándolo con el wp_kses_post filtro que se basa en la biblioteca KSES. La función msp_helloworld_authorbox_desc crea una descripción para la sección del formulario y msp_helloworld_authorbox_field genera un área de texto para manejar el marcado ingresado. Tenga en cuenta que le asignamos a las clases de CSS "código de texto grande" para que se aplique el estilo de administración incorporado.

Todo esto produce la siguiente pantalla en el panel de administración de WordPress.

3. Modifique la función que genera el cuadro del autor (en core.php)

Hacemos esto para que obtenga la plantilla de la base de datos y reemplace los datos de marcadores de posición ([gauthor_name], [gauthor_url], [gauthor_desc]) con los valores correspondientes.

/* Create author's box markup */function msp_helloworld_author_block(){global $post;$author_terms = wp_get_object_terms($post->ID, 'gauthor');if(empty($author_terms))return;$name = stripslashes($author_terms[0]->name);$url = esc_url(get_term_link($author_terms[0]));$desc = wp_filter_post_kses($author_terms[0]->description);//get template from option$options = get_option('msp_helloworld_options');$out = (isset($options['authorbox_template'])) ? $options['authorbox_template'] : '';$out = str_replace(array('[gauthor_url]', '[gauthor_name]', '[gauthor_desc]'),array($url, $name, $desc),$out);return $out;}

Finalmente, nuestro plugin (después de aplicar algunos estilos) produce un buen cuadro de autor invitado debajo del contenido del post.

Conclusión

Almacenar y acceder a los datos de opciones es una tarea muy común, que muchos complementos necesitan realizar. A través del mecanismo de opciones, puede proporcionar a sus usuarios la posibilidad de ajustar el complemento a sus necesidades (que seguramente apreciarán). Incluso desarrollándose usted mismo puede necesitar una forma de almacenar detalles de una instalación en particular. Confiar en las API y funciones nativas de WordPress para resolver tales tareas es una buena manera de crear código fácil de mantener, seguro y seguro para el futuro.

¿Qué tipo de complementos le gustaría ver disponibles para WordPress? ¿Has construido el tuyo usando esta serie? Háganos saber en los comentarios a continuación.

Usos de imágenes destacadas imagen del módulo a través de Shutterstock