Os campos personalizados permitem que informações adicionais sejam atribuídas ao conteúdo do site. Esta informação é normalmente conhecida como metadados.

Metadados são informações sobre informação. No caso do WordPress, são informações associadas a artigos, usuários, comentários e termos.

Dada a relação de muitos metadados no WordPress, as opções são virtualmente ilimitadas. Você pode ter quantas opções de metadados você quiser e pode armazenar qualquer coisa nele.

—Plugin Handbook

Aqui estão alguns exemplos de metadados que podem ser anexados a um artigo usando campos personalizados:

  • As coordenadas geográficas de um lugar ou de um imóvel
  • A data de um evento
  • O ISBN ou autor de um livro
  • O estado de espírito do dia do autor do artigo

E há muito mais.

No WordPress, não há uma maneira fácil de adicionar e gerenciar campos personalizados. No editor clássico, os campos personalizados são exibidos em uma caixa na parte inferior da página, abaixo do editor do artigo.

Campos personalizados no Editor Clássico.
Campos personalizados no Editor Clássico.

No Gutenberg, os campos personalizados são desabilitados por padrão, mas você pode exibi-los selecionando o item correspondente nas configurações do artigo.

Adicionando o painel de campos personalizados ao editor de blocos.
Adicionando o painel de campos personalizados ao editor de blocos.

Infelizmente, não há como exibir metadados no frontend sem usar um plugin ou sujar suas mãos com código.

Se você é um usuário, você encontrará vários plugins excelentes que fazem este trabalho para você. Mas se você trabalha como desenvolvedor e quer obter mais dos campos personalizados do WordPress, basta integrá-los perfeitamente ao editor de blocos e exibi-los no frontend do seu site WordPress através de um bloco personalizado do Gutenberg, então você está no lugar certo.

Então, se você está se perguntando qual é a melhor maneira de usar os campos personalizados do WordPress tanto no Gutenberg quanto no Editor Clássico para desenvolvedores de WordPress, a resposta rápida é “criando um plugin que funcione tanto para o Editor Clássico quanto para o Gutenberg”.

Mas não se preocupe. Enquanto criar um plugin para gerenciar campos personalizados em ambos os editores podem parecer um pouco complicado, vamos tentar tornar o processo o mais simples possível. Assim que você entender os conceitos que discutiremos neste artigo, você adquirirá as habilidades necessárias para gerenciar ‘meta field’ personalizados em Gutenberg e criar sites de todos os tipos.

Nota: Antes de fazer qualquer coisa, certifique-se de ter uma versão atualizada do Node.js em seu computador

Dito isso, aqui está o nosso resumo:

Crie um plugin de bloco com a ferramenta oficial de criação de blocos (create-block)

O primeiro passo é criar um novo plugin com todos os arquivos e dependências necessárias para registrar um novo tipo de bloco. O plugin de bloco permitirá que você crie facilmente um tipo de bloco personalizado para gerenciar e exibir metadados personalizados.

Para criar um novo tipo de bloco, usaremos a ferramenta oficial de criação de blocos. Para uma visão detalhada de como usar a ferramenta create-block, veja nosso artigo anterior sobre o desenvolvimento de blocos do Gutenberg.

Abra sua ferramenta de linha de comando, navegue até o diretório de plugins do seu site de desenvolvimento WordPress e execute o seguinte comando:

npx @wordpress/create-block

Quando solicitado, adicione os seguintes detalhes:

  • A variante de modelo a ser usada para este bloco: dynamic
  • A slug de bloco utilizada para identificação (também o nome da pasta de saída): metadata-block
  • O espaço interno para o nome do bloco (algo único para seus produtos): meta-fields
  • O título de exibição para o seu bloco: Meta Fields
  • A breve descrição para o seu bloco (opcional): Descrição do bloco
  • O dashicon para facilitar a identificação do seu bloco (opcional): book
  • O nome da categoria para ajudar os usuários a navegar e descobrir seu bloco: widgets
  • Você quer personalizar o plugin do WordPress? Sim/Não

Vamos examinar esses detalhes por um momento e tentar entender onde eles são usados.

  • A slug de bloco utilizada para identificação define o nome da pasta do plugin e o domínio de texto
  • O namespace interno para o nome do bloco define o namespace interno do bloco e o prefixo de função usado em todo o código do plugin.
  • O título de exibição do seu bloco define o nome do plugin e o nome do bloco usado na interface do editor.

A configuração pode demorar alguns minutos. Quando o processo for concluído, você receberá uma lista dos comandos disponíveis.

