Alp_Metabox

Vai permitir criar e gerenciar metaboxes de maneira mais prática, tanto para post types quanto para templates de páginas, usando o nosso conhecido plugin do Metabox.io.

Ao invés de todos aqueles arrays enormes, que ocupam inúmeras linhas, a ideia para o V4 é que você utilize métodos desta classe, tornando o código bem mais limpo e horizontal, que criarão por baixo dos panos todo aqueles arrays dentro de arrays para você, sem que você se preocupe em se fechou alguma ] ou não.

Construção da classe

Ao visualizar a classe, você logo notar que o construtor da classe é privado, então você não irá conseguir criar nenhum objeto da classe usando o velho new Alp_Metabox().

E isto vai estar correto, porque existem duas situações distintas em que você vai querer criar objetos de Alp_Metabox, que é quando você tem post types e quando você tem templates de páginas. Então você utilizará dois métodos estáticos da classe para fazer o retorno dos objetos para você.

Para post types

public static function create_for_post_type(string $prefix, string|array $post_type): self

Utlizando o método estático create_for_post_type() você vai poder criar metaboxes para um post type específico. Você irá passar o prefixo das caixas, e irá também passar o nome do post type, que pode até mesmo ser um array com vários.

info

Rotineiramente, você não irá criar Metaboxes para post types usando esse método. A obrigação é dos objetos de Alp_Entity de gerar os metaboxes para o post type, então ela que debaixo dos panos irá implementar esse método. Fica aqui essa seção a título de curiosidade mesmo.

Para templates

public static function create_for_template_page(string $prefix, string $template, bool $remove_editor = true): self

Nesse método iremos passar o prefixo das caixas, a string com o caminho para o template, e também há a possibilidade de remover o editor (a caixona com o bloco de texto que vem por padrão nos posts do tipo 'page'), pois geralmente não a utilizamos se a intenção é deixar a página cheia de metaboxes.

info

Assim como no caso dos post types, você não irá sair criando metaboxes para templates assim, utilizando esse método de forma direta. Quem deve fazer esse jogo são as instâncias de Alp_Page_Template.

Metódos principais

Apos ser utilizado um dos dois métodos de criação, um objeto será retornado para você e, na sequência, o caminho estará livre para você encadear com outros métodos, que farão a criação das caixas e dos campos dentro delas.

Adicionando a caixa

public function add_metabox_box(string $subprefix, string $title, string|false|null $id = false): self

A caixa é fisicamente a própria caixa mesmo, a estrutura física onde ficarão os metacampos, que nesse primeiro momento estará vazia.

$subprefix é o subprefixo que todos os campos daquela caixa vão utilizar. Será anexado ao já estabelecido $prefix anteriormente na classe. Então se você tem uma página Sobre, que utiliza o prefix 'sobre' para suas metaboxes, e agora está criando uma caixa para a Seção do banner, com subprefix 'banner', os campos ficariam 'sobre_banner_imagem', 'sobre_banner_titulo', etc.

Caso seja sua preferência, pode passar uma string vazia como subprefix, então seria usado apenas o prefix. É útil para páginas que tenha apenas uma seção, por exemplo, e você não queria deixar tudo muito verboso.

nota

A melhor parte é que quando você for criar os campos, você não vai mais precisar passar prefix e subprefix, irá poder abstrair toda essa parte.

E com o estabelecimento de prefix e subprefix, você evita as colisões de nomes para os postmetas.

$title é o título que a caixa vai ter. Simplesmente a parte visual.

$id é o id do Metabox para a caixa. Normalmente não é usado para nada, então a classe vai se encarregar de criar internamente um id genérico. Mas se você necessitar de criar um id muito específico para a caixa, pode contar com esse parâmetro.

Não precisará ter um encerramento para as caixas, automaticamente acabará

Adicionando um campo

public function add_metabox_field(string $name, string $id, string $type = 'text', int $columns = 12, array $more_args = []): self

