Ao longo dos anos, examinamos o Gutenberg de diferentes perspectivas. Avaliamos as funcionalidades do editor, fizemos comparações com outros construtores de páginas e desenvolvemos blocos personalizados, tanto estáticos quanto dinâmicos, entre outras iniciativas.
Com as versões mais recentes do WordPress, novos recursos e ferramentas permitem que você crie layouts complexos com mais facilidade, enriquecendo e aprimorando a funcionalidade do editor de blocos sem a necessidade de criar blocos personalizados.
Graças à introdução dos padrões de blocos e de ferramentas para desenvolvedores, como a API de Vinculação de Blocos (API Block Bindings), existem menos casos de uso para blocos personalizados. Agora, é possível criar estruturas de blocos complexas, injetar valores de metadados no conteúdo e automatizar boa parte do fluxo de trabalho sem sair da interface do editor. Em resumo, hoje o WordPress permite criar sites complexos com muito menos esforço.
Adicionar controles e ferramentas personalizadas ao editor pode ajudar a tornar o processo de criação de conteúdo mais fluido. Por exemplo, pode ser necessário adicionar um painel à barra lateral de artigos para incluir funcionalidades ou criar uma barra lateral personalizada para gerenciar múltiplos campos de metadados.
Vamos começar!
Como criar um plugin de editor de blocos sem criar um bloco personalizado
O WordPress fornece uma ferramenta de linha de comando conveniente que permite que você instale um ambiente de desenvolvimento Node.js local com todos os arquivos e dependências necessários para criar um bloco personalizado. Basta digitar npx @wordpress/create-block na ferramenta de linha de comando, aguardar alguns segundos e você estará pronto.
No entanto, criar a estrutura de um bloco personalizado não é necessário quando você só precisa adicionar uma barra lateral ou um painel de configurações simples. Nesse caso, é necessário criar um plugin Gutenberg.
O WordPress não oferece uma ferramenta para automatizar o processo de criação de um plugin para o Gutenberg, então será preciso fazê-lo manualmente. Mas não se preocupe. O processo é relativamente simples, e vamos guiá-lo. Estes são os passos a seguir:
1. Baixe e instale um ambiente de desenvolvimento local
Você deve começar pelo princípio: Embora você possa desenvolver seu plugin Gutenberg em um ambiente remoto, pode ser mais conveniente instalar um site WordPress de desenvolvimento localmente. Você pode usar qualquer ambiente baseado em PHP e MySQL. Entre as várias alternativas disponíveis, recomendamos o DevKinsta. Ele é gratuito, completo, fácil de usar e 100% compatível com a hospedagem da Kinsta.
2. Baixe e instale o Node.js e o npm
Baixe o Node.js em nodejs.org e instale em seu computador. Isso também instalará o npm, o gerenciador de pacotes do Node.
Depois disso, abra a sua ferramenta de linha de comando e execute os comandos node -v e npm -v. Isso exibirá as versões instaladas do Node.js e do npm.
3. Crie a pasta do seu plugin
Crie uma nova pasta em wp-content/plugins e renomeie-a para my-sidebar-plugin ou algo semelhante. Lembre-se de que esse nome deve refletir o nome do seu plugin.
Abra o terminal, navegue até a pasta do plugin e inicialize um projeto npm com o seguinte comando:
npm init -yIsso criará um arquivo package.json básico.
4. Instale as dependências
Em sua ferramenta de linha de comando, digite o seguinte comando:
npm install @wordpress/plugins @wordpress/scripts --save-dev@wordpress/pluginsinstala o módulopluginspara WordPress.@wordpress/scriptsinstala uma coleção de scripts reutilizáveis para o desenvolvimento no WordPress.
Após a instalação, uma nova pasta node_modules será adicionada ao projeto.
Agora, abra o arquivo package.json e atualize os scripts conforme mostrado abaixo:
{
"name": "my-sidebar-plugin",
"version": "1.0.0",
"main": "index.js",
"scripts": {
"build": "wp-scripts build",
"start": "wp-scripts start"
},
"keywords": [],
"author": "",
"license": "ISC",
"description": "",
"devDependencies": {
"@wordpress/plugins": "^7.14.0",
"@wordpress/scripts": "^30.7.0"
}
}Agora você pode verificar a pasta do plugin:
5. Crie os arquivos do plugin
No diretório do plugin, crie um novo arquivo .php e dê a ele o mesmo nome da pasta. Em nosso exemplo, ele é my-sidebar-plugin.php.
Abra o arquivo e cole o seguinte código para registrar o plugin no servidor:
<?php
/**
* Plugin Name: My Sidebar Plugin
*/
function my_sidebar_plugin_register_script() {
wp_enqueue_script(
'my_sidebar_plugin_script',
plugins_url( 'build/index.js', __FILE__ ),
array( 'wp-plugins', 'wp-edit-post' ),
filemtime( plugin_dir_path( __FILE__ ) . 'build/index.js' )
);
}
add_action( 'enqueue_block_editor_assets', 'my_sidebar_plugin_register_script' );Em seguida, crie uma pasta src no diretório do seu plugin. Nessa pasta, crie um novo arquivo index.js com o seguinte código:
import { registerPlugin } from '@wordpress/plugins';
import { PluginSidebar } from '@wordpress/edit-post';
const MyPluginSidebar = () => (
<PluginSidebar
name="my-sidebar-plugin"
title="My Sidebar Plugin"
>
<div>
Hello my friends!
</div>
</PluginSidebar>
);
registerPlugin( 'my-sidebar-plugin', {
render: MyPluginSidebar,
} );6. Compile o código
Agora, só falta compilar o projeto. No terminal, execute o seguinte comando:
npm run buildIsso cria uma pasta build com os arquivos compactados do projeto.
Quando terminar, navegue até a tela Plugins no painel do WordPress e ative o plugin. Crie um novo artigo ou página e clique no ícone do plugin no canto superior direito para exibir sua barra lateral personalizada.
7. Desenvolvimento e build
Colocamos o arquivo index.js na pasta src. O uso da pasta src é uma convenção comum no desenvolvimento de plugins e temas do WordPress, o que facilita o entendimento do código por outros desenvolvedores.
Ao colocar o código JS na pasta src, você pode usar o comando npm start ou npm run start para iniciar um ambiente de desenvolvimento que monitora os scripts e recompila automaticamente o código quando necessário. Quando você terminar o desenvolvimento, o comando npm build ou npm run build compilará o código JavaScript na pasta build, que conterá o código otimizado para produção.
Agora, vamos colocar em prática o que aprendemos e modificar o plugin que criamos na seção anterior para adicionar um novo painel à barra lateral do editor de artigos para gerenciar os campos personalizados.
Como criar uma barra lateral adicional para gerenciar campos de metadados de artigos
Nosso objetivo é criar uma barra lateral personalizada que contenha um painel com um único campo de texto para adicionar e editar campos de metadados personalizados.
Antes de prosseguir, vale mencionar que seria possível utilizar uma meta box personalizada para alcançar o mesmo objetivo. Com o WordPress 6.7, as meta boxes foram aprimoradas e agora são totalmente compatíveis com o editor de blocos. Diante disso, você pode se perguntar por que gerenciar campos de metadados a partir de uma barra lateral personalizada em vez de uma meta box.
A resposta é que uma barra lateral permite aproveitar componentes integrados do WordPress, facilitando a criação de interfaces mais amigáveis e com controles avançados, que também serão familiares para os usuários.
Dito isso, aqui está o processo para criar uma barra lateral personalizada que permita gerenciar campos personalizados diretamente no editor.
my-sidebar-plugin.php
Etapa 1: Registrar o metadado do artigo
Primeiro, você precisa registrar o campo de metadados. Adicione o seguinte código ao arquivo principal do plugin:
function my_sidebar_plugin_register_meta() {
register_post_meta(
'post',
'meta_fields_book_title',
array(
'show_in_rest' => true,
'type' => 'string',
'single' => true,
'sanitize_callback' => 'sanitize_text_field',
'label' => __( 'Book title', 'my-sidebar-plugin' ),
'auth_callback' => function() {
return current_user_can( 'edit_posts' );
}
)
);
}
add_action( 'init', 'my_sidebar_plugin_register_meta' );A função register_post_meta aceita três argumentos:
- O tipo de artigo: Define para qual tipo de artigo a chave de metadados será registrada. Caso seja definida como uma string vazia (
""), a chave será registrada para todos os tipos de artigos existentes. - A chave de metadados a ser registrada: Observe que não estamos usando um underscore (
_) no início do nome da chave. Prefixar a chave com um underscore ocultará o campo personalizado, o que pode ser desejado em uma meta box. No entanto, ocultar o campo impede que ele seja usado pela API de Vinculação de Blocos no conteúdo do artigo. - Um array de argumentos: É necessário definir
show_in_restcomotrue. Isso expõe o campo de metadados à API REST, permitindo vinculá-lo aos atributos de bloco. Para os outros atributos, consulte a documentação da função.
Etapa 2: Registrar uma meta box
Para garantir a compatibilidade retroativa do seu plugin, você precisa registrar uma meta box personalizada. Isso permite que os usuários gerenciem campos personalizados mesmo no editor clássico. Adicione o seguinte código ao arquivo PHP do seu plugin:
/**
* Register meta box
*
* @link https://developer.wordpress.org/reference/functions/add_meta_box/
*
*/
function my_sidebar_plugin_register_meta_box(){
add_meta_box(
'book_meta_box', // Unique ID
__( 'Book details' ), // Box title
'my_sidebar_plugin_meta_box_callback', // Content callback
array( 'post' ), // Post types
'advanced', // context
'default', // priority
array('__back_compat_meta_box' => true) // hide the meta box in Gutenberg
);
}
add_action( 'add_meta_boxes', 'my_sidebar_plugin_register_meta_box' );Agora declare o callback que cria o formulário:
/**
* Build meta box form
*
* @link https://developer.wordpress.org/reference/functions/wp_nonce_field/
* @link https://developer.wordpress.org/reference/functions/get_post_meta/
*
*/
function my_sidebar_plugin_meta_box_callback( $post ){
wp_nonce_field( 'my_sidebar_plugin_save_meta_box_data', 'my_sidebar_plugin_meta_box_nonce' );
$title = get_post_meta( $post->ID, 'meta_fields_book_title', true );
?>
<div class="inside">
<p><strong><?php echo __( 'Book title', 'my-sidebar-plugin' ); ?></strong></p>
<p><input type="text" id="meta_fields_book_title" name="meta_fields_book_title" value="<?php echo esc_attr( $title ); ?>" /></p>
</div>
<?php
}Em seguida, escreva a função para salvar seus metadados no banco de dados:
/**
* Save metadata
*
* @link https://developer.wordpress.org/reference/functions/wp_verify_nonce/
* @link https://developer.wordpress.org/reference/functions/current_user_can/
* @link https://developer.wordpress.org/reference/functions/sanitize_text_field/
* @link https://developer.wordpress.org/reference/functions/update_post_meta/
*
*/
function my_sidebar_plugin_save_meta_box_data( $post_id ) {
if ( ! isset( $_POST['my_sidebar_plugin_meta_box_nonce'] ) )
return;
if ( ! wp_verify_nonce( $_POST['my_sidebar_plugin_meta_box_nonce'], 'my_sidebar_plugin_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;
$title = sanitize_text_field( $_POST['meta_fields_book_title'] );
update_post_meta( $post_id, 'meta_fields_book_title', $title );
}
add_action( 'save_post', 'my_sidebar_plugin_save_meta_box_data' );Não vamos nos aprofundar nesse código, pois ele está além do escopo deste artigo. No entanto, você pode encontrar todas as informações necessárias seguindo os links nos cabeçalhos das funções.
Por último, precisamos adicionar o arquivo index.js do plugin na fila de scripts do WordPress:
function my_sidebar_plugin_register_script() {
wp_enqueue_script(
'my_sidebar_plugin_script',
plugins_url( 'build/index.js', __FILE__ ),
array( 'wp-plugins', 'wp-edit-post' ),
filemtime( plugin_dir_path( __FILE__ ) . 'build/index.js' )
);
}
add_action( 'enqueue_block_editor_assets', 'my_sidebar_plugin_register_script' );Isso é tudo para o arquivo PHP. Em seguida, precisamos escrever o código JS.
index.js
O arquivo index.js está localizado na pasta src, onde você armazena os arquivos JS durante a fase de desenvolvimento.
Abra o index.js e adicione as seguintes declarações import:
import { __ } from '@wordpress/i18n';
import { registerPlugin } from '@wordpress/plugins';
import { PluginSidebar } from '@wordpress/editor';
import { PanelBody, PanelRow, TextControl } from '@wordpress/components';
import { useSelect } from '@wordpress/data';
import { useEntityProp } from '@wordpress/core-data';Você precisa desses recursos para criar a barra lateral com os controles necessários.
Em seguida, você precisa criar o componente da barra lateral:
const MyPluginSidebar = () => {
const postType = useSelect(
( select ) => select( 'core/editor' ).getCurrentPostType(),
[]
);
const [ meta, setMeta ] = useEntityProp( 'postType', postType, 'meta' );
const bookTitle = meta ? meta[ 'meta_fields_book_title' ] : '';
const updateBookTitleMetaValue = ( newValue ) => {
setMeta( { ...meta, meta_fields_book_title: newValue } );
};
if ( postType === 'post' ) {
return (
<PluginSidebar
name="my-sidebar-plugin"
icon="book"
title="My plugin sidebar"
>
<PanelBody title="Book details" initialOpen={ true }>
<PanelRow>
<TextControl
value={ bookTitle }
label={ __( "Book title" ) }
onChange={ updateBookTitleMetaValue }
__nextHasNoMarginBottom
/>
</PanelRow>
</PanelBody>
</PluginSidebar>
);
}
};
registerPlugin( 'my-sidebar-plugin', {
render: MyPluginSidebar,
} );A função registerPlugin registra o plugin e renderiza o componente chamado MyPluginSidebar.
A função MyPluginSidebar declara algumas constantes e retorna o código JSX do componente.
useSelecté um hook personalizado para recuperar propriedades de seletores registrados. Utilizamos para obter o tipo de artigo atual. Consulte também este artigo do WordPress Developer Blog.useEntityPropretorna um array de campos de metadados e uma função setter para definir novos valores de metadados. Consulte também a referência on-line.updateBookTitleMetaValueé um manipulador de eventos que salva o valor do campo de metadadosbookTitle.
Utilizamos alguns componentes integrados para construir a barra lateral:
PluginSidebarpermite adicionar itens à barra de ferramentas das telas do editor de artigo ou site. (Consulte a referência do componente.)PanelBodycria um contêiner colapsável que pode ser aberto ou fechado. (Consulte a referência do componente.)PanelRowé um contêiner genérico para linhas dentro de umPanelBody. (Consulte a referência do componente.)TextControlé um campo de entrada de linha única que pode ser usado para entrada de texto livre. (Consulte a referência do componente.)
Agora, execute o comando npm run build, ative o plugin e crie um novo artigo. Um novo ícone de livro deve aparecer na barra lateral superior. Clicando nesse ícone, a barra lateral do plugin será exibida.
E se você não precisar de uma nova barra lateral, mas quiser exibir seu campo personalizado na barra lateral integrada do editor de artigos? Basta substituir PluginSidebar por PluginDocumentSettingPanel. Aqui está o novo código do arquivo index.js:
import { __ } from '@wordpress/i18n';
import { registerPlugin } from '@wordpress/plugins';
import { PluginDocumentSettingPanel } from '@wordpress/edit-post';
import { PanelBody, PanelRow, TextControl } from '@wordpress/components';
import { useSelect } from '@wordpress/data';
import { useEntityProp } from '@wordpress/core-data';
const MyPluginSidebar = () => {
const postType = useSelect(
( select ) => select( 'core/editor' ).getCurrentPostType(),
[]
);
const [ meta, setMeta ] = useEntityProp( 'postType', postType, 'meta' );
const bookTitle = meta ? meta[ 'meta_fields_book_title' ] : '';
const updateBookTitleMetaValue = ( newValue ) => {
setMeta( { ...meta, meta_fields_book_title: newValue } );
};
if ( postType === 'post' ) {
return (
<PluginDocumentSettingPanel
name="my-sidebar-plugin"
title="Book details"
className="my-sidebar-plugin"
>
<PanelRow>
<TextControl
value={ bookTitle }
label={ __( "Book title" ) }
onChange={ updateBookTitleMetaValue }
__nextHasNoMarginBottom
/>
</PanelRow>
</PluginDocumentSettingPanel>
);
}
};
registerPlugin( 'my-sidebar-plugin', {
render: MyPluginSidebar,
} );A imagem a seguir mostra o resultado.
Caso de uso: Uma substituição de padrão de bloco para automatizar seu fluxo de trabalho
Agora você pode adicionar um valor ao campo personalizado, e ele estará disponível por meio da API de Vinculação de Blocos para uso com atributos de bloco. Por exemplo, você pode adicionar um bloco de parágrafo ao seu conteúdo e vincular o campo personalizado ao atributo content do parágrafo.
Você pode alterar o valor do seu campo personalizado, e essas alterações serão aplicadas automaticamente ao conteúdo do seu parágrafo.
Se você está se perguntando se há mais possibilidades com campos personalizados e a API de Vinculação de Blocos, a resposta é sim! Os padrões de bloco e a API de Vinculação de Blocos permitem automatizar todo o processo de criação de conteúdo.
Para começar, crie um padrão com pelo menos um cabeçalho ou parágrafo. Neste exemplo, criamos um padrão de bloco com um bloco de colunas, uma imagem, um cabeçalho e alguns blocos de linha, incluindo dois parágrafos cada.
Quando você estiver satisfeito com seu layout, selecione os elementos de agrupamento e crie um padrão sincronizado.
Adicione um nome e uma categoria para o padrão de bloco e certifique-se de sincronizá-lo.
Se você criou o padrão no editor de artigos, selecione-o e clique em Editar original na barra de ferramentas do bloco. Você também pode navegar até a seção Padrões do editor de sites e encontrar o padrão em Meus padrões ou na categoria definida anteriormente.
Abra o Editor de Código e localize o bloco que deseja vincular ao seu campo personalizado. No delimitador do bloco, adicione o seguinte código:
<!-- wp:heading {
"metadata":{
"bindings":{
"content":{
"source":"core/post-meta",
"args":{
"key":"meta_fields_book_title"
}
}
}
}
} -->
Salve o padrão e crie um novo artigo. Adicione o padrão ao seu conteúdo e defina um valor para o campo personalizado. Você verá que o valor será aplicado automaticamente ao padrão.
Agora, você pode explorar mais este plugin. Graças aos campos personalizados e à API de Vinculação de Blocos, é possível adicionar mais campos e controles para preencher seus layouts automaticamente.
Resumo
O desenvolvimento de um bloco personalizado pode ser um desafio. Mas será que você precisa criar um bloco quando pode fazer mais com um padrão de bloco?
Com os avanços nos padrões de blocos e a introdução de recursos avançados para desenvolvedores, como a API de Vinculação de Blocos (API Block Bindings), não é mais necessário criar blocos personalizados para criar sites sofisticados e funcionais. Um simples plugin e um padrão de bloco podem automatizar com eficiência uma parte significativa do seu fluxo de trabalho.
Este tutorial demonstrou como adicionar funcionalidades ao editor de artigos do WordPress por meio de um plugin. No entanto, o que abordamos neste artigo é apenas uma introdução ao que você pode realizar com os recursos robustos que o WordPress oferece atualmente.
Você já explorou esses recursos e adicionou funcionalidades ao editor do WordPress? Se sim, sinta-se à vontade para compartilhar suas experiências e ideias na seção de comentários abaixo.
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.
Deixe um comentário