Plugin de bloco instalado com sucesso.
Plugin de bloco instalado com sucesso.

Antes de passar para a próxima seção, em sua ferramenta de linha de comando, navegue até a pasta do seu plugin e execute os seguintes comandos:

cd metadata-block
npm start

Você está pronto para construir seu código. O próximo passo é editar o arquivo PHP principal do plugin para construir uma meta box para o Editor Clássico.

Então, antes de passar para a próxima seção, instale e ative o plugin do Editor Clássico.

Em seguida, abra a tela Plugins e ative o novo plugin Meta Fields.

Ativar plugins.
Ativar plugins.

Adicione uma Meta Box ao Editor Clássico

No contexto do Editor Clássico, uma meta box é um contêiner contendo elementos de formulário para digitar informações específicas, como o autor do artigo, tags, categorias, etc.

Além das meta box integradas, os desenvolvedores de plugins podem adicionar qualquer número de meta box personalizadas para incluir elementos de formulário HTML (ou qualquer conteúdo HTML) onde os usuários de plugins podem inserir dados específicos do plugin.

A API do WordPress fornece funções úteis para registrar facilmente meta box personalizadas para incluir todos os elementos HTML que seu plugin precisa para funcionar.

Para começar, anexe o seguinte código ao arquivo PHP do plugin que você acabou de criar:

// register meta box
function meta_fields_add_meta_box(){
	add_meta_box(
		'meta_fields_meta_box', 
		__( 'Book details' ), 
		'meta_fields_build_meta_box_callback', 
		'post',
		'side',
		'default'
	 );
}

// build meta box
function meta_fields_build_meta_box_callback( $post ){
	  wp_nonce_field( 'meta_fields_save_meta_box_data', 'meta_fields_meta_box_nonce' );
	  $title = get_post_meta( $post->ID, '_meta_fields_book_title', true );
	  $author = get_post_meta( $post->ID, '_meta_fields_book_author', true );
	  ?>
	  <div class="inside">
	  	  <p><strong>Title</strong></p>
		  <p><input type="text" id="meta_fields_book_title" name="meta_fields_book_title" value="<?php echo esc_attr( $title ); ?>" /></p>	
		  <p><strong>Author</strong></p>
		  <p><input type="text" id="meta_fields_book_author" name="meta_fields_book_author" value="<?php echo esc_attr( $author ); ?>" /></p>
	  </div>
	  <?php
}
add_action( 'add_meta_boxes', 'meta_fields_add_meta_box' );

A função add_meta_box registra uma nova meta-box, enquanto a função callback cria o HTML a ser injetado na meta-box. Não iremos desenvolver este tópico, pois ele está além do escopo do nosso artigo, mas você encontrará todos os detalhes necessários na documentação obre a função add_meta_boxes hook, na documentação precisa aqui, aqui e aqui.

O próximo passo é criar uma função que salve os dados de entrada da pessoa que escreveu o artigo cada vez que o hook save_post é ativado (veja Recursos do Desenvolvedor):

// save metadata
function meta_fields_save_meta_box_data( $post_id ) {
	if ( ! isset( $_POST['meta_fields_meta_box_nonce'] ) )
		return;
	if ( ! wp_verify_nonce( $_POST['meta_fields_meta_box_nonce'], 'meta_fields_save_meta_box_data' ) )
		return;
	if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE )
		return;
	if ( ! current_user_can( 'edit_post', $post_id ) )
		return;

	if ( ! isset( $_POST['meta_fields_book_title'] ) )
		return;
	if ( ! isset( $_POST['meta_fields_book_author'] ) )
		return;

	$title = sanitize_text_field( $_POST['meta_fields_book_title'] );
	$author = sanitize_text_field( $_POST['meta_fields_book_author'] );

	update_post_meta( $post_id, '_meta_fields_book_title', $title );
	update_post_meta( $post_id, '_meta_fields_book_author', $author );
}
add_action( 'save_post', 'meta_fields_save_meta_box_data' );

Mais uma vez, por favor, consulte a documentação on-line para mais detalhes. Apenas destacaremos aqui o caractere de sublinhado (_) que precede a meta key. Isso diz ao WordPress para esconder as chaves destes campos personalizados da lista de campos personalizados disponíveis por padrão e torna seus campos personalizados visíveis apenas na sua meta box personalizada.

A imagem abaixo mostra como é a meta box personalizada no Editor Clássico:

A custom Meta Box in the Classic Editor
Uma Meta Box personalizada no Editor Clássico.

Agora, se você desativar o plugin Classic Editor e verificar o que acontece no Editor de Blocos, você verá que a meta box ainda aparece e funciona, mas não exatamente da maneira que você poderia esperar.

Nosso objetivo é criar um sistema de gerenciamento de metadados anexados aos blogs ou tipos de artigos personalizados que se integrem perfeitamente no editor de blocos. Por esta razão, o código mostrado até agora só será necessário para garantir a compatibilidade retroativa com o Editor Clássico.

Então, antes de continuar, vamos dizer ao WordPress para remover a meta box personalizada do editor de blocos, adicionando a flag __back_compat_meta_box à função add_meta_box (veja também Flags de Compatibilidade da Meta Box e Compatibilidade com Retrocesso).

Vamos voltar à função de callback que registra a meta box e mudá-la da seguinte forma:

// register meta box
function meta_fields_add_meta_box(){
	add_meta_box(
		'meta_fields_meta_box', 
		__( 'Book details' ), 
		'meta_fields_build_meta_box_callback', 
		'post', 
		'side',
		'default',
		// hide the meta box in Gutenberg
		array('__back_compat_meta_box' => true)
	 );
}

Salve o arquivo do plugin e volte para o seu administrador WordPress. Agora, você não deve mais ver a meta box personalizada no editor de blocos. Se você reativar o Editor Clássico ao invés disso, sua meta box personalizada aparecerá novamente.

Adicione meta fields personalizados ao editor de blocos do Gutenberg (3 opções)

Em nossos artigos anteriores sobre o desenvolvimento de blocos Gutenberg, fornecemos uma visão geral detalhada do editor, suas partes e como desenvolver blocos estáticos e blocos dinâmicos.

Como mencionamos, neste artigo daremos um passo adiante e discutir como adicionar meta fields personalizados aos artigos do blog.

Há várias maneiras de armazenar e usar metadados postados no Gutenberg. Aqui vamos cobrir o seguinte:

Criando um bloco personalizado para armazenar e exibir meta fields personalizados

Nesta seção, lhe mostraremos como criar e gerenciar meta fields personalizados a partir de um bloco dinâmico. Conforme o Manual do Editor de Bloco, um meta field do artigo “é um objeto WordPress usado para armazenar dados extras sobre um artigo” e precisamos primeiro registrar um novo meta field antes de podermos usá-lo.

Registre meta fields personalizados

Antes de registrar um meta field personalizado, você precisa ter certeza de que o tipo do artigo que irá usá-lo suporta campos personalizados. Além disso, quando você registra um meta field personalizado, você deve definir o parâmetro show_in_rest para true.

Agora, de volta ao arquivo de plugin. Adicione o seguinte código:

/**
 * Register the custom meta fields
 */
function meta_fields_register_meta() {

    $metafields = [ '_meta_fields_book_title', '_meta_fields_book_author' ];

    foreach( $metafields as $metafield ){
        // Pass an empty string to register the meta key across all existing post types.
        register_post_meta( '', $metafield, array(
            'show_in_rest' => true,
            'type' => 'string',
            'single' => true,
            'sanitize_callback' => 'sanitize_text_field',
            'auth_callback' => function() { 
                return current_user_can( 'edit_posts' );
            }
        ));
    }  
}
add_action( 'init', 'meta_fields_register_meta' );

register_post_meta registra uma meta key para os tipos de artigos especificados. No código acima, registramos dois meta fields personalizados para todos os tipos de artigos registrados em seu site que suportam campos personalizados. Para mais informações, veja a referência da função.

Uma vez feito, abra o arquivo src/index.js do seu plugin de bloco.

Registre o tipo de bloco no Cliente

Agora navegue para a pasta wp-content/plugins/metadata-block/src e abra o arquivo index.js:

import { registerBlockType } from '@wordpress/blocks';
import './style.scss';
import Edit from './edit';
import metadata from './block.json';

registerBlockType( metadata.name, {
	edit: Edit,
} );

Com blocos estáticos, também teríamos visto uma função save . Neste caso, a função save está faltando porque instalamos um bloco dinâmico. O conteúdo mostrado no frontend será gerado dinamicamente via PHP.

Construa o tipo de bloco

Navegue até a pasta wp-content/plugins/metadata-block/src e abra o arquivo edit.js. Você deve ver o seguinte código (comentários removidos):

import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';
import './editor.scss';

