Entendendo os códigos de acesso do WordPress

Se você usa o WordPress há algum tempo, provavelmente já usou alguns códigos de acesso.

Shortcodes são pequenos trechos úteis que permitem inserir algum tipo de funcionalidade especial em seu conteúdo que de outra forma não seria possível. Por exemplo: muitos plug-ins de galeria de imagens e slider fornecem um código de acesso que você pode simplesmente inserir em seu conteúdo em qualquer lugar que desejar para que as imagens apropriadas apareçam lá. Shortcodes geralmente se parecem com isto:

[example shortcode]

Em outras palavras: códigos de acesso fazem com que algo especial aconteça onde quer que sejam colocados em seu texto.
Mas você não está limitado a códigos de acesso pré-definidos; você pode definir códigos de acesso personalizados para fazer o que quiser! Eles podem ser simples, complexos ou qualquer coisa intermediária.

Nesta série, começaremos com um código de acesso simples e trabalharemos até alguns exemplos mais intrincados (e ainda mais úteis!).

Nota: vamos trabalhar principalmente com PHP aqui, especificamente no arquivo functions.php do seu tema. Se você não estiver usando um tema filho (ou um tema inicial/personalizado que pode ser editado sem medo de que as atualizações substituam suas alterações), convém criar um tema filho antes de começar.

Observe também: você não precisa de nenhum conhecimento de PHP para ler este post, mas saber pelo menos o básico ajudará. O código envolvido aqui é bastante simples e tentamos torná-lo o mais fácil possível de copiar e personalizar. Explicaremos cada parte do código à medida que avançamos, mas se você for completamente novo no PHP do tema WordPress, esteja ciente de que um pouco de código incorreto em seu arquivo functions.php pode danificar o site.

Um Exemplo Útil de Shortcode Simples

Digamos que queremos um shortcode que injete uma seção especial de informações do autor em uma postagem, como esta:

Em vez de criar e estilizar a caixa, a imagem e o texto no editor visual do WordPress, criaremos apenas um shortcode para gerar tudo isso com um simples snippet!

(Observação: o WordPress tem maneiras melhores de trabalhar com perfis de autor, mas vamos nos ater a este exemplo porque ele demonstra bem como é fácil usar códigos de acesso para colocar blocos específicos de conteúdo em uma página.)

Etapa 1: adicione o Shortcode no arquivo functions.php do seu tema

Você usará a função add_shortcode para dar um nome ao seu shortcode e informar ao WordPress o que ele deve fazer sempre que o shortcode for usado. Adicione esta linha ao arquivo functions.php do seu tema:

 [php]add_shortcode( 'author_bio', 'create_author_bio' );[/php]

Realmente não importa onde dentro de functions.php , mas para evitar conflitos, recomendamos colocá-lo bem no final. (Se o arquivo terminar com uma tag ?> de fechamento, ele deve ir logo antes disso, não depois.)

Antes de prosseguirmos, vamos quebrar essa linha um pouco, para entendermos o que realmente está acontecendo aqui. Os dois pedaços de texto, ou “argumentos”, dentro dos parênteses não são realmente especiais; são apenas nomes. Vamos ver o que cada um significa:

1. O primeiro argumento: neste caso, author_bio – informa ao WordPress o nome real do seu shortcode. Este será o texto que os usuários podem digitar, entre colchetes, para usar o shortcode. Assim, com este código escrito, [author_bio] será nosso código curto para acionar nossa caixa de biografia do autor.
   Este texto pode ser qualquer coisa, mas é sempre melhor tentar ser único. Dessa forma, você não correrá o risco de seu nome de shortcode entrar em conflito com o de outra pessoa de outro plugin ou tema instalado.
2. O segundo argumento: neste caso, create_author_bio – aponta o WordPress para a função PHP real que deve ser executada sempre que este shortcode for usado. Criaremos essa função na próxima etapa; por enquanto, estamos apenas informando ao WordPress qual será seu nome. (Esse nome também deve ser exclusivo, para evitar conflitos.)

Então, se ajudar, você pode pensar no código assim:

 [php]add_shortcode( 'when_you_see_THIS_shortcode', 'do_THIS' );[/php]

