Cómo agregar configuraciones personalizadas a un widget existente en WordPress

En esta publicación, aprenderemos cómo agregar su HTML personalizado y configuraciones a cualquiera de los widgets estándar de WordPress u otros. Usando esa configuración, aprenderemos diferentes trucos sobre cómo manipular el comportamiento de los widgets en consecuencia.

La primera parte; agregar y guardar sus configuraciones personalizadas es bastante fácil. La segunda parte depende de lo que quieras hacer específicamente y depende del widget que estés manipulando. En este post he incluido dos ejemplos; omitir un widget dependiendo de una configuración (para agregar configuraciones para controlar la visibilidad del widget en ciertos casos) y manipular los argumentos del menú del widget de navegación de WordPress. El ejemplo dado para la segunda parte debería darle una buena pista sobre cómo puede manejar lo que quiere hacer.

Agregar configuraciones personalizadas a cualquier widget

Para agregar configuraciones personalizadas a los widgets existentes, usamos una acción llamada [in_widget_form](https://developer.wordpress.org/reference/hooks/in_widget_form/). Esta acción se aplica a la form()función de todos los widgets, que es la función responsable de representar la parte administrativa del widget.

Con ese filtro obtenemos tres parámetros pero en realidad solo nos interesa el primero y el tercero. La primera es la instancia del widget que usaremos para obtener los nombres e ID de campo adecuados y (opcionalmente) verificar a qué tipo de widget estamos enganchados. El tercer parámetro es una matriz de la configuración guardada del widget, que debemos usar para verificar el estado guardado anterior de nuestra configuración.

El siguiente código agregará una casilla de verificación con el nombre de configuración ‘ awp-custom-setting‘. Ajuste el nombre y el HTML a la entrada que necesita. Lo importante es usar $widget->get_field_name()para agregar ID y nameatributos adecuados a todas sus entradas. El valor de sus entradas debe completarse con lo que se guardó anteriormente, y eso es algo que encontrará en el parámetro $instance. Para las casillas de verificación, puede usar la función de WordPress [checked](https://developer.wordpress.org/reference/functions/checked/)()para generar el atributo marcado.

Después de agregar esto al functions.phpcódigo de su tema o complemento, todos los widgets ahora deberían tener una casilla de verificación al final de su formulario en admin.

Apunta a widgets específicos

Si desea aplicar su configuración solo a uno o algunos widgets específicos, puede comparar la propiedad id_baseen el $widgetobjeto. Necesitará saber que la ID base es: si no está seguro, simplemente haga un var_dump($widget->id_base)clic dentro del enlace, guarde y verifique la salida para cada widget en el administrador. Por ejemplo, el widget de navegación tiene la base nav_menude ID y el widget de archivos tiene archives.

En el siguiente ejemplo, comprobamos si el widget es un widget de navegación. Si no es así, la función se cancela con un return. Solo los widgets de navegación obtendrán la casilla de verificación personalizada:

Debería obtener la configuración en admin así:

Por lo tanto, la configuración se ha agregado; sin embargo, en este momento no se están guardando sus configuraciones. Arreglemos eso.

Guardar su configuración personalizada

Necesitamos conectarnos a la update()función del widget para actualizar nuestra configuración personalizada.

Para ello utilizamos el filtro [widget_update_callback](https://developer.wordpress.org/reference/hooks/widget_update_callback/). El proceso de guardar nuestra configuración es exactamente como lo haría cuando escribe una clase de widget. El filtro proporciona tres parámetros; la primera es la matriz de instancias que se guardará. El segundo parámetro es el estado que se ha publicado al guardar el widget y el tercero es el estado anterior. Necesitamos asegurarnos de obtener nuestros nuevos valores del segundo parámetro y agregarlos al primero.

Así es como actualizaríamos el estado de nuestra casilla de verificación; como queremos guardar un valor trueo false:

add_filter('widget_update_callback', function($instance, $new_instance, $old_instance) {
    $instance['awp-custom-setting'] = isset($new_instance['awp-custom-setting']);
    return $instance;
}, 10, 3);

Recuerde ajustar los nombres de entrada a sus propios nombres de configuración. Si está agregando varias entradas, debe repetir esto para cada una.

¡Ahora debería ver que su configuración personalizada se está guardando en el administrador!

Uso de configuraciones de widgets personalizadas guardadas

Como se mencionó anteriormente, esta parte realmente depende de lo que desea que haga su configuración. Desafortunadamente, no es tan sencillo porque la mayoría de los widgets no agregan filtros o ganchos en sus salidas. Comencemos con algo simple; evite renderizar el widget dependiendo de la configuración.

Impedir el widget de renderizado según la configuración personalizada

Digamos que está agregando configuraciones para cuando el widget debería estar visible; por ejemplo, ocultarlo en ciertas plantillas (ocultar en la plantilla de resultados de búsqueda, pero mostrarlo en la página principal y único), o reaccionar a otros estados de WordPress.

Para ello podemos utilizar el filtro [widget_display_callback](https://developer.wordpress.org/reference/hooks/widget_display_callback/). Todo lo que tenemos que hacer es verificar el parámetro de instancia provisto para nuestra configuración y regresar falsesi no queremos renderizar el widget.

Este código simple evitará renderizar el widget si la casilla de verificación personalizada que agregamos arriba está marcada:

add_filter('widget_display_callback', function($instance, $widget, $args) {
    if ($instance['awp-custom-setting']) {
        return false;
    }
    return $instance;
}, 10, 3);

Probablemente quieras comparar otros estados. Este es un ejemplo simple en el que nuestra casilla de verificación es una casilla de verificación para "Ocultar en vistas de publicaciones individuales". Simplemente verificamos si actualmente estamos en una vista de publicación única [is_singular](https://developer.wordpress.org/reference/functions/is_singular/)()y, si la casilla de verificación está marcada, devolvemos false.

add_filter('widget_display_callback', function($instance, $widget, $args) {
    if (is_singular() && $instance['awp-custom-setting']) {
        return false;
    }
    return $instance;
}, 10, 3);

Modificar la configuración o la salida del widget existente

Un filtro poderoso para utilizar para jugar con los widgets existentes es [dynamic_sidebar_params](https://developer.wordpress.org/reference/hooks/dynamic_sidebar_params/). Eche un vistazo a la página de documentación para ver qué parámetros puede modificar. Por ejemplo, puede agregar clases personalizadas, puede modificar las cadenas before_widget, after_widgeto before_titley after_titleHTML. Sin embargo, esto se aplica a todos los widgets, también al administrador y al frontend. Y con este filtro no tiene acceso a la instancia del widget (configuración guardada) ni a la configuración del widget (por ejemplo, tipo de widget).

Obviamente, necesitamos al menos verificar nuestra configuración personalizada. Entonces, necesitamos hacer bastante código para obtener los valores que necesitamos.

Lo primero que podemos hacer es acceder a una variable global $wp_registered_widgets. Esta es una matriz que contiene todos los widgets disponibles registrados. Usando ese registro, podemos usar el parámetro del filtro para encontrar el widget específico en el que nos encontramos actualmente. Una vez que hemos encontrado el widget actual, tenemos acceso a los parámetros del widget, como id_base– que, como vimos anteriormente, nos dice el tipo de widget.

Como puede ver en línea #9, finalmente podemos verificar en qué tipo de widget nos encontramos actualmente. En el código anterior, devuelvo si el tipo de widget no es un widget de navegación, ya que nuestra configuración personalizada solo se agregó para esos widgets.

Obtener la configuración guardada del widget

Pero también necesitamos obtener la configuración guardada por widget (incluida nuestra configuración personalizada). Las configuraciones guardadas de todos los widgets se almacenan en la base de datos de opciones agrupadas por tipo de widget. Usando una propiedad en el registro de widgets, podemos usar [get_option](https://developer.wordpress.org/reference/functions/get_option/)()para obtener la configuración guardada para el tipo de widget actual. El retorno será una matriz indexada donde necesitamos usar otro parámetro más del filtro para encontrar el índice actual (porque puede agregar múltiples del mismo tipo de widget en las mismas barras laterales o en diferentes). Es más fácil mostrar con código que explicarlo:

¡Finalmente obtenemos las configuraciones guardadas del widget! En el código de ejemplo anterior, en la línea #9, verificamos si nuestra casilla de verificación personalizada está marcada o no.

Ejemplos

En este punto, depende de ti lo que quieras hacer. Por ejemplo, puede generar una salida después del título del widget, pero antes del contenido del widget:

Para casos de uso más reales, normalmente resolvería la mayoría agregando ciertos filtros en este punto, llamando add_filter()en este punto.

A continuación se muestra un ejemplo de modificación de los argumentos del menú de navegación mediante la adición de un filtro si se marcó nuestra configuración. Si no estaba marcado, nos aseguramos de que se elimine el filtro. El filtro para modificar los argumentos para representar un menú de navegación es widget_nav_menu_args. En el código a continuación, definí una función para aplicar a este filtro que agrega un nuevo argumento a los argumentos del menú; un caminante:

    ...
    if ($saved_settings['my-custom-thing']) {
        add_filter('widget_nav_menu_args', 'awp_add_menu_walker', 10, 3);
    } else {
        remove_filter('widget_nav_menu_args', 'awp_add_menu_walker', 10);
    }
    return $params;
});
function awp_add_menu_walker($nav_menu_args, $nav_menu, $args) {
    $nav_menu_args['walker'] = new AWP_Custom_Walker();
    return $nav_menu_args;
}

El código anterior es un ejemplo de un caso de uso en el que la casilla de verificación personalizada controla si se aplica o no un caminante de menú al menú. Excelente si desea que todos los menús se muestren con normalidad, pero desea que la opción de widgets de menú específicos se muestre de manera diferente. Lo que haga el andador con la salida del menú depende de usted.

Consulte a continuación el código completo para agregar una configuración personalizada a todos los menús de navegación, actualizarla y aplicar un menú de navegación.

Esperemos que esto sea suficiente para que descubras cómo codificar lo que quieres hacer. Realmente depende de lo que quieras hacer y con qué tipo de widget estés trabajando. Como se mencionó anteriormente, por lo general, la mayoría de las modificaciones se pueden resolver agregando filtros para hacer lo suyo en formato dynamic_sidebar_params.

Ejemplo completo: configuración de casilla de verificación personalizada en los widgets de navegación para aplicar un caminante de menús

Aquí está el código completo para agregar una casilla de verificación personalizada a todos los widgets del menú de navegación de WordPress para usar un caminante de menú registrado. (Código de andador no incluido)

Conclusión

¡Espero que esta publicación haya sido útil para resolver sus necesidades o darle algunos consejos sobre cómo puede hacer lo que necesita hacer!