{"id":233515,"date":"2023-02-15T13:31:00","date_gmt":"2023-02-15T10:31:00","guid":{"rendered":"https:\/\/wordpress.mediadoma.com\/?p=233515"},"modified":"2022-11-11T00:06:39","modified_gmt":"2022-11-10T21:06:39","slug":"como-adicionar-configuracoes-personalizadas-a-um-widget-existente-no-wordpress","status":"publish","type":"post","link":"https:\/\/wordpress.mediadoma.com\/pt-pt\/como-adicionar-configuracoes-personalizadas-a-um-widget-existente-no-wordpress\/","title":{"rendered":"Como adicionar configura\u00e7\u00f5es personalizadas a um widget existente no WordPress"},"content":{"rendered":"\n

Neste post, aprenderemos como adicionar seu HTML personalizado e configura\u00e7\u00f5es a qualquer um dos widgets padr\u00e3o do WordPress ou outros. Usando essas configura\u00e7\u00f5es, aprenderemos diferentes truques sobre como manipular o comportamento dos widgets de acordo.<\/p>\n

A primeira parte; adicionar e salvar suas configura\u00e7\u00f5es personalizadas \u00e9 bastante f\u00e1cil. A segunda parte depende do que voc\u00ea quer fazer especificamente, e depende de qual widget voc\u00ea est\u00e1 manipulando. Neste post inclu\u00ed dois exemplos; pular um widget dependendo de uma configura\u00e7\u00e3o (para adicionar configura\u00e7\u00f5es para controlar a visibilidade do widget em certos casos) e manipular os argumentos de menu do widget de navega\u00e7\u00e3o do WordPress. O exemplo dado para a segunda parte deve lhe dar uma boa pista de como voc\u00ea pode lidar com o que deseja fazer.<\/p>\n

Adicionando configura\u00e7\u00f5es personalizadas a qualquer widget<\/h2>\n

Para adicionar configura\u00e7\u00f5es personalizadas a widgets existentes, usamos uma a\u00e7\u00e3o chamada [in_widget_form](https:\/\/developer.wordpress.org\/reference\/hooks\/in_widget_form\/)<\/code>. Esta a\u00e7\u00e3o \u00e9 aplicada \u00e0 fun\u00e7\u00e3o de todos os widgets form()<\/code>, que \u00e9 a fun\u00e7\u00e3o respons\u00e1vel por renderizar a parte admin do widget.<\/p>\n

Com esse filtro, obtemos tr\u00eas par\u00e2metros, mas estamos realmente interessados \u200b\u200bapenas no primeiro e no terceiro. A primeira \u00e9 a inst\u00e2ncia 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\u00e2metro \u00e9 uma matriz de configura\u00e7\u00f5es salvas do widget, que precisamos usar para verificar o estado salvo anterior de nossas configura\u00e7\u00f5es.<\/p>\n

O c\u00f3digo abaixo adicionar\u00e1 uma caixa de sele\u00e7\u00e3o com o nome da configura\u00e7\u00e3o ‘ awp-custom-setting<\/code>‘. Ajuste o nome e o HTML para a entrada de que voc\u00ea precisa. O importante \u00e9 usar $widget->get_field_name()<\/code>para adicionar IDs e atributos adequados name<\/code>a todas as suas entradas. O valor de suas entradas deve ser preenchido com o que foi salvo anteriormente, e isso \u00e9 algo que voc\u00ea encontrar\u00e1 no par\u00e2metro $instance<\/code>. Para caixas de sele\u00e7\u00e3o, voc\u00ea pode usar a fun\u00e7\u00e3o do WordPress [checked](https:\/\/developer.wordpress.org\/reference\/functions\/checked\/)()<\/code>para gerar o atributo verificado.<\/p>\n

add_action('in_widget_form', function($widget, $return, $instance) {\n    ?>\n    <p>\n        <input type=\"checkbox\" class=\"checkbox\" name=\"<?php echo $widget->get_field_name('awp-custom-setting'); ?>\" id=\"<?php echo $widget->get_field_name('awp-custom-setting'); ?>\" <?php checked(isset($instance['awp-custom-setting'])? $instance['awp-custom-setting']: 0); ?> \/>\n        <label for=\"<?php echo $widget->get_field_name('awp-custom-setting'); ?>\"><?php __('Activate something', 'txtdomain'); ?><\/label>\n    <\/p>\n    <?php\n}, 10, 3);<\/code><\/pre>\n
Depois de adicionar isso ao c\u00f3digo do seu tema functions.php<\/code>ou plugin, todos os widgets agora devem receber uma caixa de sele\u00e7\u00e3o no final do formul\u00e1rio no admin.<\/p>\n
Widgets espec\u00edficos de destino<\/h3>\n
Se voc\u00ea deseja aplicar suas configura\u00e7\u00f5es apenas a um ou alguns widgets espec\u00edficos, pode comparar a propriedade id_base<\/code>no $widget<\/code>objeto. Voc\u00ea precisar\u00e1 saber qual \u00e9 o ID base \u2013 se n\u00e3o tiver certeza, simplesmente fa\u00e7a um var_dump($widget->id_base)<\/code>dentro do gancho, salve e verifique a sa\u00edda de cada widget no admin. Por exemplo, o widget Navigation tem a base nav_menu<\/code>de ID e o widget Archives tem archives<\/code>.<\/p>\n
No exemplo abaixo verificamos se o widget \u00e9 um widget de Navega\u00e7\u00e3o. Se n\u00e3o for, a fun\u00e7\u00e3o \u00e9 cancelada com um return<\/code>. Somente widgets de navega\u00e7\u00e3o ter\u00e3o a caixa de sele\u00e7\u00e3o personalizada:<\/p>\n
add_action('in_widget_form', function($widget, $return, $instance) {\n    if ($widget->id_base != 'nav_menu') {\n        return;\n    }\n\u00a0\n    ?>\n    <p>\n    ...<\/code><\/pre>\n
Voc\u00ea deve obter a configura\u00e7\u00e3o em admin assim:<\/p>\n
\"Como<\/a><\/p>\n
Ent\u00e3o a configura\u00e7\u00e3o foi adicionada, por\u00e9m no momento suas configura\u00e7\u00f5es n\u00e3o est\u00e3o sendo salvas. Vamos consertar isso.<\/p>\n
Salvando suas configura\u00e7\u00f5es personalizadas<\/h2>\n
Precisamos nos conectar \u00e0 update()<\/code>fun\u00e7\u00e3o do widget para atualizar nossas configura\u00e7\u00f5es personalizadas.<\/p>\n
Para isso usamos o filtro [widget_update_callback](https:\/\/developer.wordpress.org\/reference\/hooks\/widget_update_callback\/)<\/code>. O processo de salvar nossas configura\u00e7\u00f5es \u00e9 exatamente como voc\u00ea faria quando escreve uma classe de widget. O filtro fornece tr\u00eas par\u00e2metros; o primeiro \u00e9 o array de inst\u00e2ncias que ser\u00e1 salvo. O segundo par\u00e2metro \u00e9 o estado que foi postado ao salvar o widget e o terceiro \u00e9 o estado antigo. Precisamos ter certeza de buscar nossos novos valores do segundo par\u00e2metro e adicion\u00e1-los ao primeiro.<\/p>\n
\u00c9 assim que atualizar\u00edamos o estado de nossa caixa de sele\u00e7\u00e3o; como queremos salvar um valor true<\/code>ou false<\/code>:<\/p>\n
add_filter('widget_update_callback', function($instance, $new_instance, $old_instance) {\n    $instance['awp-custom-setting'] = isset($new_instance['awp-custom-setting']);\n    return $instance;\n}, 10, 3);<\/code><\/pre>\n
Lembre-se de ajustar os nomes de entrada aos seus pr\u00f3prios nomes de configura\u00e7\u00e3o. Se voc\u00ea estiver adicionando v\u00e1rias entradas, precisar\u00e1 repetir isso para cada uma.<\/p>\n
Agora voc\u00ea deve ver que suas configura\u00e7\u00f5es personalizadas est\u00e3o sendo salvas no admin!<\/p>\n
Usando configura\u00e7\u00f5es de widget personalizadas salvas<\/h2>\n
Como mencionado anteriormente, esta parte realmente depende do que voc\u00ea deseja que suas configura\u00e7\u00f5es fa\u00e7am. Infelizmente, n\u00e3o \u00e9 t\u00e3o simples porque a maioria dos widgets n\u00e3o adiciona filtros ou ganchos em suas sa\u00eddas. Vamos come\u00e7ar com algo simples; evite renderizar o widget dependendo das configura\u00e7\u00f5es.<\/p>\n
Impedir o widget de renderiza\u00e7\u00e3o dependendo da configura\u00e7\u00e3o personalizada<\/h3>\n
Digamos que voc\u00ea esteja adicionando configura\u00e7\u00f5es para quando o widget deve estar vis\u00edvel; por exemplo, escond\u00ea-lo em determinados modelos (ocultar no modelo de resultados de pesquisa, mas mostrar na p\u00e1gina inicial e no single) ou reagir a outros estados do WordPress.<\/p>\n
Para isso podemos usar o filtro [widget_display_callback](https:\/\/developer.wordpress.org\/reference\/hooks\/widget_display_callback\/)<\/code>. Tudo o que precisamos fazer \u00e9 verificar o par\u00e2metro de inst\u00e2ncia fornecido para nossa configura\u00e7\u00e3o e retornar false<\/code>se n\u00e3o quisermos renderizar o widget.<\/p>\n
Este c\u00f3digo simples evitar\u00e1 renderizar o widget se a caixa de sele\u00e7\u00e3o personalizada que adicionamos acima estiver marcada:<\/p>\n
add_filter('widget_display_callback', function($instance, $widget, $args) {\n    if ($instance['awp-custom-setting']) {\n        return false;\n    }\n    return $instance;\n}, 10, 3);<\/code><\/pre>\n
Voc\u00ea provavelmente quer comparar outros estados. Este \u00e9 um exemplo simples em que nossa caixa de sele\u00e7\u00e3o \u00e9 uma caixa de sele\u00e7\u00e3o para "Ocultar em visualiza\u00e7\u00f5es de postagens \u00fanicas". Simplesmente verificamos se estamos atualmente em uma visualiza\u00e7\u00e3o de postagem \u00fanica com [is_singular](https:\/\/developer.wordpress.org\/reference\/functions\/is_singular\/)()<\/code>e se a caixa de sele\u00e7\u00e3o estiver marcada, retornamos false<\/code>.<\/p>\n
add_filter('widget_display_callback', function($instance, $widget, $args) {\n    if (is_singular() && $instance['awp-custom-setting']) {\n        return false;\n    }\n    return $instance;\n}, 10, 3);<\/code><\/pre>\n
Modificando as configura\u00e7\u00f5es ou sa\u00edda do widget existente<\/h3>\n
Um filtro poderoso para utilizar para brincar com os widgets existentes \u00e9 o [dynamic_sidebar_params](https:\/\/developer.wordpress.org\/reference\/hooks\/dynamic_sidebar_params\/)<\/code>. D\u00ea uma olhada na p\u00e1gina de documenta\u00e7\u00e3o para ver quais par\u00e2metros voc\u00ea pode modificar. Por exemplo, voc\u00ea pode adicionar classes personalizadas, modificar as strings before_widget<\/code>, after_widget<\/code>ou as before_title<\/code>e after_title<\/code>HTML. No entanto, isso se aplica a todos os widgets, tamb\u00e9m admin e frontend. E com este filtro voc\u00ea n\u00e3o tem acesso \u00e0 inst\u00e2ncia do widget (configura\u00e7\u00f5es salvas) ou configura\u00e7\u00f5es do widget (por exemplo, tipo de widget).<\/p>\n
Obviamente, precisamos pelo menos verificar nossas configura\u00e7\u00f5es personalizadas. Ent\u00e3o, precisamos fazer algum c\u00f3digo para buscar os valores que precisamos.<\/p>\n
A primeira coisa que podemos fazer \u00e9 acessar uma vari\u00e1vel global $wp_registered_widgets<\/code>. Este \u00e9 um array que cont\u00e9m todos os widgets registrados e dispon\u00edveis. Usando esse registro, podemos usar o par\u00e2metro do filtro para encontrar o widget espec\u00edfico em que estamos atualmente. Uma vez que encontramos o widget atual, temos acesso aos par\u00e2metros do widget, como id_base<\/code>\u2013 que, como vimos anteriormente, nos informa o tipo de widget.<\/p>\n
add_filter('dynamic_sidebar_params', function($params) {\n    global $wp_registered_widgets;\n\u00a0\n    $this_widget_id = $params[0]['widget_id'];  \/\/ Current widget ID\n    $this_widget = $wp_registered_widgets[$this_widget_id];\n    $widget_object = $this_widget['callback'][0];  \/\/ Current widget object\n\u00a0\n    \/\/ With $widget_object we have access to e.g. id_base for checking type of widget\n    if ($widget_object->id_base != 'nav_menu') {\n        return $params;\n    }\n\u00a0\n    return $params;\n});<\/code><\/pre>\n
Como voc\u00ea pode ver na fila #9<\/code>, podemos finalmente verificar em que tipo de widget estamos atualmente. No c\u00f3digo acima, eu retorno se o tipo de widget n\u00e3o for um widget de navega\u00e7\u00e3o, pois nossa configura\u00e7\u00e3o personalizada foi adicionada apenas para esses widgets.<\/p>\n
Buscando configura\u00e7\u00f5es de widget salvas<\/h3>\n
Mas tamb\u00e9m precisamos buscar as configura\u00e7\u00f5es salvas por widget (incluindo nossa configura\u00e7\u00e3o personalizada). Todas as configura\u00e7\u00f5es salvas dos widgets s\u00e3o armazenadas no banco de dados de op\u00e7\u00f5es agrupadas por tipo de widget. Usando uma propriedade no registro do widget, podemos usar [get_option](https:\/\/developer.wordpress.org\/reference\/functions\/get_option\/)()<\/code>para buscar as configura\u00e7\u00f5es salvas para o tipo de widget atual. O retorno ser\u00e1 um array indexado onde precisamos usar mais um par\u00e2metro do filtro para encontrar o \u00edndice atual (porque voc\u00ea pode adicionar v\u00e1rios do mesmo tipo de widget na mesma ou em barras laterais diferentes). \u00c9 mais f\u00e1cil mostrar com c\u00f3digo do que explicar:<\/p>\n
    ...\n    if ($widget_object->id_base != 'nav_menu') {\n        return $params;\n    }\n\u00a0\n    $all_settings = get_option($widget_object->option_name);\n    $saved_settings = $all_settings[$params[1]['number']];\n    if ($saved_settings['my-custom-thing']) {\n        \/\/ Do your thing\n    }\n\u00a0\n    return $params;\n});<\/code><\/pre>\n
Finalmente conseguimos as configura\u00e7\u00f5es salvas do widget! No c\u00f3digo de exemplo acima, na linha #9<\/code>, verificamos se nossa caixa de sele\u00e7\u00e3o personalizada est\u00e1 ou n\u00e3o marcada.<\/p>\n
Exemplos<\/h3>\n
Neste ponto, cabe a voc\u00ea o que voc\u00ea quer fazer. Voc\u00ea pode, por exemplo, renderizar uma sa\u00edda ap\u00f3s o t\u00edtulo do widget, mas antes do conte\u00fado do widget:<\/p>\n
    ...\n    if ($saved_settings['my-custom-thing']) {\n        $params[0]['after_title'] .= '<div>This appears before widget content<\/div>';\n    }\n    ...<\/code><\/pre>\n
Para casos de uso mais reais, voc\u00ea normalmente resolveria a maioria adicionando certos filtros neste ponto, chamando add_filter()<\/code>neste ponto.<\/p>\n
Abaixo est\u00e1 um exemplo de modifica\u00e7\u00e3o dos argumentos do menu de navega\u00e7\u00e3o adicionando um filtro se nossa configura\u00e7\u00e3o estiver marcada. Se estiver desmarcado, garantimos que o filtro seja removido. O filtro para modificar os argumentos para renderizar um menu de navega\u00e7\u00e3o \u00e9 widget_nav_menu_args<\/code>. No c\u00f3digo abaixo defini uma fun\u00e7\u00e3o para aplicar a este filtro que adiciona um novo argumento aos argumentos do menu; um caminhante:<\/p>\n
    ...\n    if ($saved_settings['my-custom-thing']) {\n        add_filter('widget_nav_menu_args', 'awp_add_menu_walker', 10, 3);\n    } else {\n        remove_filter('widget_nav_menu_args', 'awp_add_menu_walker', 10);\n    }\n    return $params;\n});\nfunction awp_add_menu_walker($nav_menu_args, $nav_menu, $args) {\n    $nav_menu_args['walker'] = new AWP_Custom_Walker();\n    return $nav_menu_args;\n}<\/code><\/pre>\n
O c\u00f3digo acima \u00e9 um exemplo de um caso de uso em que a caixa de sele\u00e7\u00e3o personalizada controla se deve ou n\u00e3o aplicar um menu walker ao menu. Excelente se voc\u00ea deseja que todos os menus sejam renderizados normalmente, mas deseja que a op\u00e7\u00e3o de widgets de menu espec\u00edficos sejam renderizados de maneira diferente. O que o andador faz com a sa\u00edda do menu \u00e9 com voc\u00ea.<\/p>\n
Veja abaixo o c\u00f3digo completo para adicionar uma configura\u00e7\u00e3o personalizada a todos os menus de navega\u00e7\u00e3o, atualiz\u00e1-la e aplicar um menu walker.<\/p>\n
Espero que isso seja suficiente para voc\u00ea descobrir como codificar o que deseja fazer. Realmente depende do que voc\u00ea quer fazer e com que tipo de widget voc\u00ea est\u00e1 trabalhando. Como mencionado acima, geralmente a maioria das modifica\u00e7\u00f5es pode ser resolvida adicionando filtros para fazer suas coisas no dynamic_sidebar_params<\/code>.<\/p>\n
Exemplo completo: configura\u00e7\u00e3o de caixa de sele\u00e7\u00e3o personalizada em widgets de navega\u00e7\u00e3o para aplicar um menu walker<\/h2>\n
Aqui est\u00e1 o c\u00f3digo completo para adicionar uma caixa de sele\u00e7\u00e3o personalizada a todos os widgets do menu de navega\u00e7\u00e3o do WordPress para usar um menu walker registrado. (C\u00f3digo Walker n\u00e3o inclu\u00eddo)<\/p>\n
\/\/ Add custom setting to menu widgets\nadd_action('in_widget_form', function($widget, $return, $instance) {\n    \/\/ Add setting only to menu widgets\n    if ($widget->id_base != 'nav_menu') {\n        return;\n    }\n\u00a0\n    ?>\n    <p>\n        <input type=\"checkbox\" class=\"checkbox\" name=\"<?php echo $widget->get_field_name('activate-walker'); ?>\" id=\"<?php echo $widget->get_field_name('activate-walker'); ?>\" <?php checked(isset($instance['activate-walker'])? $instance['activate-walker']: 0); ?> \/>\n        <label for=\"<?php echo $widget->get_field_name('activate-walker'); ?>\"><?php __('Activate walker', 'txtdomain'); ?><\/label>\n    <\/p>\n    <?php\n}, 10, 3);\n\u00a0\n\u00a0\n\/\/ Update custom setting\nadd_filter('widget_update_callback', function($instance, $new_instance, $old_instance) {\n    $instance['activate-walker'] = isset($new_instance['activate-walker']);\n    return $instance;\n}, 10, 3);\n\u00a0\n\u00a0\n\/\/ Filter sidebar params to add filter if custom setting was activated\nadd_filter('dynamic_sidebar_params', function($params) {\n    global $wp_registered_widgets;\n\u00a0\n    $this_widget_id = $params[0]['widget_id'];\n    $this_widget = $wp_registered_widgets[$this_widget_id];\n    $widget_object = $this_widget['callback'][0];\n\u00a0\n    \/\/ Bail if not a menu widget\n    if ($widget_object->id_base != 'nav_menu') {\n        return $params;\n    }\n\u00a0\n    $all_settings = get_option($widget_object->option_name);\n    $saved_settings = $all_settings[$params[1]['number']];\n\u00a0\n    if ($saved_settings['activate-walker']) {\n        add_filter('widget_nav_menu_args', 'awp_add_menu_walker', 10, 3);\n    } else {\n        remove_filter('widget_nav_menu_args', 'awp_add_menu_walker', 10);\n    }\n\u00a0\n    return $params;\n});\n\u00a0\n\u00a0\n\/\/ Filter nav menu arguments to add walker\nfunction awp_add_menu_walker($nav_menu_args, $nav_menu, $args) {\n    $nav_menu_args['walker'] = new AWP_Custom_Walker();\n    return $nav_menu_args;\n}<\/code><\/pre>\n
Conclus\u00e3o<\/h2>\n
Espero que este post tenha sido \u00fatil para resolver suas necessidades ou fornecer algumas dicas sobre como voc\u00ea pode fazer o que precisa fazer!<\/p>\n
Fonte de grava\u00e7\u00e3o:  awhitepixel.com<\/a><\/div><\/p>\n","protected":false},"excerpt":{"rendered":"
Como adicionar configura\u00e7\u00f5es personalizadas a qualquer um dos widgets padr\u00e3o do WordPress. Com essas configura\u00e7\u00f5es, aprenderemos a manipular o comportamento dos widgets de acordo.<\/p>\n","protected":false},"author":1,"featured_media":223663,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":"","_wp_rev_ctl_limit":""},"categories":[930,898,898,722,722,837,1110,806,806,837,930,846,846,867,867],"tags":[1170],"class_list":["post-233515","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-assuntos","category-codigo-2","category-desenvolvedor","category-guia-para-iniciantes","category-n-a","category-php-8","category-tutoriais","category-wordpress-8","tag-affiai-pt-pt"],"_links":{"self":[{"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/posts\/233515","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/comments?post=233515"}],"version-history":[{"count":0,"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/posts\/233515\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/media\/223663"}],"wp:attachment":[{"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/media?parent=233515"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/categories?post=233515"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/wordpress.mediadoma.com\/pt-pt\/wp-json\/wp\/v2\/tags?post=233515"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}