Incluindo modelos personalizados em nossos plugins WordPress

Eu acho que um dos aspectos mais subestimados – ou talvez um dos aspectos raramente discutidos do desenvolvimento de plugins personalizados – é a capacidade de incluir modelos personalizados em nossos plugins do WordPress.

E, para ser honesto, eu entendo: eu sou uma pessoa bastante firme sobre o que deve ser um plugin e o que deve ser um tema.

Aquilo é:

• os temas são para apresentação,
• plugins são funcionalidades.

Se eu incluir templates em um plugin, não estou fazendo a mesma coisa que quando os desenvolvedores incluem funcionalidades em seus temas?

Tal como acontece com tantas coisas em desenvolvimento, acho que depende. Quero dizer, adicionar muitas funcionalidades que prendem você em um tema é algo que eu não sou fã. Da mesma forma, se você tem um plug-in destinado a mostrar dados no front-end e é independente do tema, faz sentido.

Então você tem que ser criterioso em suas decisões.

Independentemente disso, há um conjunto comum de etapas que podemos usar ao incluir modelos personalizados em nossos plugins do WordPress.

E é isso que este post vai mostrar.

Se você for incluir modelos personalizados no plug-in, assumirei que você está usando modelos únicos e de arquivo. Caso contrário, use apenas os ganchos e o código abaixo que você precisa.

Para ambos, porém, conheça estes:

• modelo_único
• arquivo_modelo

Usando esses ganchos, você pode informar ao WordPress onde os modelos personalizados residem em seu plug-in.

Modelos de organização

Para mim, geralmente tenho um  diretório de modelos no meu plugin que sites no mesmo nível dos  diretórios assets, src e vendor.

Isso facilita saber onde eles residem e fornece uma maneira consistente de incluí-los em todos os plugins que você criou. Afinal, há algo a ser dito para ser consistente nas convenções que usamos.

Incluindo os modelos

Supondo que você tenha  o modelo single-acme.php e o modelo archive-acme.php, é fácil incluí-lo. E embora eu seja mais fã de usar programação orientada a objetos, mostrarei como incluir esses modelos usando código procedural.

É fácil converter esse código em código orientado a objetos, se você quiser. Além disso, vou assumir que você está incluindo isso para tipos de postagem personalizados também.

Você sempre pode omitir uma condicional para um tipo de postagem personalizado se quiser simplesmente incluir esses modelos, mas, na minha experiência, acho raro que essas situações não usem tipos de postagem personalizados, mas não conheço sua situação.

Dito isso, aqui está o código.

Definindo Ganchos

Primeiro, precisamos definir os ganchos. Isso é relativamente simples, pois usaremos os ganchos descritos acima.

Primeiro, o modelo único :

<?php

add_action('single_template', 'acmeIncludeSingleTemplate');
/**
 * Includes a custom, single template as included in a plugin. If
 * the template is being viewed for a custom post type then use it;
 * otherwise, use the template that's provided by WordPress at runtime.
 *
 * @param  string $originalTemplate the path to the original template
 *
 * @return string the path to the original template or the custom template.
 */
function acmeIncludeSingleTemplate($originalTemplate)
{
   // More to come...
}

E então o modelo de arquivo :

<?php

add_action('archive_template', 'acmeIncludeArchiveTemplate');
/**
 * Includes a custom, archive template as included in a plugin. If
 * the template is being viewed for a custom post type then use it;
 * otherwise, use the template that's provided by WordPress at runtime.
 *
 * @param  string $originalArchiveTemplate the path to the original template
 *
 * @return string the path to the original template or the custom template.
 */
function acmeIncludeArchiveTemplate($originalArchiveTemplate)
{
  // More to come...
}

E agora podemos implementar o código para cada uma das funções.

Adicionando o código

Então, primeiro, vamos olhar para o modelo único :

<?php

add_action('single_template', 'acmeIncludeSingleTemplate');
/**
 * Includes a custom, single template as included in a plugin. If
 * the template is being viewed for a custom post type then use it;
 * otherwise, use the template that's provided by WordPress at runtime.
 *
 * @param  string $originalTemplate the path to the original template
 *
 * @return string the path to the original template or the custom template.
 */
function acmeIncludeSingleTemplate($originalTemplate)
{
  $singleTemplate = plugin_dir_path(
    dirname(
      __DIR__) );
  $singleTemplate .= '/templates/single-acme.php';

  if ('acme-cpt' === get_post_type(get_the_ID())) {
      if (file_exists($singleTemplate)) {
          return $singleTemplate;
      }
  }

  return $originalTemplate;
}

E agora o modelo de arquivo :

<?php

add_action('archive_template', 'acmeIncludeArchiveTemplate');
/**
 * Includes a custom, archive template as included in a plugin. If
 * the template is being viewed for a custom post type then use it;
 * otherwise, use the template that's provided by WordPress at runtime.
 *
 * @param  string $originalArchiveTemplate the path to the original template
 *
 * @return string the path to the original template or the custom template.
 */
function acmeIncludeArchiveTemplate($originalArchiveTemplate)
{
  $archiveTemplate = plugin_dir_path(
    dirname(
      __DIR__) );
  $archiveTemplate .= '/templates/archive-acme.php';

  if ('acme-cpt' === get_post_type(get_the_ID())) {
      if (file_exists($archiveTemplate)) {
          return $archiveTemplate;
      }
  }

  return $originalArchiveTemplate;
}

Se você prestou muita atenção ao código, sabe que há muito pouca diferença. Na verdade, o processo geral pode ser descrito da seguinte forma:

1. definir o gancho,
2. localize o modelo,
3. verifique o tipo de postagem personalizado,
4. o modelo existe, use-o
5. caso contrário, use o modelo padrão

E este é o processo para modelos únicos e de arquivo.

Escrevendo Modelos Compatíveis

E, finalmente, e isso é importante, especialmente se você deseja tornar o modelo o mais agnóstico possível, tento usar o máximo possível de tags de modelo do WordPress integradas ao mostrar o conteúdo relacionado ao plug-in. Isso permite que os desenvolvedores de temas o estilizem facilmente para se adequar ao seu tema.

Não, você não poderá acomodar todos os temas, mas essa é a natureza dos temas do WordPress. O objetivo é ter o máximo de trabalho possível para recuperar e renderizar dados do modelo para que os desenvolvedores front-end possam gerenciá-los facilmente.