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

Yazı tipi:

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: