O que são campos de carbono?
Carbon Fields é uma biblioteca WordPress gratuita desenvolvida por 2criar. Isto ajuda os desenvolvedores de temas e plug-ins do WordPress a criar campos adicionais para tipos de postagem, menus de navegação, widgets, etc., ou até mesmo registrar blocos personalizados de Gutenberg sem tocar em JavaScript.
Como veremos, ao longo do caminho ele vem com vários campos como checkboxes, repetidores (complexos), textos, etc.
Então, neste ponto, se você quiser seguir este tutorial, primeiro instale o Composer e depois instale o Carbon Fields executando este comando:
1 |
composer require htmlburger/carbon-fields |
O que é uma página de opções de tema WordPress?
Uma página de opções de tema é uma página de administração, localizada fora das páginas padrão do WordPress, onde os desenvolvedores armazenam configurações globais que afetam a funcionalidade de seu site ou plugin WordPress.
Por exemplo, pode haver opções para gerenciar coisas como:
- Comportamento do cabeçalho – se deve ser fixo ou não.
- Configurações de tipografia – o tamanho da fonte global, a fonte global, as cores dos títulos, etc.
Sublinhado dos Campos de Carbono
Os dados são geralmente armazenados no *_options tabela e disponível em qualquer página do site.
Vale a pena notar que a biblioteca Carbon Fields prefixa automaticamente todos os campos com um sublinhado quando armazenados no banco de dados (por exemplo, o footer_text campo se torna _footer_text).
Implementação
Para esta demonstração, criaremos uma página de opções que conterá informações sobre o layout do cabeçalho, layout do rodapé, informações de contato e canais sociais de um site de demonstração.
Observe que o foco principal será criar a estrutura da página no admin e mostrar apenas os campos no front end sem adicionar nenhum estilo. Todos os arquivos do tema estarão disponíveis neste repositório GitHub.
Como sempre, trabalharei com meu costume Parque infantil tema – deixarei o mais básico possível e adicionarei apenas a funcionalidade necessária para os Campos de Carbono.
Pensando nisso, seguindo a documentação, adicionarei este código dentro do functions.php:
1 |
use Carbon_Fields\Container; |
2 |
use Carbon_Fields\Field; |
3 |
|
4 |
function crb_attach_theme_options() { |
5 |
Container::make( 'theme_options', __( 'Theme Settings', 'playground' ) ) |
6 |
->set_page_menu_position( 4 ) |
7 |
->set_icon( 'dashicons-admin-settings' ) |
8 |
->add_tab( |
9 |
__( 'Header', 'playground' ), |
10 |
array(...), |
11 |
)
|
12 |
->add_tab( |
13 |
__( 'Contact', 'playground' ), |
14 |
array(...) |
15 |
)
|
16 |
->add_tab( |
17 |
__( 'Socials', 'playground' ), |
18 |
array(...) |
19 |
)
|
20 |
->add_tab( |
21 |
__( 'Footer', 'playground' ), |
22 |
array(...) |
23 |
);
|
24 |
}
|
25 |
add_action( 'carbon_fields_register_fields', 'crb_attach_theme_options' ); |
26 |
|
27 |
function crb_load() { |
28 |
require_once( 'vendor/autoload.php' ); |
29 |
\Carbon_Fields\Carbon_Fields::boot(); |
30 |
}
|
31 |
add_action( 'after_setup_theme', 'crb_load' ); |
Este código agrupará todos os campos dentro de um contêiner e criará um novo item de menu chamado Configurações de tema embaixo do Painel item do menu. Claro, você pode personalizar a localização do item e o ícone renderizado.
Além disso, o add_tab O método proporcionará uma organização melhor, pois agrupará todos os campos da página de opções em quatro seções com guias.
Vamos agora dar uma olhada nessas guias!
Guia Cabeçalho
O cabeçalho incluirá campos relacionados à funcionalidade do cabeçalho. Mais especificamente:
- A caixa de seleção O campo gerenciará se uma faixa de opções aparecerá acima do cabeçalho principal.
- Três campos (um texto rico e dois cor campos) definirá a aparência da faixa de opções. No entanto, eles aparecerão e funcionarão apenas se o campo da caixa de seleção anterior estiver selecionado.
- A scripts de cabeçalho campo nos permitirá incorporar a biblioteca de ícones do Font Awesome 6 no
headmarcação. Usaremos essa biblioteca para imprimir os ícones sociais–voltaremos a isso em uma próxima seção.
Criaremos todos os campos através do make método como este:
1 |
Field::make( 'header_scripts', 'header_scripts', __( 'Header Scripts', 'playground' ) ), |
2 |
Field::make( 'rich_text', 'header_ribbon', __( 'Ribbon', 'playground' ) ) |
3 |
->set_conditional_logic( |
4 |
array( |
5 |
array( |
6 |
'field' => 'show_header_ribbon', |
7 |
'value' => true, |
8 |
),
|
9 |
)
|
10 |
),
|
11 |
Field::make( 'color', 'header_ribbon_text_color', __( 'Ribbon Text Color', 'playground' ) ) |
12 |
->set_conditional_logic( |
13 |
array( |
14 |
array( |
15 |
'field' => 'show_header_ribbon', |
16 |
'value' => true, |
17 |
),
|
18 |
)
|
19 |
),
|
20 |
Field::make( 'color', 'header_ribbon_bg_color', __( 'Ribbon Background Color', 'playground' ) ) |
21 |
->set_conditional_logic( |
22 |
array( |
23 |
array( |
24 |
'field' => 'show_header_ribbon', |
25 |
'value' => true, |
26 |
),
|
27 |
)
|
28 |
),
|
29 |
Field::make( 'checkbox', 'show_header_ribbon', __( 'Show Ribbon (Top Header)?', 'playground' ) )->set_option_value( 'yes' ), |
Então, onde quer que queiramos exibi-los, usaremos o carbon_get_theme_option método e passe como argumento o nome do campo assim:
1 |
|
2 |
$show_header_ribbon = carbon_get_theme_option( 'show_header_ribbon' ); |
3 |
?>
|
4 |
|
5 |
|
6 |
|
7 |
|
8 |
if ( $show_header_ribbon ) : |
9 |
$header_ribbon = carbon_get_theme_option( 'header_ribbon' ); |
10 |
$header_ribbon_text_color = carbon_get_theme_option( 'header_ribbon_text_color' ) ? carbon_get_theme_option( 'header_ribbon_text_color' ) : '#000'; |
11 |
$header_ribbon_bg_color = carbon_get_theme_option( 'header_ribbon_bg_color' ) ? carbon_get_theme_option( 'header_ribbon_bg_color' ) : 'transparent'; |
12 |
?>
|
13 |
|
14 |
echo wp_kses_post( $header_ribbon ); ?>
|
15 |
|
16 |
endif; ?>
|
17 |
|
18 |
|
19 |
|
Guia Contato
O contato incluirá campos relacionados a contatos que estarão presentes em diferentes seções da página (por exemplo, no cabeçalho, rodapé, páginas de contato, barras laterais, etc.). Mais especificamente, haverá:
- Um campo textarea para adicionar o endereço da empresa.
- Um campo de texto para vincular a um local do Google Maps.
- Um campo de texto para adicionar o telefone da empresa.
- Um campo de texto para adicionar o correio da empresa.
- Um campo de seleção com opções dinâmicas para permitir que os usuários escolham o formulário Contact Form 7 (CF7) apropriado como formulário de boletim informativo.
Imagine que nosso site contenha os seguintes formulários:
Devemos disponibilizá-los todos para os usuários administradores. Mas aqui está o desafio: não iremos codificá-los, mas sim tornar dinâmicas todas as opções do campo de seleção.
Para fazer isso, definiremos o costume get_all_forms função e passá-la como parâmetro da add_options método do nosso campo de seleção. Esta função retornará todos os formulários do site em formato de array.
Veja como criamos os campos desta aba:
1 |
Field::make( 'textarea', 'address', __( 'Address', 'playground' ) ), |
2 |
Field::make( 'text', 'address_directions', __( 'Address Directions', 'playground' ) )->set_attribute( 'type', 'url' ), |
3 |
Field::make( 'text', 'phone', __( 'Phone', 'playground' ) )->set_attribute( 'type', 'tel' ), |
4 |
Field::make( 'text', 'email', __( 'Email', 'playground' ) )->set_attribute( 'type', 'email' ), |
5 |
Field::make( 'select', 'newsletter_form', __( 'Select Newsletter Form', 'playground' ) ) |
6 |
->add_options( 'get_all_forms' ), // or set |
E aqui está o get_all_forms() declaração:
1 |
function get_all_forms() { |
2 |
$all_forms_array = array(); |
3 |
$all_forms = get_posts( |
4 |
array( |
5 |
'post_type' => 'wpcf7_contact_form', |
6 |
'posts_per_page' => -1, |
7 |
)
|
8 |
);
|
9 |
|
10 |
foreach ( $all_forms as $form ) : |
11 |
$all_forms_array[ $form->ID ] = esc_html( $form->post_title ); |
12 |
endforeach; |
13 |
return $all_forms_array; |
14 |
}
|
A seguir, geramos os campos no local que desejamos assim:
1 |
|
2 |
$address = carbon_get_theme_option( 'address' ); |
3 |
$directions = carbon_get_theme_option( 'address_directions' ); |
4 |
$phone = carbon_get_theme_option( 'phone' ); |
5 |
$email = carbon_get_theme_option( 'email' ); |
6 |
$newsletter_form = carbon_get_theme_option( 'newsletter_form' ); |
7 |
?>
|
8 |
|
9 |
|
10 |
echo wp_kses_post( $address ); ?>
|
11 |
|
12 |
esc_html_e( 'See Map', 'playground' ); ?>
|
13 |
|
14 |
|
15 |
echo esc_html( $phone ); ?>
|
16 |
|
17 |
|
18 |
echo esc_html( $email ); ?>
|
19 |
|
20 |
|
21 |
|
22 |
|
23 |
echo do_shortcode( '[contact-form-7 id="' . esc_attr( $newsletter_form ) . '"]' ); ?>
|
24 |
|
Guia Social
O redes sociais incluirá um campo complexo para adicionar um número infinito de redes sociais. Cada social terá três campos de texto:
- Um campo de texto para o título social (por exemplo, Facebook).
- Um campo de texto para o URL social.
- Um campo de texto para colocar classes Font Awesome (por exemplo, aulas do Facebook).
Para aqueles que vêm do mundo ACF, o campo complexo é equivalente ao campo repetidor do ACF.
Veja como criamos o campo complexo em termos de código:
1 |
|
2 |
Field::make( 'complex', 'socials' ) |
3 |
->set_layout( 'tabbed-horizontal' ) |
4 |
->add_fields( |
5 |
array( |
6 |
Field::make( 'text', 'social_title', __( 'Social Title', 'playground' ) ), |
7 |
Field::make( 'text', 'social_url', __( 'Social URL', 'playground' ) )->set_attribute( 'type', 'url' ), |
8 |
Field::make( 'text', 'social_icon', __( 'Social Icon', 'playground' ) ) |
9 |
->set_attribute( 'placeholder', 'Add a class from the Font Awesome library' ), |
10 |
)
|
11 |
),
|
E é assim que imprimimos seus dados onde quisermos:
1 |
|
2 |
$socials = carbon_get_theme_option( 'socials' ); |
3 |
?>
|
4 |
|
5 |
|
6 |
|
7 |
foreach ( $socials as $social ) : |
8 |
//https://github.com/WordPress/WordPress-Coding-Standards/issues/1029
|
9 |
/* translators: %s: social channel */
|
10 |
$title = sprintf( __( 'Find us on %s', 'playground' ), $social['social_title'] ); |
11 |
?>
|
12 |
|
13 |
|
14 |
|
15 |
|
16 |
|
17 |
endforeach; ?>
|
18 |
|
Guia Rodapé
Semelhante à guia do cabeçalho, o rodapé incluirá campos relacionados à funcionalidade do rodapé. Mais especificamente:
- Um campo de texto produzirá o texto do rodapé.
- Dois campos de cores definirão as cores de primeiro e segundo plano do rodapé.
Como de costume, nós os criamos com o make método:
1 |
Field::make( 'rich_text', 'footer_text', __( 'Footer Text', 'playground' ) ), |
2 |
Field::make( 'color', 'footer_text_color', __( 'Footer Text Color', 'playground' ) ), |
3 |
Field::make( 'color', 'footer_bg_color', __( 'Footer Background Color', 'playground' ) ), |
E nós os exibimos no arquivo de destino:
1 |
|
2 |
$footer_text = carbon_get_theme_option( 'footer_text' ); |
3 |
$footer_text_color = carbon_get_theme_option( 'footer_text_color' ) ? carbon_get_theme_option( 'footer_text_color' ) : '#000'; |
4 |
$footer_bg_color = carbon_get_theme_option( 'footer_bg_color' ) ? carbon_get_theme_option( 'footer_bg_color' ) : 'transparent'; |
5 |
?>
|
6 |
|
7 |
|
8 |
|
9 |
echo wp_kses_post( $footer_text ); ?>
|
10 |
|
11 |
|
Conclusão
Neste tutorial, examinamos o kit de ferramentas de campos personalizados do Carbon Fields WordPress e exploramos muitos de seus tipos de campo criando uma página de opções de tema. Espero que agora você tenha material suficiente para decidir se esta biblioteca pode atender às suas necessidades para o seu próximo projeto WordPress.
Resumindo, vá em frente se:
- Você quer algo grátis e não é um grande fã de estender o WordPress Customizer.
- Você pode trabalhar sem uma interface de administração.
- Você constrói um plugin/tema que requer um pequeno número de campos.
Por outro lado, você pode ter dúvidas sobre usá-lo se:
- Você não terá problemas em pagar por um plugin do WordPress que oferece mais opções de tipo e estilo de layout como o ACF PRO.
- Você prefere gerenciar seus campos por meio de uma IU e se sente sobrecarregado ao gerenciá-los por meio de código.
- Além de não ser obrigatório, se você estiver construindo um site/plugin multilíngue, você pode querer escolher soluções que sejam oficialmente suportadas pela ferramenta de tradução escolhida. Por exemplo, embora Carbon Fields pareça funcionar bem com WPML de acordo com seus documentos e meus testes locais, esta ferramenta não é oficialmente compatível com WPML.
Mas sem dúvida, esta é uma ferramenta útil que todo desenvolvedor WordPress deveria experimentar pelo menos uma vez. E você? Você já usou isso? Deixe-nos saber em X!
Como sempre, muito obrigado pela leitura!
