Como criar e personalizar trechos do WordPress

Trecho é um texto opcional associado a um post. Na maioria das vezes, é usado como o resumo do post. Se você estiver usando o novo editor, verá que existe uma opção na barra lateral chamada Trecho :

Se não aparecer, talvez seja necessário habilitar a opção nas configurações do Gutenberg. Clique no ícone de reticências no canto superior direito do editor e depois em Opções :

Em seguida, procure por Trecho e habilite-o:

Dependendo de como o seu tema está configurado, o trecho aparecerá ao olhar seus posts no blog, os resultados de uma pesquisa, etc. Por exemplo, em nosso blog você pode ver como todos os nossos posts são apresentados com seus respectivos trechos:

Agora, é sempre obrigatório escrever esse trecho? Se não o fizermos, o que o WordPress faz? Mostra alguma coisa ou nada? Bem, vamos responder a essas perguntas e examinar mais de perto as opções que o WordPress nos oferece para personalizar trechos.

Como funcionam os trechos do WordPress

O WordPress tem duas funções para obter o trecho de um post: get_the_excerpt e the_excerpt . Ambos são definidos em wp-includes/post-template.php e se você der uma olhada no código fonte deles você descobrirá que tudo que the_excerpt faz é echo o resultado de get_the_excerpt (depois de filtrá-lo com the_excerpt ). Então, essencialmente, podemos dizer aproximadamente que a única coisa que você precisa entender para saber como os trechos funcionam no WordPress é a função get_the_excerpt .

Como você pode ver, get_the_excerpt é extremamente simples:

 function get_the_excerpt( $post = null ) { // ... $post = get_post( $post ); if ( empty( $post ) ) { return ''; } // ... return apply_filters( 'get_the_excerpt', $post->post_excerpt, $post ); }

Basicamente, ele carrega um post (se você não definir um, ele usa o post disponível no loop do WordPress) e retorna seu atributo post_excerpt . Então parece que nenhum trecho significa que o WordPress não mostrará nada no final, certo?

Não tão rápido, amigo.

Observe que esta função não retorna o valor de post_excerpt diretamente. Em vez disso, ele o filtra usando um novo filtro: get_the_excerpt. Portanto, se houver alguma ação associada a esse filtro, o resultado final pode mudar e não ser mais a string vazia…

E, de fato, é isso que está acontecendo aqui! Se não escrevermos um trecho para um determinado post, é isso que veremos no front-end:

as primeiras palavras do nosso post serão o trecho que o WordPress gera.

A função wp_trim_excerpt

Se fizermos uma busca rápida no código fonte do WordPress veremos que, por padrão, existe apenas uma única ação associada ao filtro get_the_excerpt . Especificamente, em wp-includes/default-filters.php vemos que uma função chamada wp_trim_excerpt está ligada.

De acordo com a documentação do WordPress, wp_trim_excerpt é responsável por gerar um trecho com no máximo 55 palavras e reticências anexadas, se necessário. E aqui está a chave: a função considera que gerar um trecho “é necessário” se já não houver um (o que, em geral, equivale a dizer que o usuário não escreveu o trecho no editor). Você pode ver isso no código-fonte da função:

 function wp_trim_excerpt( $text = '', $post = null ) { $raw_excerpt = $text; if ( '' == $text ) { $post = get_post( $post ); $text = get_the_content( '', false, $post ); // [...] » Generates the excerpt using the post content } return apply_filters( 'wp_trim_excerpt', $text, $raw_excerpt ); }

Ver? Se não houver trecho ( $text é a string vazia), recupere o conteúdo do post atual ( get_the_content de $post ) e use-o para gerar um trecho.

A partir deste ponto, você pode continuar cavando e descobrir como o WordPress realmente gera o código-fonte. No entanto, acho que você já entendeu a ideia, então vamos dar uma olhada na documentação novamente, pois ela lança alguma luz sobre este tópico:

Retorna um máximo de 55 palavras com reticências anexadas, se necessário. O limite de 55 palavras pode ser modificado por plugins/temas usando o filtro excerpt_length . A string ' […]' pode ser modificada por plugins/temas usando o filtro excerpt_more .

Documentação wp_trim_excerpt

Então agora você sabe tudo o que precisa saber para personalizar totalmente os trechos automáticos que o WordPress gera para seus posts.

Como personalizar trechos automáticos

Vamos dar uma olhada em alguns exemplos de como podemos usar os filtros que vimos ao longo do post de hoje para personalizar trechos automáticos. A propósito, lembre-se que para adicionar qualquer uma dessas modificações ao seu site você provavelmente precisará criar um plugin.

a) Como alterar o número de palavras que quero em meus trechos

Este é um dos mais simples. Já vimos que temos à nossa disposição o filtro excerpt_length para escolher quantas palavras queremos em nossos excertos, então vamos usá-lo:

 function nelio_100_word_excerpts( $length ) { if ( is_admin() ) { return $length; } return 100; } add_filter( 'excerpt_length', 'nelio_100_word_excerpts', 99 );

Observe que a primeira coisa que fazemos em nossa função é ter certeza de que estamos no front-end. Se estivermos no Dashboard ( is_admin ), é melhor não fazermos nada com nossos trechos. Assim que tivermos certeza de que estamos em um “ambiente seguro”, só precisamos retornar nosso número mágico. No meu caso: 100 palavras.

b) Como alterar o texto que aparece após uma extração automática

Este também é extremamente fácil porque já vimos que existe um filtro para ele:

 function nelio_clickable_read_more( $more ) { if ( is_admin() ) { return $more; } return sprintf( '<a href="%s">Tell me more!</a>', esc_url( get_the_permalink() ) ); } add_filter( 'excerpt_more', 'nelio_clickable_read_more', 99 );

Nesse caso, tudo o que fazemos é retornar o texto “Diga-me mais!” após o resumo e faça um link para que os usuários possam clicar nele.

c) Como limitar o comprimento de um trecho a um certo número de caracteres

