Neste post, aprenderemos como adicionar seu HTML personalizado e configurações a qualquer um dos widgets padrão do WordPress ou outros. Usando essas configurações, aprenderemos diferentes truques sobre como manipular o comportamento dos widgets de acordo.
A primeira parte; adicionar e salvar suas configurações personalizadas é bastante fácil. A segunda parte depende do que você quer fazer especificamente, e depende de qual widget você está manipulando. Neste post incluí dois exemplos; pular um widget dependendo de uma configuração (para adicionar configurações para controlar a visibilidade do widget em certos casos) e manipular os argumentos de menu do widget de navegação do WordPress. O exemplo dado para a segunda parte deve lhe dar uma boa pista de como você pode lidar com o que deseja fazer.
Adicionando configurações personalizadas a qualquer widget
Para adicionar configurações personalizadas a widgets existentes, usamos uma ação chamada [in_widget_form](https://developer.wordpress.org/reference/hooks/in_widget_form/). Esta ação é aplicada à função de todos os widgets form(), que é a função responsável por renderizar a parte admin do widget.
Com esse filtro, obtemos três parâmetros, mas estamos realmente interessados apenas no primeiro e no terceiro. A primeira é a instância do widget que usaremos para buscar nomes e IDs de campo apropriados e (opcionalmente) verificar em que tipo de widget estamos conectados. O terceiro parâmetro é uma matriz de configurações salvas do widget, que precisamos usar para verificar o estado salvo anterior de nossas configurações.
O código abaixo adicionará uma caixa de seleção com o nome da configuração ‘ awp-custom-setting‘. Ajuste o nome e o HTML para a entrada de que você precisa. O importante é usar $widget->get_field_name()para adicionar IDs e atributos adequados namea todas as suas entradas. O valor de suas entradas deve ser preenchido com o que foi salvo anteriormente, e isso é algo que você encontrará no parâmetro $instance. Para caixas de seleção, você pode usar a função do WordPress [checked](https://developer.wordpress.org/reference/functions/checked/)()para gerar o atributo verificado.
Depois de adicionar isso ao código do seu tema functions.phpou plugin, todos os widgets agora devem receber uma caixa de seleção no final do formulário no admin.
Widgets específicos de destino
Se você deseja aplicar suas configurações apenas a um ou alguns widgets específicos, pode comparar a propriedade id_baseno $widgetobjeto. Você precisará saber qual é o ID base – se não tiver certeza, simplesmente faça um var_dump($widget->id_base)dentro do gancho, salve e verifique a saída de cada widget no admin. Por exemplo, o widget Navigation tem a base nav_menude ID e o widget Archives tem archives.
No exemplo abaixo verificamos se o widget é um widget de Navegação. Se não for, a função é cancelada com um return. Somente widgets de navegação terão a caixa de seleção personalizada:
Você deve obter a configuração em admin assim:
Então a configuração foi adicionada, porém no momento suas configurações não estão sendo salvas. Vamos consertar isso.
Salvando suas configurações personalizadas
Precisamos nos conectar à update()função do widget para atualizar nossas configurações personalizadas.
Para isso usamos o filtro [widget_update_callback](https://developer.wordpress.org/reference/hooks/widget_update_callback/). O processo de salvar nossas configurações é exatamente como você faria quando escreve uma classe de widget. O filtro fornece três parâmetros; o primeiro é o array de instâncias que será salvo. O segundo parâmetro é o estado que foi postado ao salvar o widget e o terceiro é o estado antigo. Precisamos ter certeza de buscar nossos novos valores do segundo parâmetro e adicioná-los ao primeiro.
É assim que atualizaríamos o estado de nossa caixa de seleção; como queremos salvar um valor trueou 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);Lembre-se de ajustar os nomes de entrada aos seus próprios nomes de configuração. Se você estiver adicionando várias entradas, precisará repetir isso para cada uma.
Agora você deve ver que suas configurações personalizadas estão sendo salvas no admin!
Usando configurações de widget personalizadas salvas
Como mencionado anteriormente, esta parte realmente depende do que você deseja que suas configurações façam. Infelizmente, não é tão simples porque a maioria dos widgets não adiciona filtros ou ganchos em suas saídas. Vamos começar com algo simples; evite renderizar o widget dependendo das configurações.
Impedir o widget de renderização dependendo da configuração personalizada
Digamos que você esteja adicionando configurações para quando o widget deve estar visível; por exemplo, escondê-lo em determinados modelos (ocultar no modelo de resultados de pesquisa, mas mostrar na página inicial e no single) ou reagir a outros estados do WordPress.
Para isso podemos usar o filtro [widget_display_callback](https://developer.wordpress.org/reference/hooks/widget_display_callback/). Tudo o que precisamos fazer é verificar o parâmetro de instância fornecido para nossa configuração e retornar falsese não quisermos renderizar o widget.
Este código simples evitará renderizar o widget se a caixa de seleção personalizada que adicionamos acima estiver marcada:
add_filter('widget_display_callback', function($instance, $widget, $args) {
if ($instance['awp-custom-setting']) {
return false;
}
return $instance;
}, 10, 3);Você provavelmente quer comparar outros estados. Este é um exemplo simples em que nossa caixa de seleção é uma caixa de seleção para "Ocultar em visualizações de postagens únicas". Simplesmente verificamos se estamos atualmente em uma visualização de postagem única com [is_singular](https://developer.wordpress.org/reference/functions/is_singular/)()e se a caixa de seleção estiver marcada, retornamos false.
add_filter('widget_display_callback', function($instance, $widget, $args) {
if (is_singular() && $instance['awp-custom-setting']) {
return false;
}
return $instance;
}, 10, 3);Modificando as configurações ou saída do widget existente
Um filtro poderoso para utilizar para brincar com os widgets existentes é o [dynamic_sidebar_params](https://developer.wordpress.org/reference/hooks/dynamic_sidebar_params/). Dê uma olhada na página de documentação para ver quais parâmetros você pode modificar. Por exemplo, você pode adicionar classes personalizadas, modificar as strings before_widget, after_widgetou as before_titlee after_titleHTML. No entanto, isso se aplica a todos os widgets, também admin e frontend. E com este filtro você não tem acesso à instância do widget (configurações salvas) ou configurações do widget (por exemplo, tipo de widget).
Obviamente, precisamos pelo menos verificar nossas configurações personalizadas. Então, precisamos fazer algum código para buscar os valores que precisamos.
A primeira coisa que podemos fazer é acessar uma variável global $wp_registered_widgets. Este é um array que contém todos os widgets registrados e disponíveis. Usando esse registro, podemos usar o parâmetro do filtro para encontrar o widget específico em que estamos atualmente. Uma vez que encontramos o widget atual, temos acesso aos parâmetros do widget, como id_base– que, como vimos anteriormente, nos informa o tipo de widget.
Como você pode ver na fila #9, podemos finalmente verificar em que tipo de widget estamos atualmente. No código acima, eu retorno se o tipo de widget não for um widget de navegação, pois nossa configuração personalizada foi adicionada apenas para esses widgets.
Buscando configurações de widget salvas
Mas também precisamos buscar as configurações salvas por widget (incluindo nossa configuração personalizada). Todas as configurações salvas dos widgets são armazenadas no banco de dados de opções agrupadas por tipo de widget. Usando uma propriedade no registro do widget, podemos usar [get_option](https://developer.wordpress.org/reference/functions/get_option/)()para buscar as configurações salvas para o tipo de widget atual. O retorno será um array indexado onde precisamos usar mais um parâmetro do filtro para encontrar o índice atual (porque você pode adicionar vários do mesmo tipo de widget na mesma ou em barras laterais diferentes). É mais fácil mostrar com código do que explicar:
Finalmente conseguimos as configurações salvas do widget! No código de exemplo acima, na linha #9, verificamos se nossa caixa de seleção personalizada está ou não marcada.
Exemplos
Neste ponto, cabe a você o que você quer fazer. Você pode, por exemplo, renderizar uma saída após o título do widget, mas antes do conteúdo do widget:
Para casos de uso mais reais, você normalmente resolveria a maioria adicionando certos filtros neste ponto, chamando add_filter()neste ponto.
Abaixo está um exemplo de modificação dos argumentos do menu de navegação adicionando um filtro se nossa configuração estiver marcada. Se estiver desmarcado, garantimos que o filtro seja removido. O filtro para modificar os argumentos para renderizar um menu de navegação é widget_nav_menu_args. No código abaixo defini uma função para aplicar a este filtro que adiciona um novo argumento aos argumentos do menu; um caminhante:
...
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;
}O código acima é um exemplo de um caso de uso em que a caixa de seleção personalizada controla se deve ou não aplicar um menu walker ao menu. Excelente se você deseja que todos os menus sejam renderizados normalmente, mas deseja que a opção de widgets de menu específicos sejam renderizados de maneira diferente. O que o andador faz com a saída do menu é com você.
Veja abaixo o código completo para adicionar uma configuração personalizada a todos os menus de navegação, atualizá-la e aplicar um menu walker.
Espero que isso seja suficiente para você descobrir como codificar o que deseja fazer. Realmente depende do que você quer fazer e com que tipo de widget você está trabalhando. Como mencionado acima, geralmente a maioria das modificações pode ser resolvida adicionando filtros para fazer suas coisas no dynamic_sidebar_params.
Aqui está o código completo para adicionar uma caixa de seleção personalizada a todos os widgets do menu de navegação do WordPress para usar um menu walker registrado. (Código Walker não incluído)
Conclusão
Espero que este post tenha sido útil para resolver suas necessidades ou fornecer algumas dicas sobre como você pode fazer o que precisa fazer!