O método add_metabox_field() é a forma genérica para criar os campos de metabox. Na prática e no dia-a-dia, não será esse o método a ser utilizado, e sim um dos métodos derivados do principal, que estão estabelecidos dentro do trait Alp_Metabox_Fields, que já estabelecem qual é o campo e já traz parâmetros adicionais inspirados no próprio tipo de campo que você quer utilizar.

Mas para fins didáticos é bom entender como a fórmula genérica foi criada, pois todos os parâmetros dela serão usados nos outros métodos, exceto o parâmetro $type, claro, pois todos os outros métodos já deixarão estabelecidos qual o type daquele field. Mas é o mesmo type que passamos no array do Metabox.

$name é a chave 'name' como passado no array do Metabox, que é o rótulo/label daquele campo.

$id também representa a chave 'id' como no array do Metabox, simbolizando aquele identificador do post_meta. A melhor parte aqui é que você não vai precisar perder tempo colocando o prefix e subprefix aqui, porque a classe é quem fará isso pra você.

$columns vai representar quantas colunas você quer que o layout tenha, partindo do pressuposto que você está usando a extensão de colunas do Metabox para deixar o visual mais bacana. O esquema é o mesmo que conhecemos das 12 colunas para layouts web.

$more_args aqui você pode passar o resto do array do Metabox, que internamente haverá uma junção de tudo.

info

Como falado anteriormente, geralmente esse não será o esquema usado para criar os campos. Você poderá usar métodos da trait Alp_Metabox_Fields como add_metabox_field_text, add_metabox_field_image, add_metabox_field_select_advanced, ou até mesmo métodos da trait Alp_Metabox_Specifics, que traz métodos com implementações mais específicas dos campos básicos, como add_metabox_field_biu, add_metabox_field_select_cidades, add_metabox_field_select_target.

Cada método desses vai propor parâmetros mais específicos de acordo com o campo que você vai inserir. Dê uma olhada depois nas traits.

Adicionando um group

public function add_metabox_group(string $name, string $id, string $group_title = 'Item {#}', int $max_clone = -1, int $columns = 12, array $more_args = []): self

Fechando um group

public function close_metabox_group(): self

Se você abriu um group, também tem que ter um método pra fechar. Então temos esse método simples que apenas fecha o group atual e volta o ponteiro para o nível anterior. Bem útil quando você está dentro de uma caixa e quer inserir mais campos depois, ou está dentro de um group mais interno e quer voltar para o externo.

Mesmo que quando a caixa encerra, tudo dentro dela fica lacrado, é sempre boa prática colocar um close_metabox_group()

Enfim, os refrescos

public function render(): void

Embora tudo esteja sendo estabelecido dentro de um array interno da classe, nada será exibido ainda na tela, não há menos que você encerre todos os encadeamentos com um método render, que irá jogar tudo para ser renderizado na tela de seu post.

Uso de traits para fields

Para facilitar a limpeza do código, a classe Alp_Metabox irá implementar apenas métodos principais, para funcionamento do seu próprio core, e a lógica de criação de inúmeros tipos de campos para Metaboxes será responsabilidade dos traits que ela utiliza.

Alp_Metabox_Fields

trait Alp_Metabox_Fields

Esse trait vai fornecer muitos métodos para alguns tipos de campos já tradicionais do Metabox.io, como por exemplo 'text', 'number', 'image', 'select_advanced', 'video', 'switch', entre muitos outros.

O objetivo dessa trait é que cada método para um campo específico já venha com parâmetros que sejam interessantes para esse tipo. Por exemplo, para uma imagem é interessante que já seja perguntada a quantidade de imagens, e internamente esse método já implementa configurações diferentes se for requerida apenas uma imagem ou se forem múltiplas.

Campo de número pergunta min, max e step. Campo de select já pergunta as options. E assim vai.

Surgindo a necessidade de colocar fields de tipos que não estejam ainda contemplados, é só acrescentar dentro dessa trait.