export default function Edit() {
	return (
		<p { ...useBlockProps() }>
			{ __( 'Meta Fields – hello from the editor!', 'metadata-block' ) }
		</p>
	);
}

Aqui você adicionará o código para gerar o bloco a ser renderizado no editor.

O primeiro passo é importar os componentes e funções necessárias para construir o bloco. Aqui está a lista completa de dependências:

import { __ } from '@wordpress/i18n';
import { useBlockProps, InspectorControls, RichText } from '@wordpress/block-editor';
import { useSelect } from '@wordpress/data';
import { useEntityProp } from '@wordpress/core-data';
import { TextControl, PanelBody, PanelRow } from '@wordpress/components';
import './editor.scss';

Se você já leu nossos artigos anteriores, você deve estar familiarizado com muitas dessas declarações import. Aqui nós vamos apontar apenas alguns deles:

import { useSelect } from '@wordpress/data';
import { useEntityProp } from '@wordpress/core-data';

Uma vez que estas dependências foram importadas, é assim que o useSelect e useEntityProp são inseridos na função Edit():

const postType = useSelect(
		( select ) => select( 'core/editor' ).getCurrentPostType(),
		[]
	);
const [ meta, setMeta ] = useEntityProp( 'postType', postType, 'meta' );

Este código fornece o atual postType, um objeto de meta fields (meta), e uma função de setter para atualizá-los (setMeta).

Agora substitua o código atual para a função Edit() com o seguinte:

export default function Edit() {
	const blockProps = useBlockProps();
	const postType = useSelect(
		( select ) => select( 'core/editor' ).getCurrentPostType(),
		[]
	);
	const [ meta, setMeta ] = useEntityProp( 'postType', postType, 'meta' );
	const bookTitle = meta[ '_meta_fields_book_title' ];
	const bookAuthor = meta[ '_meta_fields_book_author' ];
	const updateBookTitleMetaValue = ( newValue ) => {
		setMeta( { ...meta, _meta_fields_book_title: newValue } );
    };
	const updateBookAuthorMetaValue = ( newValue ) => {
		setMeta( { ...meta, _meta_fields_book_author: newValue } );
	};
return ( ... );
}

Novamente:

  • Nós usamos useSelect para obter o tipo do artigo atual.
  • useEntityProp retorna um conjunto de meta fields e uma função setter para definir novos valores de meta.
  • updateBookTitleMetaValue e updateBookAuthorMetaValue são dois manipuladores de eventos para salvar os valores dos meta fields.

O próximo passo é construir o código JSX (JavaScript XML) retornado pela função Edit():

export default function Edit() {
	...
	return (
		<>
			<InspectorControls>
				<PanelBody 
					title={ __( 'Book Details' )}
					initialOpen={true}
				>
					<PanelRow>
						<fieldset>
							<TextControl
								label={__( 'Book title' )}
								value={ bookTitle }
								onChange={ updateBookTitleMetaValue }
							/>
						</fieldset>
					</PanelRow>
					<PanelRow>
						<fieldset>
							<TextControl
								label={ __( 'Book author' ) }
								value={ bookAuthor }
								onChange={ updateBookAuthorMetaValue }
							/>
						</fieldset>
					</PanelRow>
				</PanelBody>
			</InspectorControls>
			<div { ...blockProps }>
				<RichText 
					tagName="h3"
					onChange={ updateBookTitleMetaValue }
					allowedFormats={ [ 'core/bold', 'core/italic' ] }
					value={ bookTitle }
					placeholder={ __( 'Write your text...' ) }
				/>
				<TextControl
					label="Book Author"
					value={ bookAuthor }
					onChange={ updateBookAuthorMetaValue }
				/>
			</div>
		</>
	);
}

O componente RichText fornece uma entrada de conteúdo, enquanto TextControl fornece campos de texto simples.

Também criamos um painel lateral contendo dois campos de entrada para usar ao invés dos dois controles de formulário incluídos no bloco.

Salve o arquivo e volte para o editor. Adicione o bloco Meta Fields do inseridor do bloco e preencha o título do livro e o autor.

Um bloco personalizado incluindo dois Meta Fields personalizados.
Um bloco personalizado incluindo dois Meta Fields personalizados.

Você notará que sempre que você alterar o valor do campo no bloco, o valor no campo de texto correspondente na barra lateral também mudará.

Em seguida, temos que criar o código PHP que gera o HTML a ser renderizado no frontend.

Exibindo o bloco no frontend

Abra o arquivo PHP principal novamente em seu editor de código e reescreva a função de retorno de chamada que gera a saída do bloco como a seguir:

