Kitabı oku: «El gran libro de desarrollo de plugins WordPress», sayfa 3

Yazı tipi:

¿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.