Se você estiver interessado em mais detalhes minuciosos, confira a entrada add_shortcode Codex.

Passo 2: Crie a função para lidar com o Shortcode

Agora precisamos realmente criar a função que acabamos de nomear!

Como acabamos de dizer ao WordPress na última etapa que o nome da nossa função é create_author_bio, nosso código agora deve ficar assim, uma vez que adicionamos a nova função:

 [php]add_shortcode( 'author_bio', 'create_author_bio' ); function create_author_bio(){ //Code goes here! }[/php]

Você pode notar que esta função ainda não faz nada; tudo o que está dentro dele é um comentário. Cuidaremos disso na próxima etapa. Por enquanto, queremos apenas ressaltar que realmente existem apenas duas partes aqui: o registro do shortcode e a função que acontece sempre que ele é usado. WordPress PHP pode parecer intimidante, mas é realmente simples assim!

Observação: não importa se a função create_author_bio vem depois da função add_shortcode ou antes dela. A ordem não é importante neste caso.

Etapa 3: fazer a função fazer algo

Agora só falta fazer nossa função fazer o que queremos!

Uma função como essa pode fazer qualquer coisa, mas não importa o quê, ela deve retornar um único valor (como uma string de texto ou um número). Esse valor pode ser de qualquer tamanho ou complexidade, mas o que quer que a função retorne é o que aparecerá sempre que nosso shortcode for usado.

Para nossos propósitos, isso será apenas um HTML simples. Aqui está a marcação para adicionar nossa imagem de autor e biografia dentro de um elemento <aside> com uma classe personalizada (mas não coloque isso em nenhum lugar ainda; estamos apenas vendo isso como uma prévia no momento):

 [html]<aside class="author-bio-box"></span> <img src="https://upload.wikimedia.org/wikipedia/en/1/1f/Bilbo_Baggins_Tolkien_illustration.jpg"> <p>Bilbo Baggins is the author of <cite>The Hobbit</cite>, translator of various works from the elvish, and author of a number of poems and songs.</p> <p>He is the oldest Hobbit ever in Middle Earth, and spends his days in his Tol Eressea home across the sea.</p> </aside>[/html]

Eventualmente, usaremos a classe author-bio-box na primeira linha para estilizar a biografia com CSS. (Usaremos uma classe em vez de um ID, apenas no caso de você querer adicionar mais de um shortcode de autor para conteúdo escrito por vários autores.) Mas lembre-se, isso pode ser qualquer coisa que queiramos colocar na página!

Agora, tudo o que precisamos fazer é fazer com que a função do nosso shortcode retorne o HTML acima!

Como o arquivo functions.php deve conter apenas... bem, funções PHP (e também para organização), removemos as quebras de linha e os espaços entre os elementos HTML que acabamos de ver e os colocamos em uma string (dentro de aspas simples) . Mas, funcionalmente, ainda é o mesmo trecho de HTML que acabamos de ver acima, e é assim que nosso código PHP final deve ficar:

 [html]add_shortcode( 'author_bio', 'create_author_bio' ); function create_author_bio(){ return '<aside class="author-bio-box"><img src="https://upload.wikimedia.org/wikipedia/en/1/1f/Bilbo_Baggins_Tolkien_illustration.jpg"><p>Bilbo Baggins is the author of <cite>The Hobbit</cite>, translator of various works from the elvish, and author of a number of poems and songs.</p><p>He is the oldest Hobbit ever in Middle Earth, and spends his days in his Tol Eressea home across the sea.</p></aside>'; }[/html]

Acabamos com o PHP! Depois de salvar nosso arquivo functions.php com o código final acima, qualquer autor pode simplesmente inserir [author_bio] em qualquer página ou postagem, e o HTML acima aparecerá no lugar do shortcode!

Além disso, o mais legal é: se precisarmos atualizar nossa biografia, não precisaremos editar todos os lugares em que ela aparecer! Em vez disso, tudo o que precisamos fazer é editar o código em nosso arquivo functions.php e ele será atualizado em todos os lugares de uma só vez. Legal, hein?

No entanto, para tirar o máximo proveito disso, provavelmente desejaremos adicionar um estilo especial à caixa bio.

Etapa 4: adicionar algum CSS

O shortcode não é bom sem algum estilo, então vamos adicioná-lo! Pode ser necessário ajustar um pouco alguns dos valores, dependendo das fontes do seu próprio site (a da imagem acima é Fanwood Text) e quais regras de CSS já estão em vigor. Ou você pode apenas querer tentar algo diferente!

Este CSS pode ser copiado para o arquivo style.css do seu tema (filho), ou se você estiver executando o WordPress 4.7 ou superior (o que deveria ser!), basta colar este CSS na caixa “CSS adicional” no Personalizar tela:

 [css].author-bio-box { background: #d4ead9; padding: 2em; overflow: auto; font-family: Fanwood Text; font-size: 1.2em; line-height: 1.4em; } .author-bio-box img { float: left; max-width: 128px; height: auto; margin: 0 1em 0 0; } .author-bio-box > p:first-of-type:first-letter { font-size: 3.1em; line-height: 1; float: left; margin-bottom: -.2em; } .author-bio-box > p:last-of-type { margin: 0; }[/css]

Agora as coisas devem estar muito melhores. Mas fique à vontade para brincar com o CSS para tornar a caixa do autor sua e fazê-la se sentir em casa em seu site!

Recomendado: Tornar a Função “Conectável”

Isso não é específico para códigos de acesso e não é estritamente necessário para que o código funcione, mas é uma prática recomendada e este é um bom momento para mencioná-lo.

Primeiro, um pouco de histórico sobre como o PHP funciona :

Lembra como nós mesmos nomeamos nossa função create_author_bio ? Bem, não há nada de especial no nome create_author_bio; poderíamos facilmente nomear nossa função como quiséssemos (embora seja melhor se o nome da função fornecer pelo menos uma pequena dica sobre o que ela faz, e é por isso que escolhemos create_author_bio ).

Mas é o seguinte: se duas funções PHP tiverem o mesmo nome, o resultado será um erro fatal que impedirá o carregamento do site, já que o PHP não fará ideia de qual função é a correta. O PHP não adivinha, então ele simplesmente para.

E não é apenas com o nosso código que precisamos nos preocupar; um site WordPress pode usar código de dezenas ou talvez centenas de desenvolvedores diferentes, dependendo dos plugins e temas instalados. Se o mesmo nome de função for usado duas vezes, tudo falhará!

Isso é ruim e, obviamente, queremos garantir que isso nunca aconteça.

Podemos fazer isso tornando nossa função “conectável”; em outras palavras, dizer ao WordPress para não criar nossa função se já existir outra com o mesmo nome. É elegantemente simples; nós apenas envolvemos nosso código existente dentro desta declaração condicional fácil:

 [php]if( !function_exists( 'create_author_bio' ) ){ //Our existing PHP goes here! }[/php]

Essa expressão if condicional apenas verifica se uma função chamada create_author_bio ainda não existe. Todo o código PHP que usamos até agora pode ser movido dentro dessa instrução, entre as chaves { } .

No entanto, ainda é melhor nomear as funções da maneira mais exclusiva possível! Tornar nossa função conectável apenas evita um erro fatal. Portanto, se houvesse um conflito de nomenclatura, nosso shortcode ainda não funcionaria, mas pelo menos o site ainda estaria no ar e nada mais seria quebrado.

Conclusão

É isso! Espero que você tenha gostado de criar um shortcode de biografia de autor personalizado! Se você acompanhou, tudo que você precisa fazer é digitar [author_bio] em qualquer lugar em uma página ou post e seu código aparecerá!

Este shortcode pode ser facilmente adaptado para enviar qualquer coisa para uma página. Um gif, um bloco personalizado de HTML e/ou JavaScript, uma imagem ou vídeo... o que você quiser!

No entanto, embora este exemplo seja útil se você precisar apenas enviar um único valor estático para a página em algum lugar, ele não é muito flexível. Ele sempre retornará exatamente a mesma coisa todas as vezes, e geralmente precisamos de códigos de acesso para serem mais adaptáveis ​​do que isso.

Boas notícias: cobrimos apenas o básico dos códigos de acesso e eles são capazes de muito, muito mais!