function meta_fields_metadata_block_block_init() {
	register_block_type(
		__DIR__ . '/build',
		array(
			'render_callback' => 'meta_fields_metadata_block_render_callback',
		)
	);
}
add_action( 'init', 'meta_fields_metadata_block_block_init' );

function meta_fields_metadata_block_render_callback( $attributes, $content, $block ) {
	
	$book_title = get_post_meta( get_the_ID(), '_meta_fields_book_title', true );
	$book_author = get_post_meta( get_the_ID(), '_meta_fields_book_author', true );
    
	$output = "";

	if( ! empty( $book_title ) ){
		$output .= '<h3>' . esc_html( $book_title ) . '</h3>';
	}
	if( ! empty( $book_author ) ){
		$output .= '<p>' . __( 'Book author: ' ) . esc_html( $book_author ) . '</p>';
	}
	if( strlen( $output ) > 0 ){
		return '<div ' . get_block_wrapper_attributes() . '>' . $output . '</div>';
	} else {
		return '<div ' . get_block_wrapper_attributes() . '>' . '<strong>' . __( 'Sorry. No fields available here!' ) . '</strong>' . '</div>';
	}
}

Este código é bastante autoexplicativo. Primeiro, usamos get_post_meta para recuperar os valores dos meta fields personalizados. Depois, usamos esses valores para construir o conteúdo do bloco. Finalmente, a função callback retorna o HTML do bloco.

Os blocos estão prontos para uso. Este exemplo intencionalmente mantém o código o mais simples possível, mas você pode usar os componentes nativos do Gutenberg para criar blocos mais avançados e aproveitar ao máximo os meta fields personalizados do WordPress.

Um bloco personalizado incluindo vários meta fields.
Um bloco personalizado incluindo vários meta fields.

Em nosso exemplo, usamos h3 e p elementos para construir o bloco para o frontend.

Mas você pode exibir os dados de várias maneiras. A imagem seguinte mostra uma simples lista não ordenada de meta fields.

Um bloco de exemplo no frontend.
Um bloco de exemplo no frontend.

Você encontrará o código completo deste exemplo neste resumo público.

Adicionando uma meta box personalizada à barra lateral do documento

A segunda opção é anexar meta fields personalizados aos artigos usando um plugin que gera um painel de configurações na barra lateral do documento.

O processo é bastante similar ao exemplo anterior, exceto que, neste caso, não precisaremos de um bloco para gerenciar metadados. Criaremos um componente para gerar um painel incluindo um conjunto de controles na barra lateral do documento seguindo estes passos:

  1. Crie um novo plugin de bloco com create-block
  2. Registre uma meta box personalizada para o Editor Clássico
  3. Registre os meta fields personalizados no arquivo principal do plugin através da função register_post_meta()
  4. Registre um plugin no arquivo index.js
  5. Construa o componente usando componentes incorporados do Gutenberg

Crie um novo plugin de bloco com a ferramenta create-block

Para criar um novo plugin de bloco, siga os passos da seção anterior. Você pode criar um novo plugin ou editar os scripts que construímos no exemplo anterior.

Registre uma Meta Box personalizada para o Editor Clássico

Em seguida, você precisa registrar uma meta box personalizada para garantir a compatibilidade retroativa para sites WordPress que ainda usam o Editor Clássico. O processo é o mesmo descrito na seção anterior.

Registre os Meta Fields Personalizados no arquivo principal do plugin

O próximo passo é registrar os meta fields personalizados no arquivo principal do plugin através da função register_post_meta(). Novamente, você pode seguir o exemplo anterior.

Registre um Plugin no arquivo index.js

Uma vez que você tenha completado os passos anteriores, é hora de registrar um plugin no arquivo index.js para renderizar um componente personalizado.

Antes de registrar o plugin, crie uma pasta de componentes na pasta src do plugin. Dentro da pasta de componentes, crie um novo arquivo MetaBox.js. Você pode escolher o nome que você acha mais adequado para o seu componente, seguindo as melhores práticas para nomear no React.

Antes de continuar, instale o módulo@wordpress/plugins a partir da sua ferramenta de linha de comando.

Pare o processo (mac), instale o módulo e inicie o processo novamente:

^C
npm install @wordpress/plugins --save
npm start

Uma vez feito, abra o arquivo index.js do seu plugin e adicione o seguinte código.

/**
 * Registers a plugin for adding items to the Gutenberg Toolbar
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-sidebar/
 */