A função wp_trim_words possui um filtro com o mesmo nome que podemos usar para modificar o trecho final que o WordPress usa. Então vamos usar:

 function nelio_140_char_excerpts( $excerpt, $raw_excerpt ) { if ( is_admin() ) { return $excerpt; } if ( '' !== $raw_excerpt ) { return $excerpt; } return mb_substr( $excerpt, 0, 140 ); } add_filter( 'wp_trim_excerpt', 'nelio_140_char_excerpts', 99, 2 );

O filtro wp_trim_words se aplica a trechos automáticos e definidos pelo usuário. No meu exemplo, estou interessado apenas em modificar trechos que foram gerados automaticamente, então preciso adicionar uma nova condição. Se você se lembra, wp_trim_words só gera um trecho automático se o trecho original estiver vazio, então tudo que você precisa fazer é verificar isso para obter o resultado desejado.

Por outro lado, observe que usei mb_substr em vez da função clássica substr . Se você está se perguntando por que, o motivo é simples: se você escrever em seu blog em um idioma diferente do inglês, provavelmente estará usando caracteres de vários bytes, e encurtar strings de vários bytes com substr pode dar errado. Leia a documentação do PHP para mais informações sobre isso.

d) Como criar trechos com o primeiro parágrafo do conteúdo

E por fim, um exemplo de como criar um trecho usando exatamente o primeiro parágrafo do seu post. Sem explicação desta vez, então preste atenção no que estou fazendo:

 function nelio_first_paragraph_excerpts( $excerpt, $raw_excerpt ) { if ( is_admin() ) { return $excerpt; } if ( '' !== $raw_excerpt ) { return $excerpt; } $content = apply_filters( 'the_content', get_the_content() ); return substr( $content, 0, strpos( $content, '</p>' ) + 4 ); } add_filter( 'wp_trim_excerpt', 'nelio_first_paragraph_excerpts', 99, 2 );

Resumidamente…

O grande poder do WordPress está em sua extensibilidade. Hoje vimos em detalhes como o WordPress gera trechos de posts e todos os filtros e funções que oferece para personalizar o resultado final de acordo com suas necessidades.

Espero que tenham gostado do post de hoje. Compartilhe com seus amigos para que mais pessoas conheçam as vantagens do WordPress!

Imagem em destaque de Aaron Burden no Unsplash.