Kitabı oxu: «El gran libro de desarrollo de plugins WordPress»

Funciones y condicionales básicos de un plugin
¿Qué es un plugin?

Los plugins o complementos son paquetes de código que amplían la funcionalidad principal de WordPress. Los plugins de WordPress están formados por código PHP y otros activos como imágenes, CSS y JavaScript.

Al crear su propio complemento, está ampliando WordPress, es decir, creando funcionalidades adicionales además de lo que WordPress ya ofrece. Por ejemplo, podría escribir un complemento que muestre enlaces a las diez publicaciones más recientes en su sitio.

O, utilizando los tipos de publicaciones personalizadas de WordPress, puede escribir un complemento que cree un sistema de tiques de soporte con todas las funciones con notificaciones por correo electrónico, estados de tiques personalizados y un portal orientado al cliente. ¡Las posibilidades son infinitas!

La mayoría de los plugins o complementos de WordPress están compuestos por muchos archivos, pero un plugin realmente solo necesita un archivo principal con un DocBlock formateado específicamente en el encabezado.

Un DocBlock es un fragmento de código PHP comentado dentro de nuestro archivo php.

Requisitos de cabecera, título y descripción del plugin

El archivo PHP principal del plugin debe incluir un comentario de encabezado que le dice a WordPress que un archivo es un complemento, y proporciona información sobre este.

Como mínimo, un comentario de encabezado debe contener el nombre del complemento:

Campos de encabezado disponibles

Plugin Name: (obligatorio) el nombre de su complemento, que se mostrará en la lista de complementos en el administrador de WordPress.

Plugin URI: la página de inicio del complemento, que debe ser una url única, preferiblemente en su propio sitio web. Esto debe ser exclusivo de su complemento. No puede usar una url de WordPress.org aquí.

Description: una breve descripción del complemento, como se muestra en la sección Complementos en el Administrador de WordPress. Mantenga esta descripción a menos de 140 caracteres.

Version: el número de versión actual del complemento, como 1.0 o 1.0.3.

Requires at least: la versión más baja de WordPress en la que funciónará el complemento.

Requires PHP: la versión mínima requerida de PHP.

Author: el nombre del autor del complemento. Se pueden enumerar varios autores utilizando comas.

Author URI: el sitio web o el perfil del autor en otro sitio web, como WordPress.org.

License: el nombre corto (slug) de la licencia del complemento (por ejemplo, GPLv2). Puede encontrar más información sobre licencias en las pautas de WordPress.org.