import { registerPlugin } from '@wordpress/plugins';

import MetaBox from './components/MetaBox';

O código é bastante explicativo. Entretanto, gostaríamos de nos deter por um momento nas duas declarações import para aqueles que não têm conhecimentos avançados do React.

Com a primeira declaração import, nós incluímos o nome da função entre parênteses curvos. Com a segunda declaração import, o nome do componente não está incluído  entre parênteses encaracolados.

A seguir, registre seu plugin:

registerPlugin( 'metadata-plugin', {
	render: MetaBox
} );

registerPlugin simplesmente registra um plugin. A função aceita dois parâmetros:

  • Uma string única que identifica o plugin
  • Um objeto de configurações do plugin. Note que a propriedade render deve ser especificada e deve ser uma função válida.

Construa o componente usando componentes incorporados do Gutenberg

É hora de construir nosso componente React. Abra o arquivo MetaBox.js (ou como você o chamou) e adicione as seguintes declarações de importação:

import { __ } from '@wordpress/i18n';
import { compose } from '@wordpress/compose';
import { withSelect, withDispatch } from '@wordpress/data';
import { PluginDocumentSettingPanel } from '@wordpress/edit-post';
import { PanelRow, TextControl, DateTimePicker } from '@wordpress/components';
  • A função compose executa a composição da função, o que significa que o resultado de uma função é passado para outra função. Antes de você poder usar compose, você pode precisar instalar o módulo correspondente: 
    npm install @wordpress/compose --save

    Observaremos a função compose em ação em um momento.

  • withSelect e withDispatch são dois componentes superiores que permitem a você buscar ou enviar dados para ou de uma loja WordPress. withSelect é usado para injetar adereços derivados do estado usando seletores registrados, enquanto, withDispatch é usado para enviar adereços usando criadores de ações registrados.
  • PluginDocumentSettingPanel renderiza itens na barra lateral do documento (veja o código-fonte no Github).

Em seguida, você criará o componente para exibir o painel da meta box na barra lateral do documento. Em seu arquivo MetaBox.js, adicione o seguinte código:

const MetaBox = ( { postType, metaFields, setMetaFields } ) => {

	if ( 'post' !== postType ) return null;

	return(
		<PluginDocumentSettingPanel 
			title={ __( 'Book details' ) } 
			icon="book"
			initialOpen={ false }
		>
			<PanelRow>
				<TextControl 
					value={ metaFields._meta_fields_book_title }
					label={ __( "Title" ) }
					onChange={ (value) => setMetaFields( { _meta_fields_book_title: value } ) }
				/>
			</PanelRow>
			<PanelRow>
				<TextControl 
					value={ metaFields._meta_fields_book_author }
					label={ __( "Author" ) }
					onChange={ (value) => setMetaFields( { _meta_fields_book_author: value } ) }
				/>
			</PanelRow>
			<PanelRow>
				<TextControl 
					value={ metaFields._meta_fields_book_publisher }
					label={ __( "Publisher" ) }
					onChange={ (value) => setMetaFields( { _meta_fields_book_publisher: value } ) }
				/>
			</PanelRow>
			<PanelRow>
				<DateTimePicker
					currentDate={ metaFields._meta_fields_book_date }
					onChange={ ( newDate ) => setMetaFields( { _meta_fields_book_date: newDate } ) }
					__nextRemoveHelpButton
					__nextRemoveResetButton
				/>
			</PanelRow>
		</PluginDocumentSettingPanel>
	);
}

const applyWithSelect = withSelect( ( select ) => {
	return {
		metaFields: select( 'core/editor' ).getEditedPostAttribute( 'meta' ),
		postType: select( 'core/editor' ).getCurrentPostType()
	};
} );

const applyWithDispatch = withDispatch( ( dispatch ) => {
	return {
		setMetaFields ( newValue ) {
			dispatch('core/editor').editPost( { meta: newValue } )
		}
	}
} );

export default compose([
	applyWithSelect,
	applyWithDispatch
])(MetaBox);

Vamos analisar este código.

  • O elemento PluginDocumentSettingPanel faz um novo painel na barra lateral do documento. Nós definimos o título (“Detalhes do livro”) e o ícone, e definimos initialOpen para false, o que significa que inicialmente o painel é fechado.
  • Dentro do PluginDocumentSettingPanel temos três campos de texto e um elemento DateTimePicker que permite que o usuário defina a data de publicação.
  • withSelect fornece acesso à função select que estamos usando para recuperar metaFields e postType. withDispatch fornece acesso à função dispatch, que permite a atualização dos valores dos metadados.
  • Finalmente, a função compose nos permite compor nosso componente com withSelect e withDispatch componentes de ordem superior. Isso dá ao componente acesso às propriedades metaFields e postType e à função setMetaFields.

