O WordPress permite usar as chamadas classes Walker para percorrer e exibir elementos em uma estrutura hierárquica. Neste post vamos aprender como criar, implementar e customizar nossa própria classe walker para customizar a saída do nosso menu.
O uso mais conhecido de personalização com classes Walker no WordPress é para menus, mas, na realidade, o WordPress usa classes Walker para vários casos, por exemplo, gerando hierarquias de taxonomia, hierarquias de comentários [wp_list_pages](https://developer.wordpress.org/reference/functions/wp_list_pages/)()e arquivos [wp_list_categories](https://developer.wordpress.org/reference/functions/wp_list_categories/)(). Todos eles estendem uma Walkerclasse geral. Vamos estender o Walker_Nav_Menuque é usado para menus no WordPress.
Como estendemos outra classe, precisamos apenas adicionar as funções que desejamos substituir. Se uma função não existir em nossa classe, o WordPress executará a função da classe pai’ (a classe que estendemos).
Preparação
Você pode adicionar sua classe walker em seus arquivos de plugin, temas function.phpou qualquer arquivo PHP incluído por functions.php(para um código mais limpo). Você começa definindo sua classe por um nome de sua escolha (certifique-se de que o nome da classe seja único, e isso inclui possíveis nomes de classe no núcleo do WordPress!) estendendo Walker_Nav_Menu:
class AWP_Menu_Walker extends Walker_Nav_Menu {
}Para dizer ao WordPress para usar nosso walker, definimos isso em nossas [wp_nav_menu](https://developer.wordpress.org/reference/functions/wp_nav_menu/)()chamadas. Esta função é responsável pela saída de um menu e você provavelmente tem pelo menos um em seu tema para o menu principal.
No array de argumentos para wp_nav_menu()você adiciona um novo elemento com a chave ‘walker’ e cria uma nova instância de sua classe walker assim:
Se você atualizar seu site, não deverá ver nenhuma alteração. Isso ocorre porque nossa classe não substitui nenhuma das funções do pai e, portanto, o WordPress simplesmente executa as funções normais do menu walker ao gerar o menu, assim como antes dissemos a ele para usar nosso walker.
A seguir estão as funções que você pode adicionar à sua classe walker personalizada para substituir as funções da classe parental Walker_Nav_Menu:
As quatro primeiras são funções que são simplesmente responsáveis pela saída, e todas elas exigem que você anexe a uma string – a primeira variável de parâmetro. É importante saber que você não faz echonada aqui, tudo deve ser construído como uma corda.
start_lvl
A função start_lvlé responsável pela saída do HTML para o início de um novo nível. Em suma, deve produzir o arquivo <ul>.
function start_lvl(&$output, $depth=0, $args=null) { }O primeiro parâmetro, $output– passado por referência, é a string à qual você anexará sua saída. $depthé um número inteiro sinalizando em que nível você está; 0 para nível superior, 1 para filho direto do nível superior e assim por diante. $argsé um objeto de todos os argumentos fornecidos em wp_nav_menu().
end_lvl
A end_lvlfunção é responsável pela saída do HTML para o final de um nível. Isso geralmente é apenas o fechamento </ul>.
function end_lvl(&$output, $depth=0, $args=null) { }Os parâmetros são exatamente os mesmos start_lvlacima.
start_el
Esta função é responsável pela saída do HTML de cada elemento. Em suma, deve gerar o início <li>e a <a>tag com o título do link dentro.
function start_el(&$output, $item, $depth=0, $args=null, $id=0) { }O primeiro argumento, $output, é como de costume a string à qual você anexará a saída. O segundo argumento, $item, é o objeto de item de menu – e é aqui que você buscará a maioria dos dados para a saída do item de menu. Se o link do menu for um item de menu de postagem, você obterá o objeto de postagem aqui. Independentemente do tipo de menu, você também terá alguns elementos úteis adicionais; como classes, url, titlee description.
O terceiro argumento, $depth, é um inteiro informando em que nível estamos. O nível 0 é o nível superior, 1 é filho direto do nível superior e assim por diante. O quarto argumento, $args, é um objeto de todos os argumentos fornecidos a wp_nav_menu(). O quinto parâmetro, $id, é o ID do item de menu atual.
end_el
A end_elfunção é responsável por emitir o fechamento de um elemento. Normalmente, seria apenas a saída da </li>tag.
function end_el(&$output, $item, $depth=0, $args=null) { }Os argumentos para end_elsão os mesmos start_elacima, exceto que a função não possui o quinto parâmetro, $id.
display_element
A função display_elementé uma função herdada da Walkerclasse geral e é a função responsável pela travessia. Esta é a função que chama todas as funções acima por sua vez.
Estou incluindo isso aqui porque em alguns casos, por exemplo, se você quiser evitar atravessar uma ramificação inteira, você usaria essa função para isso.
function display_element($element, &$children_elements, $max_depth, $depth, $args, &$output) { }O primeiro argumento, $element, é o objeto de item de menu – isso é o que é passado como $itemnas funções acima. O segundo argumento, $children_elements– passado por referência, contém todos os elementos filho que esta função percorrerá. $max_depth, o terceiro argumento, é um número inteiro que sinaliza a profundidade que devemos percorrer, e o quarto argumento, $depth, é a profundidade em que estamos atualmente. O quinto argumento, $args, são os argumentos passados para a função que chamou o walker (para menus seriam os argumentos fornecidos para wp_nav_menu()), e o argumento final, $output– passado por referência, é a saída que é passada como primeiro argumento em todos os das funções acima.
Modificando a saída de cada elemento
Na visão geral acima você deve ver que a função start_el()é a responsável pela saída do HTML para um único elemento de menu. Vamos começar substituindo essa função em nossa classe walker com um exemplo simples.
Exemplo: impedindo a adição de links para elementos ‘#’
Vamos nos certificar de que qualquer #link ‘ ‘ receba um <span>elemento em vez de uma tag de link, para evitar a atualização da página.
Iniciaremos o elemento anexando uma <li>tag a $output. Queremos ter certeza de que as classes padrão do WordPress (por exemplo ‘menu-item’, ‘menu-item-has-children’ etc), bem como as classes inseridas manualmente no editor de menu, sejam adicionadas ao nosso elemento de lista. Nós colamos as classes fornecidas como um array $item->classesusando a função PHP [implode](https://www.php.net/manual/en/function.implode.php)()separando cada elemento com um espaço.
Na linha #5-9 e #13-17 nós tratamos a saída condicional do elemento de encapsulamento. Emitimos uma <a>tag, a menos que a URL do elemento seja ‘ #‘ nesse caso, fornecemos uma <span>tag. Na linha #11 nós simplesmente produzimos o texto do link, que reside em $item->title.
Isso é tudo o que precisamos para garantir que todos os elementos de menu que tenham ‘ #‘ como URL não sejam clicáveis!
Se você estiver fazendo isso em um tema estilizado, lembre-se de que poderá perder algum estilo se o tema tiver estilizado a <a>tag diretamente. Você pode resolver isso alterando o estilo e possivelmente adicionando uma classe ao elemento span.
Como exemplo, outra coisa que você pode fazer aqui é gerar a descrição do menu. Isso existe, mas não está ativado como padrão. No editor de menus do WordPress, você precisa clicar em "Opções de tela" no canto superior direito e marcar para mostrar "Descrição":
Isso permite que o usuário insira uma descrição para cada elemento. Você pode produzir essa descrição em sua classe de walker. Digamos que você queira mostrar apenas a descrição dos itens de nível superior, pois isso faz parte do design do seu tema. Você pode simplesmente verificar se $itemtem uma descrição e se $depthé 0, assim:
Exemplo: adicionar acentos de lista suspensa
Um exemplo mais comum e útil é adicionar um “caret", um ícone que sinaliza que este item de menu possui um menu suspenso (tem elementos filhos).
Exemplo de acento circunflexo em ação – atrás de “Blog” e “Notícias”
Você precisará descobrir sua saída HTML de acento circunflexo. No meu caso estou gerando um <i>item com classes específicas para uma bela seta para baixo disponível pela biblioteca Fontawesome que fornece milhares de ícones. Você também deseja garantir que esse acento circunflexo seja gerado apenas em elementos que tenham filhos. A melhor maneira que encontrei para descobrir se o elemento atual tem filhos, é referenciando o objeto walker (sim, que é o nosso walker em si, mas também as classes que ele estende!) em $args, e verificando o boolean has_children. A saída de um acento circunflexo é tão simples quanto:
A classe walker completa ficaria assim:
E isso é tudo que você precisa para garantir que seu menu tenha bons ícones de acento circunflexo nos elementos pai e que #os links ‘ ‘ não sejam clicáveis.
Se você quiser que o ícone de acento circunflexo mude, por exemplo, em uma seta para cima quando o menu suspenso estiver ativo, você precisará adicioná-lo com Javascript ao seu tema.
Como os exemplos acima sugerem, você pode manipular a saída como quiser, com base em quaisquer condicionais. Você pode, por exemplo, modificar a saída com base na presença de uma determinada classe (por exemplo, uma classe inserida manualmente no editor de menus) procurando a classe em $item->classes, ou pode manipular (por exemplo, capitalizar) o texto do item de saída fornecido em $item->title.
Eu gostaria de mencionar outra coisa útil. Lembre-se de que $args contém todos os argumentos fornecidos para wp_nav_menu(). Isso inclui, por exemplo theme_location, e outros, portanto, se você puder modificar a saída apenas para locais específicos do tema – por exemplo, menu principal. Mas você pode realmente fornecer quaisquer argumentos personalizados!
Digamos que você esteja exibindo o mesmo menu várias vezes, por exemplo, um para desktop e novamente para celular. Ou você quer que seu walker manipule os itens apenas quando eles são exibidos wp_nav_menu()em seu tema, e não quando o menu é adicionado por meio de um widget? Talvez você queira que seu andador lide com a saída de maneira diferente nesses casos?
Você pode fornecer quaisquer argumentos personalizados para wp_nav_menu(). Como um exemplo simples, adicionarei um booleano ‘ show_carets‘ aos argumentos para garantir que os acentos circunflexos sejam adicionados apenas nos casos em que eu os desejar – em vez de minha classe walker adicionar acentos circunflexos a todos os menus.
Então, posso simplesmente alterar meu código de adição de acento circunflexo acima (linha # 19-21) para verificar se show_caretsestá ou não presente e verdadeiro em $args, assim:
Você pode adicionar quaisquer argumentos que desejar, garantindo que seu andador personalize apenas os menus que você deseja. Por exemplo, booleanos simples para diferentes casos, por exemplo is_mobile_menu, ou qualquer outra coisa que você precise.
E é isso. Sinta-se à vontade para experimentar e deixe-me saber se você tiver alguma dúvida ou sugestão abaixo!