Alp_Metabox_Specifics

trait Alp_Metabox_Specifics

Já a trait de Specifics vai fornecer configurações específicas para campos tradicionais.

Podemos citar por exemplo o método add_metabox_field_biu(), que é uma configuração do type 'wysiwyg' em que são renderizados apenas os botões de bold, italic e underline, daí o significado biu (ou b/i/u) no nome.

Há também um segundo método chamado add_metabox_field_biu_list(), que além do b/i/u também renderiza listas numéricas (ol) e não-numéricas (ul).

Podemos contar também com alguns selects customizados, que já vem com valores para target (_self e _blank), e até mesmo os que carregam dados de API, que são os de cidades e estados, carregados através do IBGE.

Métodos mais avançados

Encadeamento de callable

public function chain_from_callable(callable $callable): self

Também será possível usar callables (funções ou métodos de outras classes) para fazer encadeamentos no objeto da Alp_Metabox, facilitando o reuso.

Por exemplo, se todas as páginas do seu projeto precisam renderizar uma box de banner na página, que inclui SUBTÍTULO, TÍTULO, TEXTO, IMAGEM DE FUNDO (MOBILE E DESKTOP) e BOTÃO (CTA), o que vai incluir campos para TEXTO, LINK e um select de TARGET, por que não armazenar tudo isso num só lugar, e quando precisar já chamar a montagem do box completo?

Usando a chain_from_callable isso se torna um trabalho bem fácil. Os únicos requirementos são que a função/método receba um objeto Alp_Metabox como primeiro parâmetro e retorne também esse objeto Alp_Metabox ao término da função.

Exemplo:

Exemplo_Minha_Pagina.php

class Exemplo_Minha_Pagina extends Alp_Page
{
  use Exemplo_Banner_Topo;

  /**
   * Cria as metaboxes do template.
   */
  public function create_metaboxes(): void
  {
    $this
      ->template->create_metaboxes()
      //BANNER NO TOPO
      ->chain_from_callable([$this, 'chain_metaboxes_banner_topo'])
      ->render();
  }
}

Exemplo_Banner_Topo.php

trait Exemplo_Banner_Topo {
  public function chain_metaboxes_banner_topo(Alp_Metabox $metaboxes): Alp_Metabox
  {
    $metaboxes
      ->add_metabox_box('banner', 'Banner no Topo')
      ->add_metabox_field_text('Subtítulo', 'subtitulo', 6)
      ->add_metabox_field_biu('Título', 'titulo', 6)
      ->add_metabox_field_biu('Texto', 'texto', 6);
      ->add_metabox_field_image('Imagem de Fundo (Desktop)', 'imagem_desktop', 1, 6)
      ->add_metabox_field_image('Imagem de Fundo (Mobile)', 'imagem_mobile', 1, 6)
      ->add_metabox_field_text('Texto do Botão', 'cta_texto', 4)
      ->add_metabox_field_text('Link do Botão', 'cta_link', 4)
      ->add_metabox_field_select_target('Onde abrir o link?', 'cta_target', 4);

    return $metaboxes;
  }
}

Adicionando lógica

public function add_logic(string $field, mixed $value, string $operator = '=', $hide = false): self

Padrões de Nome

Todos os métodos que adicionam fields do Meta Box, sejam eles atuais ou futuros, devem ter sempre o prefixo add_metabox_field_. Isso vale para implementações dos tipos básicos, estabelecidos na documentação do MB, ou para tipos que você criar com configurações mais personalizadas.

As exceções ficam por conta de:

• Grupos não serão considerados fields em nosso contexto, então o método de adição não carrega field no nome, sendo direto add_metabox_group. Além disso também vai implementar o método close_metabox_group.
• Alguns campos que só imprimem valores na tela não utilizam field também. É o exemplo de add_metabox_heading que imprime um heading, e do add_metabox_content que imprime um HTML customizado na tela.