Salve seu arquivo MetaBox.js e crie um novo artigo em seu site de desenvolvimento WordPress e dê uma olhada na barra lateral do documento. Você deve ver o novo painel de detalhes do Livro.

Um painel de meta box personalizado no Gutenberg.
Um painel de meta box personalizado no Gutenberg.

Agora faça seus testes. Defina os valores dos seus meta fields personalizados e salve o artigo. Depois, recarregue a página e verifique se os valores que você inseriu estão no lugar.

Adicione o bloco que construímos na seção anterior e verifique se tudo está funcionando corretamente.

Adicionando uma barra lateral personalizada para gerenciar metadados de artigos

Se você tiver inúmeros meta fields personalizados para adicionar aos seus artigos ou tipos de artigos personalizados, você também pode criar uma barra lateral de configurações personalizadas especificamente para o seu plugin.

O processo é muito similar ao exemplo anterior, então se você entendeu os passos discutidos na seção anterior, você não terá nenhuma dificuldade em construir uma barra lateral personalizada para Gutenberg.

Novamente:

  1. Crie um novo plugin de bloco com create-block
  2. Registre uma meta box personalizada para o Editor Clássico
  3. Registre os meta fields personalizados no arquivo principal do plugin através da função register_post_meta()
  4. Registre um plugin no arquivo index.js
  5. Construir o componente usando componentes incorporados do Gutenberg

Crie um novo plugin de bloco com a ferramenta create-block

Novamente, para criar um novo plugin de bloco, siga os passos discutidos acima. Você pode criar um novo plugin ou editar os scripts construídos nos exemplos anteriores.

Registre uma Meta Box personalizada para o Editor Clássico

Agora registre uma meta box personalizada para garantir a compatibilidade retroativa para sites WordPress que ainda usam o Editor Clássico. O processo é o mesmo descrito na seção anterior.

Registre os Meta Fields personalizados no arquivo principal do plugin

Registre os meta fields personalizados no arquivo principal do plugin através da função register_post_meta().

Registre um plugin no arquivo index.js

Agora crie um arquivo CustomSidebar.js vazio em sua pasta de componentes.

Uma vez feito, mude seu arquivo index.js como segue:

/**
 * Registers a plugin for adding items to the Gutenberg Toolbar
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-sidebar/
 */
import { registerPlugin } from '@wordpress/plugins';

import CustomSidebar from './components/CustomSidebar';
// import MetaBox from './components/MetaBox';

registerPlugin( 'metadata-block', {
    render: CustomSidebar
} );

Com o código acima, primeiramente importamos o componente CustomSidebar e depois dizemos à função registerPlugin para renderizar o novo componente.

Construa o componente usando componentes incorporados do Gutenberg

Em seguida, abra o arquivo CustomSidebar.js e adicione as seguintes dependências:

import { __ } from '@wordpress/i18n';
import { compose } from '@wordpress/compose';
import { withSelect, withDispatch } from '@wordpress/data';
import { PluginSidebar, PluginSidebarMoreMenuItem } from '@wordpress/edit-post';
import { PanelBody, PanelRow, TextControl, DateTimePicker } from '@wordpress/components';

Você deve notar que estamos importando dois novos componentes:

  • PluginSidebar adiciona um ícone na barra de ferramentas do Gutenberg que, quando clicado, exibe uma barra lateral incluindo o conteúdo envolvido no elemento <PluginSidebar /> (O componente também está documentado no GitHub).
  • PluginSidebarMoreMenuItem torna um item de menu em Plugins in More Menu dropdown e pode ser usado para ativar o componente PluginSidebar correspondente (veja também no GitHub).

Agora você pode construir seu componente personalizado:

