Читать книгу El gran libro de desarrollo de plugins WordPress - Jhon Jairo Rincón Cardona - Страница 65
Оглавление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:
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:
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.