License URI: un enlace al texto completo de la licencia (p. Ej. Https://www.gnu.org/licenses/gpl-2.0.html).

Text Domain: el dominio de texto gettext del complemento. Puede encontrar más información en la sección Dominio de texto de la página Cómo internacionalizar su complemento.

Domain Path: la ruta del dominio le permite a WordPress saber dónde encontrar las traducciones. Puede encontrar más información en la sección Ruta del dominio de la página Cómo internacionalizar su complemento.

Network: si el complemento solo se puede activar en toda la red. Solo se puede establecer en verdadero y se debe omitir cuando no sea necesario.

Ganchos de activación y desactivación

Creamos nuestro plugin de prueba, al que llamaremos pruebas. Vamos a nuestra carpeta wp-content -> plugins -> y aquí dentro de plugins crearemos una carpeta o directorio res_pruebas. Le pondremos un prefijo (res_), de restaurante.

Podemos ver resaltado res_pruebas, dentro crearemos un archivo PHP y lo nombraremos res-pruebas.php.

Vamos a nuestro editor Visual Studio Code y escribimos la cabecera.

Ahora escribiremos las funciones:

Es muy común que en el desactivador se utilice una función para limpiar enlaces permanentes, la función es:

flush_rewrite_rules

Elimine las reglas de reescritura y luego vuelva a crear las reglas de reescritura.

Parámetros

• $hard

(bool) (Opcional) Ya sea para actualizar .htaccess (hard flush) o simplemente actualizar rewrite_rules transient (soft flush). El valor predeterminado es verdadero (duro). Valor predeterminado: verdadero.

Esta función es útil cuando se usa con tipos de publicaciones personalizadas, ya que permite el vaciado automático de las reglas de reescritura de WordPress (por lo general, debe hacerse manualmente para los nuevos tipos de publicaciones personalizadas). Sin embargo, esta es una operación costosa, por lo que solo debe usarse cuando sea necesario.

Al desactivar el plugin, se ejecutará esa función y, al activarlo, llamará al archivo activador.php. Si activamos el plugin, nos dará un error, pues no tenemos este archivo.

Vamos a nuestro panel de administrador de WordPress, vamos a plugins y buscamos el plugin pruebas.

Activaremos el plugin y veremos el error.

Ahora, para comprobar que nuestro plugin funciona, vamos a nuestro archivo res-pruebas.php y comentamos la línea donde requerimos el archivo activador.php. Al desinstalar y volver a instalar, veremos que no aparece ningún error.

Ahora crearemos el archivo activador.php y escribiremos lo siguiente:

Con este código estaremos creando una tabla en nuestra base de datos a la que llamaremos mitabla. Esta tabla se creará en el mismo instante en que hagamos clic en Activar nuestro plugin.

Métodos de desinstalación

Los métodos de desinstalación de plugins en WordPress se ejecutan cuando hacemos clic en la opción de borrar un plugin en WordPress.

El primer método requiere que en nuestro archivo principal del plugin escribamos una función.

Con esta función podemos borrar tablas, configuraciones y otras opciones.

El segundo método requiere crear un archivo en la raíz de nuestro plugin, este archivo debe llamarse uninstall.php. Creamos el archivo y escribimos el siguiente código:

Este primer código es de seguridad y dice que, si no está definida esa constante, no siga ejecutando el código que vamos a escribir más abajo.

Ahora vamos a crear una consulta sql para eliminar la tabla que hemos creado anteriormente.

Después de escribir este código, guardamos los cambios.

Ahora vamos a comprobar que esto funciona y, para ello, vamos primero a crear una copia de nuestro plugin res_pruebas comprimiéndolo en un archivo .zip con winrar.

Después de crear el archivo res_pruebas.zip, volvemos a nuestro panel de administración, recargamos la página y desinstalamos el plugin res_pruebas. Ahora hacemos clic en Borrar.

Veremos que nos saldrá una ventana de confirmación y hacemos clic en Aceptar. Ahora, al volver a nuestra base de datos y recargar, podemos ver que la tabla atr_mitabla ha desaparecido.

Mejores prácticas para definir nuestras funciones o variables

Para que no se creen conflictos entre nuestras funciones, clases y variables de WordPress, debemos definirlas de la siguiente manera:

Comprobando que una variable no exista:

Comprobando que una función no exista:

Comprobando que una clase no exista:

Comprobando que una constante no está definida:

Mostrar información de nuestro plugin según el rol que tenga la persona, is_admin();. Determina si la solicitud actual es para una página de interfaz administrativa. Para ver más acerca de esta función, podemos visitar la web oficial de WordPress developers.

https://developer.wordpress.org/reference/functions/is_admin/

Comprobación de las capacidades de usuario

Las capacidades de usuario son las funciones que se pueden realizar dependiendo del rol que tenga la persona dentro de la web. Los roles que puede desempeñar una persona dentro de un proyecto web son:

• Super Admin

• Administrator

• Editor

• Author

• Contributor

• Subscriber

A continuación, mostraremos como ejemplo algunas de las funciones que se pueden realizar con el rol de Super Admin:

• create_sites

• delete_sites

• manage_network

• manage_sites

• manage_network_users

• manage_network_plugins

• manage_network_themes

• manage_network_options

• upload_plugins

• upload_themes

Son muchas más las funciones. Acto seguido, pondremos una tabla con las funciones y los roles que pueden desempeñar dichas funciones.

Para conceder el permiso a un usuario según su rol o mostrarle según qué funciones, podemos utilizar la siguiente función:

current_user_can( string $capability, mixed $args )

También podemos escribir un condicional para ejecutar alguna acción, por ejemplo:

Ahora crearemos un ejemplo, añadiremos una función donde aquel usuario con permisos para editar paginas podrá ver la modificación que añadiremos al head de nuestro WordPress:

Esta función nos puede dar un error Undefined function wp_get_current_user(). Este error se debe a que, durante el proceso de carga, WordPress carga primero todos los archivos y plugins, por último comprueba las capacidades de usuario, por eso nos marca el error de que no está definido.

Para solventar este error, debemos crear una función con el gancho de acción ‘plugins_loaded’; así quedaría el código.

Si vamos a nuestro frontend y comprobamos desde la consola nuestro head, veremos los cambios realizados.

Métodos de validación de datos

Existen varios métodos de validación de datos en WordPress. Entre los más utilizados podemos encontrar los siguientes:

• is_email()

• term_exists()

• username_exists()

• validate_file()

Pondremos un ejemplo de cómo validar un email:

Al aplicar este código de validación, obviamente me devolverá que es correcto, pues el mail cumple con los requisitos, que son:

• Nombre de usuario

• Servidor

• Sin olvidar el punto(.) y la arroba (@)

Si quitásemos el punto y dejáramos: prueba@pruebaeu, me devolvería Email incorrecto. Vamos al frontend en la página de inicio y nos fijamos en la parte superior, y veremos el mensaje Email incorrecto:

Otras funciones para la validación de datos pueden ser funciones de php como:

• isset() - empty()

• mb_strlen() - strlen()

• preg_match, strpos()

• count()

• in_array()

Pondremos un ejemplo de cómo utilizar in_array();

Esto me devolverá true, pues manzana está dentro del array.

Métodos de desinfección para la entrada de datos

Los métodos de sanitización de WordPress nos ayudan a eliminar caracteres extraños o maliciosos en nuestro envío y recepción de datos.

Para ello, utilizaremos las funciones de sanitización de WordPress, que son las siguientes:

• sanitize_email()

• sanitize_file_name()

• sanitize_html_class()

• sanitize_key()

• sanitize_meta()

• sanitize_mime_type()

• sanitize_option()

• sanitize_sql_orderby()

• sanitize_text_field()

• sanitize_title()

• sanitize_title_for_query()

• sanitize_title_with_dashes()

• sanitize_user()

• esc_url_raw()

• wp_filter_post_kses()

• wp_filter_nohtml_kses()

sanitize_email( $email )

Elimina todos los caracteres que no están permitidos en un correo electrónico.

sanitize_file_name( $filename )

Desinfecta un nombre de archivo, reemplazando espacios en blanco con guiones.

Descripción

Elimina caracteres especiales, que son ilegales en los nombres de archivo en ciertos sistemas operativos, y caracteres especiales, que requieren un escape especial para manipular en la línea de comando. Reemplaza espacios y guiones consecutivos con un solo guion. Recorta el período, el guion, y el subrayado, desde el principio y el final del nombre de archivo. No se garantiza que esta función devolverá un nombre de archivo que se puede cargar.

sanitize_html_class( $class, $fallback = ‘’ )

Desinfecta un nombre de clase HTML para garantizar que solo contenga caracteres válidos.

sanitize_key( $key )

Desinfecta una clave de cadena.

Descripción

Las claves se usan como identificadores internos. Se permiten caracteres alfanuméricos en minúscula, guiones y guiones bajos.

sanitize_meta ( $meta_key, $meta_value, $object_type, $object_subtype = ‘’ )

Desinfecta el metavalor.

Parámetros

• $meta_key

( cadena ) (Obligatorio) Clave de metadatos.

• $meta_value

( mixto ) (Requerido) Valor de metadatos para desinfectar.

• $object_type

( cadena ) (Obligatorio) El tipo de metadatos del objeto es para. Acepta ‘publicación’, ‘comentario’, ‘término’, ‘usuario’ o cualquier otro tipo de objeto con una metatabla asociada.

• $object_subtype

( cadena ) (Opcional) El subtipo del tipo de objeto. Valor por defecto: ‘’

sanitize_mime_type( $mime_type )

Desinfecta un tipo mimo.

sanitize_option( $option, $value )

Desinfecta varios valores de opciones según la naturaleza de la opción.

Descripción

Esto es básicamente una declaración de cambio que pasará $value a través de una serie de funciones dependiendo de la $option.

Parámetros

• $option

• ( cadena ) (Obligatorio) El nombre de la opción.

• $value

• ( cadena ) (Obligatorio) El valor no desinfectado.

sanitize_sql_orderby ( $orderby )

Asegura que una cadena sea una cláusula válida de ‘ordenar por’ de SQL.

sanitize_text_field ( $str )

Desinfecta una cadena de entrada del usuario o de la base de datos.

sanitize_title( $title )

Desinfecta un título o devuelve un título alternativo.

sanitize_title_for_query( $title )

Desinfecta un título con el contexto de ‘consulta’.

sanitize_title_with_dashes( $title )

Desinfecta un título, reemplazando espacios en blanco y algunos otros caracteres con guiones.

Descripción

Limita la salida a caracteres alfanuméricos, guion bajo (_) y guion (-). El espacio en blanco se convierte en un guion.

sanitize_user()

Desinfecta un nombre de usuario, eliminando caracteres inseguros.

esc_url_raw( $url )

Realiza esc_url () para el uso de la base de datos.

wp_filter_post_kses( $data )

Desinfecta el contenido de las etiquetas HTML permitidas para el contenido de la publicación.

Descripción

El contenido de la publicación se refiere al contenido de la página del tipo ‘publicación’ y no a los $_POSTdatos de los formularios. Esta función espera datos recortados.

wp_filter_nohtml_kses()

Elimina todo el HTML de una cadena de texto.

Ejemplos

Ejemplo 1

A continuación, pondremos un ejemplo de cómo funciona el método sanitize_text_field()

Estamos inyectando código sql dentro del mensaje. Lo que hace la función de sanitización es eliminar este código. Si vamos a nuestro frontend y observamos en la consola, veremos que lo elimina.

Ejemplo 2

Ahora vamos a realizar un ejemplo con el método sanitize_email(), el cual podemos utilizar por ejemplo cuando recibimos en un formulario el mail de algún usuario.

Para ello, vamos a nuestro archivo principal de nuestro plugin res-pruebas. php y escribimos el siguiente código:

Observemos que estamos introduciendo un email con espacios y caracteres que no se pueden admitir en un correo normal, ahora lo pasamos por el método de sanitización y revisamos nuestro frontend.

Vemos cómo me devuelve solo los caracteres admitidos.

Nonces I
Generalidades

El término «nonce» es la abreviación en inglés de «number used once», o número usado una vez. En WordPress los nonces son cadenas de texto que parecen ser cadenas aleatorias, pero en realidad no lo son, pues son generadas a través de funciones hash.

Una función criptográfica hash (usualmente conocida como “hash”) es un algoritmo matemático que transforma cualquier bloque arbitrario de datos en una nueva serie de caracteres con una longitud fija. Independientemente de la longitud de los datos de entrada, el valor hash de salida tendrá siempre la misma longitud.

Nonces en WordPress

Si vemos el código de los enlaces o código de los formularios de WordPress, podemos detectar alguna de estas cadenas de seguridad.

Nonces en URL

Por ejemplo, cuando queremos eliminar una entrada, veremos una url como se muestra en la siguiente imagen:

_wpnonce es el parámetro por defecto que usa WordPress para el nonce en la url.

Nonces en formularios

Por ejemplo, al crear una nueva entrada, aparece el formulario con los diferentes campos para llenar, pero también aparecen campos ocultos. Lo podemos ver con el Inspector de Código, tal como se muestra en la siguiente imagen:

Vemos que el nombre del input es _wpnonce es el nombre por defecto que usa WordPress para el nonce.

Proteger a los usuarios de ellos mismos

Imagínese que un usuario tiene permisos de administrador y está logueado en su WordPress, él no tiene pensado borrar ninguna entrada. Sin embargo, ¿qué sucede si le envío por correo un enlace con la url para eliminar una entrada? Si el usuario pulsa mi enlace, lo estaré forzando a realizar el borrado de alguna entrada.

Este tipo de ataque es parte de los ataques conocidos como CSRF (Cross Site Request Forgery).

Si el usuario ejecuta alguna acción forzada sin tener un nonce válido, WordPress mostrará la siguiente pantalla por defecto y sin opción a nada.

Creando Nonces en el desarrollo de plugins

Por todo lo anteriormente expuesto, cuando desarrollamos plugins, hay que tener presente el uso de nonces. A continuación, veremos algunos escenarios más comunes:

Nonces en URL

Para agregar un nonce en la url, usamos la función wp_nonce_url(), por ejemplo:

En el código anterior:

• Nuestro nonce se generará a partir del texto «ejemplo-nonce».

• Tendrá como nombre «nonce» (en lugar del nombre por defecto _wpnonce).

Nonces en formulario

En este caso usaremos la función wp_nonce_field(), que creará el campo oculto con el valor del nonce.

En el código anterior:

• Nuestro nonce se generará a partir del texto «ejemplo-nonce».

• tendrá como nombre de campo «nonce» (en lugar del nombre por defecto _wpnonce).

Nonces usando ajax

Para usar nonces con ajax, tenemos que crear el nonce y pasarlo al archivo javascript a través de la función wp_localize_script(). Para la creación del nonce usaremos wp_create_nonce().

Comprobando validez de Nonces en el desarrollo de plugins

Para personalizar el mensaje que se muestra cuando hay un error de nonce, puede usar la función wp_verify_nonce(). El código sería similar al siguiente:

Este código funcionará en todos los casos, para nonces en url, formulario y ajax.

IMPORTANTE:

Los nonces cambian cada 12 horas y es válido por 24 horas (es decir, el nonce actual tiene un período de expiración de 24 horas, pero ese código generado se repetirá solo por 12 horas, y luego cambiará por otro, siendo válidos los 2 en su período de tiempo).

Ejemplos

Ejemplo 1

En este ejemplo veremos cómo insertar un nonce en una url. Para ello, vamos a configurar primero nuestros enlaces y vamos a nuestro panel de administración de WordPress, y en ajustes->enlaces permanentes vamos a clicar la opción nombre de la entrada y hacemos clic en guardar cambios.

Ahora vamos al archivo functions.php de nuestra plantilla restaurante, la ruta es:

C:\wamp64\www\_curso02\wp-content\themes\atr_theme

Aquí encontraremos el archivo functions.php y dentro de este archivo crearemos una variable donde guardaremos la ruta de algún post de nuestra web restaurante. A continuación, con la función wp_nonce_url() pasaremos el nonce de seguridad.

El código seria así:

Observemos qué estamos haciendo en echo para ver la ruta y el nonce que generamos.

Nonces II

Ejemplo 2

En este ejemplo crearemos un nonce para un input de un formulario, crearemos una opción de menú en nuestro panel de administrador y un formulario con un botón de eliminar. En este formulario pasaremos el nonce que hemos creado y lo verificaremos.

Creamos un menú en el panel de administración:

Después creamos la función donde pasaremos un nonce por medio de un formulario:

En el código que acabamos de escribir, validaremos el nonce que hemos creado, y pasamos por el formulario a través del campo input con el name “nonce”. Validaremos si el valor $_POST[‘nonce’] existe y no está vacío:

También utilizaremos una function de WordPress wp_verify_nonce(), para comprobar que el nonce que creamos y pasamos por post sea el mismo:

El resultado de todo este código es que, en nuestro panel de administración, al hacer clic en el botón eliminar, veremos un mensaje tal que hemos verificado correctamente el nonce:

Menús y submenús de administración de WordPress
Creación de menús en la administración

Crear un menú en WordPress es bastante sencillo. Existen varias formas de hacerlo: lo puedes poner en un plugin, lo puedes poner en un tema, y luego lo puedes hacer con clases o con funciones sueltas.

¿Para qué vale tener un menú de administración en WordPress? Si quieres poder personalizar o tener tus propias páginas de configuración para vuestro plugin o vuestro tema, esta es la mejor solución.

Crear un menú en WordPress

Para esto usaremos la función add_menu_page() que nos provee la api de WordPress.

Agregar una página de menú de nivel superior.

Descripción

Esta función tiene una capacidad que se utilizará para determinar si una página se incluye o no en el menú.

La función que está conectada para manejar la salida de la página debe verificar que el usuario también tenga la capacidad requerida.

Parámetros

• $page_title

( cadena ) (obligatorio) El texto que se mostrará en las etiquetas de título de la página cuando se seleccione el menú.

• $menu_title

( cadena ) (obligatorio) El texto que se utilizará para el menú.

• $capability

( cadena ) (Requerido) La capacidad requerida para que en este menú se muestre al usuario.

• $menu_slug

( cadena ) (Obligatorio) El nombre del slug para referirse a este menú. Debe ser único para esta página de menú y solo debe incluir caracteres alfanuméricos en minúscula, guiones y guiones bajos para que sean compatibles con sanitize_key ().

• $function

( invocable ) (Opcional) La función que se llamará para generar el contenido de esta página. Valor por defecto: ‘’

• $icon_url

( cadena ) (Opcional) La url del icono que se utilizará para este menú. Pase un SVG codificado en base64 usando un URI de datos, que se coloreará para que coincida con el esquema de color. Esto debería comenzar con ‘data: image / svg + xml; base64,’. Pase el nombre de una clase auxiliar de Dashicons para usar un icono de fuente, por ejemplo, ‘dashicons-chart-pie’. Pase ‘none’ para dejar div.wp-menu-image vacío para que se pueda agregar un icono a través de CSS. Valor por defecto: ‘’

• $position

( int ) (Opcional) Debe aparecer la posición en el orden de menú de este elemento. Valor predeterminado: nulo

Ejemplo

Crearemos un menú como ejemplo en nuestro plugin pruebas. Lo primero que crearemos es un archivo img en la raíz de nuestro plugin y dentro pondremos un archivo de tipo imagen de 20 px x 20 px que es lo que requiere el estándar de WordPress para los iconos personalizados de nuestros menús.

Después en nuestro archivo principal res-pruebas.php escribiremos el siguiente código para crear el menú:

Creando la función callback del menú

Ahora crearemos la función de llamada o función callback del menú, que es donde pondremos nuestro html. Esta función proviene de la función de creación de la página del menú.

Eliminar menús

Para eliminar algún menú del panel de administración, debemos utilizar la función remove_menu_page(), dentro de la misma función donde se creó el menú.

Eliminaremos el menú RES Prueba Nonce que hemos hecho en ejemplos anteriores.

Si vamos a nuestro panel de administrador, veremos cómo desaparece el menú.

Creación de submenús

Los submenús son páginas de opciones adicionales que van dentro del menú que hemos creado. Para crear un submenú del menú RES Opciones de Página, debemos tener en cuenta el slug que es res_options_page y escribimos lo siguiente:

Ahora crearemos la función de llamada o función callback, donde pondré mi html.

Funcion add_submenu_page()

Agregar una página de submenú.

Descripción

Esta función tiene una capacidad que se utilizará para determinar si una página se incluye o no en el menú.

La función que está conectada para manejar la salida de la página debe verificar que el usuario también tenga la capacidad requerida.

Parámetros

• $parent_slug (cadena ) (Obligatorio)

El nombre del slug para el menú principal (o el nombre de archivo de una página de administración estándar de WordPress).

• $page_title

(cadena ) (obligatorio) El texto que se mostrará en las etiquetas de título de la página cuando se seleccione el menú.

• $menu_title

(cadena ) (obligatorio) El texto que se utilizará para el menú.

• $capability

(cadena ) (Requerido) La capacidad requerida para que este menú se muestre al usuario.

• $menu_slug

(cadena ) (Obligatorio) El nombre del slug para referirse a este menú. Debe ser único para este menú y solo debe incluir caracteres alfanuméricos en minúscula, guiones y guiones bajos para que sean compatibles con sanitize_key ().

• $function

( invocable ) (Opcional) La función que se llamará para generar el contenido de esta página. Valor por defecto: ‘’

• $position

( int ) (Opcional) Debe aparecer la posición en el orden de menú de este elemento. Valor predeterminado: nulo.

Como podemos ver en la imagen, tenemos el menú principal y el submenú. Ganchos Hooks

¿Qué son los hooks o ganchos en WordPress y para qué sirven?

WordPress, a diferencia de otros gestores de contenido, utiliza una arquitectura basada en eventos y procedimientos. Si quieres desarrollar tanto temas como plugins en este CMS, es esencial que aprendas a utilizar el sistema de hooks o ganchos.

Los ganchos o hooks en WordPress son puntos concretos y estratégicos dentro del core de WordPress, que permiten añadir funcionalidades o modificar un comportamiento. Cuando la secuencia de carga llegue a ese punto concreto, se ejecuta la función que has “enganchado”.

De esta manera, podrás modificar el funcionamiento del código de WordPress sin ni siquiera tocarlo. Sin embargo, tienes que ser consciente de que los hooks no se ejecutan aleatoriamente, sino que siguen un orden.

En WordPress existen dos tipos de hooks: acciones (actions hooks) y filtros (filters hooks). Aunque se utilizan de la misma manera, el valor que devuelve cada uno es diferente.

Ganchos de acción o Action hooks I

Las acciones o action hooks ejecutan una función propia en un lugar preciso en un momento determinado de la línea de ejecución de WordPress.

Cuando llega a un punto concreto, realice la acción que quiera además de las que ya se van a ejecutar por defecto. En resumen, los action hooks añaden código adicional a su WordPress.

Propiedades

• $tag (requerido):

El nombre de la acción a la que se va a enganchar la función que añada, o sea, que aquí pondré el nombre del do_action().

• $function_to_add (requerido):

El nombre de la función que creó para utilizar con este gancho de acción.

• $priority (opcional):

Se especifica el orden en el que se ejecutan las funciones que están asociadas a ese gancho. Su valor por defecto es 10. Cuanto más pequeño es el número, antes se ejecuta esa función. Si el valor es igual entre dos funciones, se ejecutará antes la que se haya agregado primero al gancho de acción.

• $accepted_args (opcional):

Un número que indica la cantidad de parámetros que va a pasar a la función. Por defecto, es 1.

do_action(‘nombre_hook’)

Así es como puede localizar en qué puntos de WordPress están los action hooks. Para verlo más claro, vamos a poner un ejemplo sencillo.

Imagine que necesita agregar código CSS personalizado dentro de la cabecera de su web.

En el código de WordPress existe una función que se llama wp_head() que se define en el archivo:

/wp-includes/general-template.php.

Esta función utiliza do_action() para crear un punto con el que pueda trabajar con el gancho wp_head.

Si abre el archivo header.php de su theme principal, verá que entre las etiquetas <head></head> se llama a la función wp_head().

Cuando la ejecución de su WordPress llega a ese punto, el código que realmente ejecuta wp_head(); es do_action(‘wp_head’); creando así un punto de anclaje justo antes del cierre de la etiqueta <head>.

De esta manera, cuando usted enganche su función al hook wp_head, se añadirá el código CSS que tiene preparado al header.php de su tema.

Pero la función do_action(); no solo se utiliza en el core de WordPress, y esto es MUY INTERESANTE.

Crearemos unos ejemplos:

Ejemplo 1

Para poder eliminar el widget del panel de control, va a utilizar un hook de WordPress que se activa justo después de que se hayan registrado todos los widgets: widgets_init.

Ahora solo tiene que añadir el código necesario dentro de su función.

Como ve en la siguiente imagen, ya no puede utilizar el widget del calendario.

En el siguiente enlace verá los distintos ganchos para cada widget:

https://developer.wordpress.org/reference/functions/unregister_widget/

Ganchos de acción o Action hooks II

IMPORTANTE:

El resultado final de este ejemplo podremos verlo desde un servidor remoto y no local. La razón es que el servidor local no posee la función sendmail, para ello se debe instalar y ajustar nuestro servidor local Wampserver. Podemos hacerlo si buscamos en internet cómo enviar un correo desde un servidor local.

Ejemplo 2

En esta segunda parte veremos otro ejemplo para los ganchos de acción. Aquí crearemos una función donde el administrador de un sitio web recibirá un email que notificará la creación de un nuevo post, con los datos del autor que lo ha creado, el título del post y la dirección url.

Para ello utilizaremos el do_action(‘save_post’).

Del gancho save_post, obtendremos el id del post y toda la información del post, entonces crearemos nuestro gacho de acción y la función:

Para ver todos los action hooks y saber en qué orden cargan, podemos ir a la web de WordPress:

https://codex.wordpress.org/Plugin_API/Action_Reference/

wp_is_post_revision

Esta función determina si la publicación especificada es una revisión.

Parámetros

• $post

( int | WP_Post ) (obligatorio) ID de publicación u objeto de publicación.

Retorna

(int | false) ID del padre de la revisión en caso de éxito, falso si no es una revisión.

Con el condicional:

Estamos diciendo que, si el post es una revisión, se haga un return y no se continúe ejecutando el código que hay debajo. Pero si el post no es una revisión, entonces el código que hay debajo se ejecutará.

Las variables de más abajo se obtendrán a través del parámetro $post recibido en la función.

Por ejemplo, para obtener el id del autor, instanciaremos el valor $post_ author, que forma parte del array de objetos del parámetro o la variable $post. Para ver los objetos que forman parte de esta variable, simplemente debemos utilizar un var_dump($post). Sería algo así:

Ahora vamos a entradas en nuestro panel de administración->entradas y haremos clic en añadir nueva. Veremos lo siguiente:

Estos son todos los objetos que hay dentro del array.

Funciones de WordPress

A continuación, analizaremos las funciones de WordPress que utilizaremos para obtener determinados valores.

Con la primera función get_the_author_meta() obtendremos el nombre del autor y el email que almacenaremos en las variables $author_id y $name_ autor

get_the_author_meta

Esta función recupera los datos solicitados del autor de la publicación actual.

Parámetros

• $field

( cadena ) (Opcional) El campo de usuario para recuperar. Valor por defecto: ‘’

• $user_id

( int | false ) (Opcional) ID de usuario. Valor predeterminado: falso.

Los valores válidos para el campo $field son:

• admin_color

• aim

• comment_shortcuts

• description

• display_name

• first_name

• ID

• jabber

• last_name

• nickname

• plugins_last_view

• plugins_per_page

• rich_editing

• syntax_highlighting

• user_activation_key

• user_description

• user_email

• user_firstname

• user_lastname

• user_level

• user_login

• user_nicename

• user_pass

• user_registered

• user_status

• user_url

• yim

Con la segunda función get_permalink() obtendremos el link del post y solo debemos pasar el id del post.

La tercera función get_option() recupera un valor de opción basado en el nombre de una opción. Si la opción no existe o no tiene un valor, el valor de retorno será falso.

Los valores de opción de uso más común son los siguientes:

• ‘admin_email’ - Dirección de correo electrónico del administrador del blog.

• ‘blogname’ - Título del weblog; establecido en Opciones generales.

• ‘blogdescription’ - Lema para tu blog; establecido en Opciones generales.

• ‘blog_charset’ - Codificación de caracteres para tu blog; establecido en Opciones de lectura.

• ‘date_format’ - Formato de fecha predeterminado; establecido en Opciones generales.

• ‘default_category’ - Categoría de publicación predeterminada; establecido en Opciones de escritura.

• ‘home’ - La dirección web del hogar del blog; establecido en Opciones generales.

• ‘siteurl’ - Dirección web de WordPress; establecido en Opciones generales.

• Advertencia: Esto no es lo mismo que get_bloginfo( ‘url’ )(que devolverá la url de la página de inicio), sino como get_bloginfo( ‘wpurl’ ).

• ‘template’ - El nombre del tema actual; establecido en la presentación.

• ‘start_of_week’ - El calendario del día de la semana debe comenzar; establecido en Opciones generales.

• ‘upload_path’ - Ubicación de carga predeterminada; establecido en Opciones varias.

• ‘users_can_register’ - Si los usuarios pueden registrarse; establecido en Opciones generales.

• ‘posts_per_page’ - Número máximo de publicaciones para mostrar en una página; establecido en Opciones de lectura.

• ‘posts_per_rss’ - Número máximo de publicaciones más recientes para mostrar en el feed de sindicación; establecido en Opciones de lectura.

La cuarta función wp_mail() nos servirá para enviar un correo electrónico, similar a la función de correo de PHP.

wp_mail

Parámetros

• $to

( cadena | matriz ) (Obligatorio) Matriz o lista de direcciones de correo electrónico separadas por comas para enviar el mensaje.

• $subject

( cadena ) (obligatorio) Asunto del correo electrónico.

• $message

( cadena ) (obligatorio) Contenido del mensaje.

• $headers

( cadena | matriz ) (Opcional) Encabezados adicionales. Valor por defecto: ‘’

• $attachments

( cadena | matriz ) (Opcional) Archivos para adjuntar. Valor predeterminado: array ()

Funciones de PHP

• sprintf()

Esta función o método de php devuelve un string producido según el string de formateo dado. Para consultar toda la información, podemos ir la siguiente url:

https://www.php.net/manual/es/function.sprintf.php

Por último, para que funcione todo, debemos quitar el código que genera comentarios en nuestro frontend.

Estos son los comentarios que hemos ido dejando en los ejemplos de nuestro plugin res-pruebas. Podemos quitar el código o comentarlo; de lo contrario, al intentar crear un post, nos saldrá lo siguiente.

No deben producirse errores a la hora de crear un nuevo post, para que el código que hemos escrito se ejecute correctamente y recibamos el email que esperamos.

Por último, aplicaremos este código en un servidor remoto, y el resultado será que, al crear un post nuevo, recibiremos un email confirmando la creación del post y la url, junto con los datos del autor que lo creó.

Ganchos de filtro o filter hooks

Los filtros o filter hooks de WordPress manipulan la información en un punto concreto de la ejecución, antes de que se muestre en la pantalla o se almacene en la base de datos.

Por ejemplo, puede cambiar el título de una página antes de que salga en la pantalla del usuario, añadir más contenido al título de un post, cambiar el texto de un botón, etc.

Al igual que con los action hooks, le voy a enseñar cuál es la estructura o sintaxis de un filter hook:

add_filter

• $tag (requerido): el nombre de filtro con el que quiera trabajar.

• $function_to_add (requerido): el nombre de la función que se ejecutará cuando el filtro se active.

• $priority (opcional): se especifica el orden en el que se ejecutan las funciones que están asociadas a ese gancho. Su valor por defecto es 10. Cuanto más pequeño es el número, antes se ejecuta esa función. Si el valor es igual entre dos funciones, se ejecutará antes la que se haya agregado primero al action hook.

• $accepted_args (opcional): un número que indica la cantidad de parámetros que va a pasar a la función. Por defecto es 1.

Realmente los action hooks y los filter hooks son muy similares y se utilizan de la misma forma, aunque se usen para cosas diferentes:

• Los filter hooks reciben un parámetro de entrada que usted va a modificar y devolver al hook correspondiente.

• No se llaman con la función do_action(). Como en el caso de los action hooks, se utiliza apply_filters(); por lo que tendrá que localizar en el código de WordPress los puntos en los que puede engancharse al hook con esta función.

• No se referencia con add_action(); sino que se usa add_filter();

Ejemplos

En este ejemplo vamos a a realizar un cambio en las publicaciones de nuestro blog.

Observemos la página blog de nuestro template donde tenemos varias publicaciones:

Veamos que tenemos un resumen de cada post con una cantidad de palabras predefinida que finaliza con unos corchetes y unos puntos suspensivos […]. Esto se debe a que internamente en el desarrollo de la plantilla se incluye la función the_excerp() de WordPress.

Ahora lo que haremos será crear un gancho de filtro para que, donde sea que se aplique esta función the_excerpt(), en vez de aparecer […], aparezcan solo los puntos suspensivos sin el corchete. Debemos tener en cuenta que, como hacemos este pequeño cambio, se pueden hacer muchos más.

Ahora vamos a nuestro archivo principal res-pruebas y vamos a escribir el siguiente código:

Como podemos ver en la siguiente imagen, el gancho de filtro con la función que hemos desarrollado funciona correctamente.

Si quiere ver todos los filter hooks que existen y aprender a utilizarlos correctamente, le recomiendo que visite la documentación oficial de WordPress:

https://codex.wordpress.org/Plugin_API/Filter_Reference

Ganchos personalizados

Los ganchos personalizados sirven para que otros desarrolladores puedan extender nuestros plugins.

Para crear un gancho de acción personalizado, debemos utilizar la función do_action() y, como parámetro, le pasaremos el nombre personalizado que queremos darle a nuestro nuevo gancho de acción.

Ejemplo

Crearemos un gancho personalizado para nuestra página de menú RES Opciones de Página, utilizaremos la función do_action(). Esto servirá para que otro desarrollador pueda extender este formulario y añadir más campos.

Ahora buscaremos el siguiente código:

Esta función es la que utilizamos para crear el html de nuestro menú RES Opciones de Página.

Observemos que hemos creado un nuevo gancho de acción con la función do_action() justo entre el campo input y la función submit para extender el formulario:

Ahora crearemos una función para añadir un nuevo campo al formulario.

Si vamos a nuestro panel de administrador de WordPress, veremos que ahora aparecerá el nuevo campo input.

Veamos cómo queda ahora la pantalla:

Shortcodes
¿Qué es un shortcode?

Un shortcode es un código abreviado que puede insertar en el editor de su web, para añadir funcionalidades al contenido de su página, sin necesidad de tener que insertar lenguaje de programación.

Dicho de otra forma, es una etiqueta (tag) que llama a un script, para que se ejecute en el lugar en el que la ponga. Los shortcodes funcionan como las etiquetas HTML, con la diferencia de que, en vez de usar los símbolos de menor y mayor que (<>), van entre corchetes ([ ]).

Ejemplo

Vamos a crear nuestro primer shortcode. Para ello, vamos al archivo principal de nuestro plugin res-pruebas.php y escribiremos el siguiente código:

Observemos que en la función estamos pasando dos variables: una es $atts, con la cual podemos crear un array de objetos para pasar distintos valores, y otra es una variable $content, con un valor nulo o vacío, lista para recibir lo que nosotros le pasemos.

El gancho de acción para el shortcode será add_shortcode() y el primer parámetro será el nombre que le daremos a nuestro shortcode.

Ahora guardamos y comprobamos que el shortcode funcione. Para ello vamos a nuestro panel de administración, y en entradas crearemos una nueva entrada y le pondremos como título Prueba Shortcode.

Ahora añadiremos un bloque widget y dentro veremos la opción shortcode. Hacemos clic y escribiremos lo siguiente:

[res_texto] Mi primer shortcode [/res_texto]

Veamos la siguiente imagen:

Ahora vamos a publicar la entrada que acabamos de crear y hagamos una vista previa para verlo en nuestro frontend.

Podemos ver que aparece el texto Mi primer shortcode como un título h3.

Creando un shortcode complejo con parámetros

En este tema veremos cómo pasar varios parámetros en un array dentro de nuestro shortcode, escribiremos el siguiente código y justo debajo explicaremos su funcionalidad.

Observemos que en la función res_shortcode_link_personalizado() pasamos dos parámetros:

• $atts

• $contenido = null

La primera variable $atts recibirá los valores de la variable $attr_default, que será un array donde pasaremos unos objetos que formarán parte del botón que personalizaremos.

Justo debajo utilizaremos la función array_change_key_case(), esta función de php cambia a mayúsculas o minúsculas todas las claves en un array. A esta función le pasaremos dos parámetros, el primero será la variable y el segundo parámetro será CASE_UPPER o CASE_LOWER.

CASE_UPPER: convierte los índices en mayúsculas.

CASE_LOWER: convierte los índices a minúsculas. Después de esto utilizaremos la función extract() de php para convertir los índices del array en variables, esta función extract() le pasamos 2 parámetros, la variable del array y un valor flat EXTR_OVERWRITE.

Para ver más acerca de esta función, podemos ir a la siguiente URL:

https://www.w3schools.com/php/func_array_extract.asp

Observemos que dentro de la función extract() pasamos la función shortcode_atts().

shortcode_atts

Esta función combina atributos de usuario con atributos conocidos y completa los valores predeterminados cuando sea necesario.

Descripción

Los pares deben considerarse como todos los atributos que son compatibles con la persona que llama y se dan como una lista. Los atributos devueltos solo contendrán los atributos en la lista de $pairs.

Si la lista $atts tiene atributos no compatibles, se ignorarán y se eliminarán de la lista final devuelta.

Parámetros

• $pairs

( matriz ) (obligatorio) Lista completa de atributos admitidos y sus valores predeterminados.

• $atts

( matriz ) (Obligatorio) Atributos definidos por el usuario en la etiqueta shortcode.

• $shortcode

( cadena ) (Opcional) El nombre del shortcode, proporcionado para el contexto para permitir el filtrado valor por defecto: ‘’

Por último, escribiremos un return y el html del enlace o botón personalizado con las variables que creamos en el array.

Ejemplo

Con el código que hemos escrito, vamos a crear un botón con un enlace el cual podremos personalizar pasando parámetros en un array. En el shortcode podremos pasar parámetros como una clase button de Bootstrap 4, un href y un target.

Las clases para el botón podrían ser:

• btn btn-primary

• btn btn-secondary

• btn btn-success

• btn btn-danger

• btn btn-warning

• btn btn-info

• btn btn-light

• btn btn-dark

El href lo pasaremos como parámetro url.

El target que pasemos como parámetro puede ser:

• _blank

• _self

• _parent

• _top

Ahora vamos a nuestro panel de administración y, en entradas, vamos a la entrada que creamos anteriormente. Pruebe shortcode, aquí añadiremos un nuevo bloque widgets->shortcode. En este widget escribiremos el siguiente shortcode:

[reslink url=”https://wordpress.org/” class=”btn btn-primary” target=”_ blank”][/reslink]

Observemos que en este shortcode estamos pasando parámetros con valores que nosotros mismos personalizaremos para el botón que creamos.

Si vamos a visualizar esta entrada, veremos nuestro botón Ver más información, que nos llevará a la url que hemos puesto.

Podremos ver información más detallada a cerca de la Api shortcode en el codex de WordPress:

https://codex.wordpress.org/Shortcode_API

Modificando el shortcode con parámetros

En el tema anterior habíamos creado un shortcode con parámetros. Desarrollamos la función res_shortcode_link_personalizado(), donde pasábamos dos parámetros:

• $atts

• $content = null

El código era el siguiente:

Vamos a realizar un ejercicio en el que modificando un poco esta función, podremos personalizar el texto del botón de nuestro shortcode.

Ejercicio

Vamos a personalizar el texto que hay en el botón de nuestro shortcode. Para ello, vamos a remplazar la variable $texto que hay dentro de la etiqueta <a></a> de nuestro botón.

Con esto ya podremos ir a nuestro panel de administración entradas y modificar el shortcode que teníamos. Ahora pondremos el texto Más información entre la etiqueta de apertura y la etiqueta de cierre de nuestro shortcode.

[reslink url=”https://wordpress.org/” class=”btn btn-primary” target=”_blank”]Más información[/reslink]

Si hacemos una vista previa de la entrada, veremos cómo cambia el texto del botón.

Para ver información más detallada a cerca de la Api shortcode, recuerde ir al siguiente enlace de la documentación oficial de wordpress:

https://codex.wordpress.org/Shortcode_API

Creando un filtro para nuestro shortcode

Crear un filtro para nuestro shortcode puede ayudarnos o ayudar a otros desarrolladores a extenderlo desde otro plugin. Para ello, vamos al código con el que hemos trabajado anteriormente, la función res_shortcode_link_personalizado(). Dentro vamos a buscar la función shortcode_atts( ), a la cual le habíamos pasado 2 parámetros.

Ahora le pasaremos un tercer parámetro. Este tercer parámetro será el nombre del shortcode que es reslink, quedaría así:

Este último parámetro es el que se utiliza para crear el gancho de filtro.

Después de este cambio, vamos a realizar el siguiente ejercicio:

Ejercicio

En el siguiente ejercicio vamos a crear una función de filtro para nuestro shortcode. Lo haremos desde otro plugin; para ello vamos a los archivos de nuestro WordPress y vamos a

wp-content/plugins/hello-dolly/hello.php

Si no tenemos el plugin, lo buscaremos en el panel de administración Plugins->añadir. Una vez aquí, buscaremos hello e instalaremos Hello Dolly y luego activaremos el plugin.

Abrimos el archivo hello.php y escribimos el siguiente código:

Observemos algunas cosas importantes. Por ejemplo, que en esta nueva función estamos pasando 4 parámetros:

• $attr_final : esa variable nos devuelve el valor que pasamos desde el panel de administración.

• $attr_default : esta variable nos devuelve el valor que por defecto pasamos al momento de crear el shortcode, o sea, el valor por defecto.

• $attr_new : esta variable nos devuelve el mismo valor que la variable $attr_default hasta que la retornamos con los nuevos valores.

• $shortcode : esta variable me devuelve el nombre del shortcode, el cual definimos en la función res_shortcode_link_personalizado().

Haremos un var_dump() con cada variable y aplicaremos un <br> para separarlos.

Justo debajo pasaremos 3 índices del array $attr_final ( url, class, target ) con un valor diferente al que tenemos por defecto, así comprobaremos que la función de filtro funciona.

Por último, retornaremos la variable $attr_final.

Si hacemos una vista previa de la entrada, veremos los valores de las variables que se muestran con el var_dump(). También veremos cómo cambia nuestro botón personalizado:

IMPORTANTE

Por último, y lo más importante de este ejercicio, es el gancho de filtro de nuestra función:

Fijémonos que el gancho de filtro es ‘shortcode_atts_reslink’. Este gancho tiene el nombre de la función shortcode_atts seguido de un guion bajo y el nombre de nuestro shortcode reslink. Así creamos los ganchos de filtro para los shortcodes.

Eliminando el shortcode

Para eliminar el shortcode, solo debo emplear la función remove_shortcode() y pasarle el nombre de nuestro shortcode.

Así ya no se mostrará más el shortcode. También podemos crear un condicional que me valide si el shortcode ha sido eliminado. Esto me devolverá un mensaje que saldrá en la cabecera de nuestro sitio web.

Podemos comprobarlo con solo ver la página de inicio.

Recordemos que este tipo de comprobaciones que generan texto sin más en nuestro WordPress pueden causar errores, así que podemos hacer algo más sofisticado.

Por ejemplo, podemos desarrollar una función para comprobar la existencia del shortcode en la misma página de entrada donde lo insertamos, es decir, en la entrada Pruebas Shortcode. Para ello eliminaremos o comentaremos el condicional que hemos creado y escribiremos la siguiente función:

Observemos que esta función lleva el gancho de filtro the_content, y recibe un parámetro que es $content. Al final se retornará esta variable con el mensaje o texto que queremos pasar en la función. Pasaremos el mensaje dentro de un alert de Bootstrap 4, podemos ver los diferentes tipos de alert que hay aquí:

https://getbootstrap.com/docs/4.5/components/alerts/

Con el primer condicional comprobaremos si estamos dentro de una publicación y dentro del bucle principal. Para ello utilizamos la primera función is_singular(). Esta función determina si la consulta es para una publicación única existente de cualquier tipo de publicación.

La segunda función in_the_loop() nos servirá para determinar si nos encontramos dentro del bucle que genera las publicaciones. El valor que hay que devolver será verdadero si determina que la llamada que estamos haciendo se encuentra dentro del loop y nos devolverá falso si el bucle no ha comenzado o finalizado.

La tercera función is_main_query() se puede utilizar para evaluar si la consulta actual (como dentro del bucle) es la consulta “principal” (en oposición a una consulta secundaria). Esta función se usa más comúnmente dentro de los ganchos para distinguir la consulta principal de WordPress (para una página, publicación o archivo) de una consulta personalizada / secundaria.

Con el segundo condicional utilizaremos la función is_single(), que funciona para cualquier tipo de publicación, y como parámetro le pasaremos el slug de la publicación, así el mensaje será mostrado en el post que estamos indicando.

Veamos el resultado final en nuestra entrada.

Uso de las Api settings y Api options
¿Qué son las API settings?

La API de configuración nos permite definir páginas de configuración, crear secciones dentro de estas páginas y campos dentro de las secciones.

Se pueden registrar nuevas páginas de configuración junto con secciones y campos dentro de ellas. Las páginas de configuración existentes también se pueden agregar al registrar nuevas secciones de configuración o campos dentro de ellas.

La API de configuración definida

En esta imagen vemos un formulario para configurar opciones

En el nivel más básico, la API de configuración es un conjunto de funciones proporcionadas por WordPress que simplifica el proceso de introducir menús, páginas de opciones y guardar, validar y recuperar la entrada del usuario.

Funciones

Setting Register/Unregister	Add Field/Section
register_setting() unregister_setting()	add_settings_section() add_settings_field()

Options Form Rendering	Errors
settings_fields() do_settings_sections() do_settings_fields()	add_settings_error() get_settings_errors() settings_errors()

Para ver más información, podemos ir a la documentación de WordPress:

https://developer.wordpress.org/plugins/settings/settings-api/

Uso de la API de configuración I

Para empezar a comprender un poco mejor el uso de la API setting o API de configuración, estudiaremos sus funciones.

register_setting

La función register_setting() registra una configuración y sus datos.

Parámetros

• $option_group:

Un nombre de grupo de configuración. Debe corresponder a un nombre de clave de opción de la lista blanca. Los nombres de las teclas predeterminadas de las opciones incluidas en la lista blanca incluyen:

– ‘general’,

– ‘discussion’,

– ‘media’,

– ‘reading’,

– ‘writing’,

– ‘misc’,

– ‘options’,

– ‘privacy’

• $option_name: El nombre de una opción para desinfectar y guardar.

• $args:

– ‘tipo’ :el tipo de datos asociados con esta configuración. Los valores válidos son ‘string’, ‘boolean’, ‘integer’, ‘number’, ‘array’ y ‘object’.

– ‘descripción’: una descripción de los datos adjuntos a esta configuración.

– ‘sanitize_callback’: una función de devolución de llamada que desinfecta el valor de la opción.

– ‘show_in_rest’: si los datos asociados con esta configuración deben incluirse en la API REST. Al registrar configuraciones complejas, este argumento puede ser opcionalmente una matriz con una clave de ‘esquema’.

– ‘default’: valor predeterminado al llamar get_option().

Agregue una nueva sección a una página de configuración

Usaremos add_settings_section() para definir nuevas secciones de configuración para una página de administración.

Mostraremos las secciones de configuración en la función de devolución de llamada de nuestra página de administrador con do_settings_sections ().

Agregaremos campos de configuración a nuestra sección con add_settings_ field ().

El argumento o variable $callback debe ser el nombre de una función que muestre cualquier contenido que deseamos. Mostraremos el nombre de esta función en la parte superior de la sección de configuración antes de los campos reales.

add_settings_section

Parámetros

• $id:

slug-name para identificar la sección. Se usa en el atributo ‘id’ de las etiquetas.

• $title:

Título formateado de la sección. Se muestra como el título de la sección.

• $callback:

Función que se hace eco de cualquier contenido en la parte superior de la sección (entre encabezado y campos).

• $page:

El slug-name de la página de configuración en la que se muestra la sección. Las páginas incorporadas incluyen ‘general’, ‘lectura’, ‘escritura’, ‘discusión’, ‘medios’, etc. Cree las suyas usando add_options_page () ;

Ejemplo

A continuación, realizaremos un ejercicio donde crearemos una nueva opción de configuración en nuestro panel de administración Ajustes->Generales.

Iremos a nuestro archivo principal de nuestro plugin y escribiremos la siguiente función:

El resultado es este:

Uso de la API de configuración II

Ahora crearemos campos de configuración con la función add_settings_ field(); esta función recibe 6 parámetros:

add_settings_field

Usaremos esto para definir un campo de configuración que se mostrará como parte de una sección de configuración dentro de una página de configuración. Los campos se muestran usando do_settings_fields () en do_settings-secciones ().

El argumento $callback debería ser el nombre de una función que repita las etiquetas de entrada html para este campo de configuración. Use get_option() para recuperar los valores existentes para mostrar.

Parámetros

• $id: slug-name para identificar el campo. Se usa en el atributo ‘id’ de las etiquetas.

• $title: título formateado del campo. Se muestra como la etiqueta del campo durante la salida.

• $callback: función que llena el campo con las entradas de formulario deseadas. La función debe hacer eco de su salida.

• $page: (Obligatorio) el nombre de la página de configuración en la que se muestra la sección (general, lectura, escritura, ...).

• $section: (Opcional) el nombre de la sección de la página de configuración en la que se muestra el cuadro. Valor predeterminado: ‘predeterminado’

• $args: ( matriz ) (Opcional) argumentos adicionales utilizados al generar el campo.

– ‘label_for’ (cadena) Cuando se proporciona, el título de la configuración se envolverá en un <label>elemento, su (for) atributo se completará con este valor.

– ‘clase’ (cadena) Clase CSS que se agregará al <tr>elemento cuando se muestre el campo.

– Valor predeterminado: array ()

Continuaremos con el ejemplo donde estábamos creando un campo de configuración en ajustes generales de nuestro panel de administración de WordPress:

Con esta función ya tendremos creado el campo, solo falta que en la función de llamada ‘res_config_campo1_cb1’; escribamos nuestro código html. Observemos también que en el último parámetro le estamos pasando el id o slug de la sección que creamos res_config_seccion.

Ahora, si vamos a nuestro panel de configuración, veremos lo siguiente:

Si escribimos algo en el campo de texto que acabamos de crear y hacemos clic en Guardar cambios, veremos que no se guarda, y el campo queda vacío.

Solo falta escribir el código que hará que, al escribir algún texto en el campo, podamos recuperarlo de la base de datos y, para ello, utilizaremos la función get_option(); dentro de esta función escribiremos el string id que pusimos en el campo name del input, que es el slug que creamos al registrar la sección res_primera_configuracion, así que escribiremos el siguiente código:

Volvemos a nuestro panel de administrador. En ajustes generales vamos a nuestra opción personalizada y escribiremos algo, por ejemplo, un nombre Alicia, y después hacemos clic en Guardar. Ahora veremos que el nombre Alicia se guarda.

Podemos comprobarlo también en la base de datos. Iremos a nuestra base de datos y buscaremos la tabla atr_options. Haremos clic y, una vez nos la muestre, pondremos en la cabecera lo siguiente:

Después veremos cómo con este filtro nos devolverá las filas con el prefijo res_ y el nombre que hemos puesto.

Con el dato que obtengamos podemos desarrollar la función o acción que queramos para nuestro sitio web.

Uso de la API de configuración III

Ahora crearemos varios campos de opciones de configuración para una sola sección. Para ello utilizaremos el 6.° parámetro de la función add_settings_ field(), que es un array.

Utilizaremos el mismo código anterior, solo que ahora añadiremos un campo más y una función de llamada. El código quedaría así:

Si nos fijamos, el 6.° parámetro es un array asociativo con unos nombres clave y su valor. También podemos ver que, para recibir este array de valores, debemos poner en la función de llamada una variable, en nuestro caso hemos puesto $args, pero podemos llamarla como queramos. Esta variable recoge los valores del arreglo que creamos en el 6.° parámetro.

Si vamos a nuestro panel de administrador, veremos:

Y si vamos a nuestra base de datos, veremos lo siguiente:

Vemos que esta fila indica que es un arreglo con 2 objetos, y si hacemos doble clic, nos mostrará los objetos, la clave y el valor que se recoge del campo.

Con los datos que obtengamos en cada campo, podemos desarrollar la función o acción que queramos para nuestro sitio web.

Uso de la API options

Esta función nos ayuda a crear un nuevo campo en la tabla _options de nuestra base de datos. En este campo podemos guardar valores que podemos utilizar para realizar configuraciones.

add_option

Parámetros

• $option

(cadena ) ( obligatorio ) Nombre de la opción que se va a agregar. No debe exceder los 64 caracteres. Use guiones bajos para separar las palabras y no use mayúsculas; esto se colocará en la base de datos. Predeterminado: Ninguno.

• $value

(mixto) (opcional) Valor para el nombre de esta opción. Limitado a 2 ˆ 32 bytes de datos. Valor predeterminado: cadena vacía.

• $deprecated

(cadena) (opcional) Descripción. Ya no se usa a partir de la versión 3 de WordPress.

• $autoload

(cadena) (opcional) Si se carga la opción cuando se inicia WordPress. El valor predeterminado está habilitado. Acepte ‘no’ para deshabilitar por razones heredadas. Valor predeterminado: ‘sí’.

Descripción

Agregue una fila personalizada con un valor a la tabla de opciones de nuestra base de datos, ya sea un solo valor o un array.

No necesita serializar valores. Si el valor necesita ser serializado, entonces será serializado antes de ser insertado en la base de datos. Recuerde: los recursos no se pueden serializar o agregar como una opción.

Puede crear opciones sin valores y luego actualizar los valores más adelante. Las opciones existentes no se actualizarán, y se realizarán comprobaciones para asegurarse de que no está agregando una opción protegida de WordPress. Se debe tener cuidado de no nombrar las opciones de la misma manera que las que están protegidas.

Ejemplo 1

En este ejemplo utilizaremos el prefijo (_atr). Vamos a nuestro archivo principal de nuestro plugin y escribiremos lo siguiente:

No hace falta ningún gancho de acción. Podemos crear esto dentro de cualquier función.

A continuación, revisaremos nuestra base de datos y buscaremos en la tabla Options:

IMPORTANTE:

No podemos cambiar el valor de esta opción, tendremos que eliminarla o actualizarla con otra función.

Ejemplo 2

Crearemos una opción, pero esta vez el valor será un arreglo.

Ahora revisaremos la base de datos, en la tabla _options.

Recuperando el valor de la opción.

Para recuperar este valor, utilizaremos la función get_option();

Si revisamos nuestra página web, veremos los valores:

Para actualizar el valor de una opción, utilizaremos la función update_option(); actualizaremos el valor de la opción que creamos en el ejemplo 01, escribiremos lo siguiente:

Revisamos la base de datos:

Para eliminar esta opción de la tabla _options, solo bastará con poner la función delete_option();