const CustomSidebar = ( { postType, metaFields, setMetaFields } ) => {
        
    if ( 'post' !== postType ) return null;

    return (
        <>
            <PluginSidebarMoreMenuItem 
                target="metadata-sidebar" 
                icon="book"
            >
                Metadata Sidebar
            </PluginSidebarMoreMenuItem>
            <PluginSidebar 
                name="metadata-sidebar" 
                icon="book" 
                title="My Sidebar"
            >
                <PanelBody title="Book details" initialOpen={ true }>
                    <PanelRow>
                        <TextControl 
                            value={ metaFields._meta_fields_book_title }
                            label={ __( "Title" ) }
                            onChange={ (value) => setMetaFields( { _meta_fields_book_title: value } ) }
                        />
                    </PanelRow>
                    <PanelRow>
                        <TextControl 
                            value={ metaFields._meta_fields_book_author }
                            label={ __("Author", "textdomain") }
                            onChange={ (value) => setMetaFields( { _meta_fields_book_author: value } ) }
                        />
                    </PanelRow>
                    <PanelRow>
                        <TextControl 
                            value={ metaFields._meta_fields_book_publisher }
                            label={ __("Publisher", "textdomain") }
                            onChange={ (value) => setMetaFields( { _meta_fields_book_publisher: value } ) }
                        />
                    </PanelRow>
                    <PanelRow>
                        <DateTimePicker
                            currentDate={ metaFields._meta_fields_book_date }
                            onChange={ ( newDate ) => setMetaFields( { _meta_fields_book_date: newDate } ) }
                            __nextRemoveHelpButton
                            __nextRemoveResetButton
                        />
                    </PanelRow>
                </PanelBody>
            </PluginSidebar>
        </>
    )
}

O passo final é a composição dos componentes com withSelect e withDispatch componentes de ordem superior:

const applyWithSelect = withSelect( ( select ) => {
    return {
        metaFields: select( 'core/editor' ).getEditedPostAttribute( 'meta' ),
        postType: select( 'core/editor' ).getCurrentPostType()
    };
} );

const applyWithDispatch = withDispatch( ( dispatch ) => {
    return {
        setMetaFields ( newValue ) {
            dispatch('core/editor').editPost( { meta: newValue } )
        }
    }
} );

export default compose([
    applyWithSelect,
    applyWithDispatch
])(CustomSidebar);

Salve suas alterações, então verifique a interface do editor. Se você abrir o menu suspenso Options, você verá um novo item Metadata Sidebar sob a seção Plugins. Clicando no novo item, você ativará sua nova barra lateral personalizada.

O componente PluginSidebarMoreMenuItem adiciona um item de menu em Opções - Plugins.
O componente PluginSidebarMoreMenuItem adiciona um item de menu em Opções – Plugins.

O mesmo acontece quando você clica no ícone do livro no canto superior direito.

A barra lateral de configurações do Plugin.
A barra lateral de configurações do Plugin.

Agora volte ao seu site de desenvolvimento e crie um novo artigo no blog. Preencha as meta fields, depois adicione o bloco à tela do editor. Ele deve incluir os mesmos valores meta que você digitou na sua barra lateral personalizada.

Salve o artigo e visualize a página no frontend. Você deve ver seu cartão incluindo o título do livro, autor, editora e data de publicação.

Você encontrará o código completo deste artigo neste resumo público.

Outras leituras

Neste artigo, cobrimos vários tópicos, de seletores a componentes de ordem superior e muito mais. Nós também ligamos os principais recursos que usamos como referência ao longo do artigo.

No entanto, se você quiser se aprofundar nesses tópicos, verifique também estes recursos adicionais:

Documentação do Gutenberg e recursos oficiais do WordPress

Mais recursos oficiais

Recursos adicionais da comunidade

Leituras úteis do site Kinsta

Resumo

Neste terceiro artigo de nossa série sobre o desenvolvimento de blocos Gutenberg, cobrimos novos tópicos avançados que devem tornar o quadro delineado nos artigos anteriores sobre o desenvolvimento de blocos dinâmicos e estáticos  mais completo.

Agora você deve conseguir aproveitar o potencial dos campos personalizados no Gutenberg e criar sites WordPress mais avançados e funcionais.

Com as habilidades que você adquiriu com nossos artigos sobre desenvolvimento de blocos, você também deve ter uma boa ideia de como desenvolver componentes React fora do WordPress. Afinal de contas, Gutenberg é um SPA baseado em React.

Agora é com você! Você já criou blocos Gutenberg que usam meta fields personalizados? Compartilhe suas criações conosco nos comentários abaixo.

Carlo Daniele Kinsta

Carlo é um apaixonado por webdesign e desenvolvimento frontend. Ele tem mais de 10 anos de experiência com WordPress e colaborou com diversas universidades e instituições educacionais na Itália e na Europa. Carlo já publicou inúmeros artigos e guias sobre WordPress, tanto em sites italianos quanto internacionais, além de revistas impressas. Você pode seguir ele no LinkedIn e no X.