wp<\/code>e a desestrutura\u00e7\u00e3o<\/h2>\nQuando estamos em um arquivo Javascript enfileirado no editor Gutenberg, temos acesso a um objeto\/pacote global: wp<\/code>. Este \u00e9 um objeto Javascript muito grande e variado e cont\u00e9m um monte de componentes e fun\u00e7\u00f5es \u00fateis que usaremos para criar blocos. Ao escrever Javascript para blocos personalizados, voc\u00ea se referir\u00e1 wp<\/code>bastante.<\/p>\nPor isso \u00e9 comum, tanto no Javascript moderno quanto no React, desestruturar o que queremos usar dele. Basicamente, significa apenas que definimos vari\u00e1veis \u200b\u200blocais a partir de partes de uma estrutura maior. Por exemplo, a primeira fun\u00e7\u00e3o que usaremos \u00e9 registerBlockType()<\/code>aquela que existe dentro do wp.blocks<\/code>. Poder\u00edamos invocar a fun\u00e7\u00e3o assim:<\/p>\nwp.blocks.registerBlockType();<\/code><\/pre>\nMas \u00e9 mais f\u00e1cil desestruturar assim:<\/p>\n
const { registerBlockType } = wp.blocks;\nregisterBlockType();<\/code><\/pre>\nAgora voc\u00ea pode fazer refer\u00eancia \u00e0 fun\u00e7\u00e3o diretamente sem prefix\u00e1-la com sua estrutura. Fica muito mais \u00fatil quando nos referimos a fun\u00e7\u00f5es ou componentes que repetiremos com frequ\u00eancia.<\/p>\n
Faremos a reestrutura\u00e7\u00e3o nesta s\u00e9rie e, \u00e0 medida que avan\u00e7amos no tutorial, veremos o quanto nosso c\u00f3digo fica mais leg\u00edvel e curto.<\/p>\n
Cadastrando um novo bloco<\/h2>\n
A fun\u00e7\u00e3o para registrar um novo bloco personalizado est\u00e1 registerBlockType()<\/code>dispon\u00edvel no wp.blocks<\/code>pacote. Aceita dois par\u00e2metros; primeiro uma string com o namespace e o nome do bloco e, em segundo lugar, um objeto com a configura\u00e7\u00e3o do bloco completo.<\/p>\nGutenberg espera que todos os blocos tenham um namespace e um nome, definidos com uma barra entre eles. O namespace \u00e9 para garantir que o nome do seu bloco n\u00e3o entre em conflito com nenhum outro bloco que possa usar o mesmo nome. Todos os blocos no WordPress usam o namespace core<\/code>. Por exemplo, o bloco de par\u00e1grafo padr\u00e3o no WordPress tem o nome core\/paragraph<\/code>. Se voc\u00ea escolher outro namespace, tamb\u00e9m poder\u00e1 criar um bloco chamado par\u00e1grafo sem causar problemas.<\/p>\nDecida um namespace de vers\u00e3o de slug que seja exclusivo para voc\u00ea. Vou usar o namespace awp<\/code>(vers\u00e3o curta de A White Pixel) nesta s\u00e9rie.<\/p>\nAbra o arquivo de origem que criamos na \u00faltima etapa; src\/block-awhitepixel-myfirstblock.js<\/code>, em um editor. Primeiro vamos chamar registerBlockType<\/code>de destructured wp.blocks<\/code>, com o nome awp\/firstblock<\/code>. Ajuste seu nome e namespace \u00e0 medida que avan\u00e7a.<\/p>\nconst { registerBlockType } = wp.blocks;\n\u00a0\nregisterBlockType('awp\/firstblock', {\n \/\/ Your block configuration and code here\n});<\/code><\/pre>\nNo segundo par\u00e2metro, o objeto de configura\u00e7\u00e3o do bloco, precisamos definir algumas propriedades para que ele seja registrado com sucesso. Lembre-se que a configura\u00e7\u00e3o do bloco \u00e9 um objeto, o que significa que voc\u00ea precisa escrever tudo como pares chave + valor, separados por v\u00edrgula. Existem algumas propriedades de configura\u00e7\u00e3o poss\u00edveis, ent\u00e3o vamos passar por elas e veremos o c\u00f3digo final no final.<\/p>\n
Requerido: t\u00edtulo<\/h3>\n
A primeira propriedade necess\u00e1ria \u00e9 title<\/code>. Este \u00e9 o nome que aparecer\u00e1 quando voc\u00ea selecionar entre os blocos. Defina esta propriedade como qualquer nome que voc\u00ea queira em uma string.<\/p>\nAdicionaremos o seguinte como t\u00edtulo:<\/p>\n
title: 'My first block',<\/code><\/pre>\nPS: Revisitaremos como escrevemos todas as strings em nosso bloco para garantir que elas possam ser traduzidas na parte 8. Mas, por enquanto, vamos simplificar e simplesmente escrever strings.<\/p>\n
Obrigat\u00f3rio: categoria<\/h3>\n
A propriedade category<\/code>define em qual categoria de bloco seu bloco aparecer\u00e1 quando voc\u00ea selecionar blocos para inser\u00e7\u00e3o no editor. Os valores poss\u00edveis s\u00e3o common<\/code>, formatting<\/code>, layout<\/code>, widgets<\/code>, embed<\/code>.<\/p>\nVamos coloc\u00e1-lo em common<\/code>, a primeira categoria de bloco.<\/p>\ncategory: 'common',<\/code><\/pre>\nOpcional: \u00edcone<\/h3>\n
Se voc\u00ea j\u00e1 usou o Gutenberg, provavelmente notou que todos os blocos t\u00eam \u00edcones. Voc\u00ea pode adicionar um \u00edcone ao seu bloco com uma string que se refere a qualquer um dos Dashicons do WordPress<\/a> ou pode fornecer um svg<\/code>elemento personalizado.<\/p>\nVou escolher apenas um dos dashicons do WordPress, o smiley<\/a> \u2013 mas voc\u00ea pode escolher o que quiser. Observe que voc\u00ea pula a inclus\u00e3o de "dashicons-" no nome da classe do \u00edcone.<\/p>\nicon: 'smiley',<\/code><\/pre>\nOpcional: descri\u00e7\u00e3o<\/h3>\n
Voc\u00ea pode fornecer uma descri\u00e7\u00e3o que ser\u00e1 exibida na barra lateral Configura\u00e7\u00f5es (no lado direito) quando o bloco estiver ativo.<\/p>\n
Vou apenas adicionar um texto r\u00e1pido como exemplo:<\/p>\n
description: 'Learning in progress',<\/code><\/pre>\nOpcional: palavras-chave<\/h3>\n
O Gutenberg suporta uma funcionalidade de pesquisa ao escolher os tipos de bloco. Voc\u00ea pode fornecer uma matriz de poss\u00edveis correspond\u00eancias na propriedade keywords<\/code>. Sem keywords<\/code>voc\u00ea s\u00f3 encontraria seu bloco procurando pelo nome dele.<\/p>\nVou adicionar example<\/code>e test<\/code>, para que possamos encontrar facilmente nosso bloco personalizado ao come\u00e7ar a digitar uma dessas palavras-chave.<\/p>\nkeywords: ['example', 'test'],<\/code><\/pre>\nOpcional: atributos<\/h3>\n
A propriedade attributes<\/code>\u00e9 uma propriedade muito importante que revisitaremos com bastante frequ\u00eancia nesta s\u00e9rie de tutoriais. \u00c9 aqui que voc\u00ea armazena seus dados estruturados e informa\u00e7\u00f5es de entrada do usu\u00e1rio para o seu bloco. Voc\u00ea pode imagin\u00e1-lo como vari\u00e1veis. N\u00e3o vamos adicion\u00e1-lo por enquanto, mas definitivamente voltaremos a isso em breve.<\/p>\n(Tipo de) obrigat\u00f3rio: editar e opcional: salvar<\/h3>\n
Dentro das propriedades edit<\/code>e save<\/code>\u00e9 onde voc\u00ea adicionar\u00e1 todo o seu c\u00f3digo tanto para a sa\u00edda do editor quanto para a renderiza\u00e7\u00e3o do front-end. Ambas as propriedades esperam uma fun\u00e7\u00e3o que deve retornar alguma sa\u00edda.<\/p>\nA propriedade edit<\/code>descreve a estrutura do seu bloco dentro do editor. A save<\/code>propriedade lida basicamente com duas coisas; a sa\u00edda do seu bloco no frontend, mas tamb\u00e9m a estrutura de como seu bloco \u00e9 salvo no banco de dados. Voc\u00ea trabalhar\u00e1 principalmente, edit<\/code>pois \u00e9 aqui que voc\u00ea adiciona entradas para inserir ou escolher coisas e atualizar os dados do bloco. A save<\/code>fun\u00e7\u00e3o n\u00e3o deve atualizar ou editar os dados de forma alguma, deve apenas produzir.<\/p>\nGutenberg precisa ser capaz de reconstruir seu bloco com todas as suas configura\u00e7\u00f5es no editor a partir do que \u00e9 gerado na save<\/code>fun\u00e7\u00e3o (e atributos). Se Gutenberg abrir um post onde a sa\u00edda do bloco salvo anteriormente difere (mesmo que um pouco) do que est\u00e1 definido em salvar, seu bloco se tornar\u00e1 inv\u00e1lido.<\/p>\n![\"Criar](\"https:\/\/wordpress.mediadoma.com\/wp-content\/uploads\/2022\/01\/post-151978-61e4d21609214.png\")
<\/a><\/p>\nPosso garantir que voc\u00ea encontrar\u00e1 muito isso ao desenvolver blocos personalizados. Quando isso acontece, voc\u00ea precisa remover o bloco (dos pontos na barra de ferramentas) e adicion\u00e1-lo novamente. Eu recomendo tamb\u00e9m fazer uma atualiza\u00e7\u00e3o do navegador (F5 ou CTRL+R).<\/p>\n
O WordPress tem uma p\u00e1gina de documenta\u00e7\u00e3o<\/a> dedicada para as fun\u00e7\u00f5es de edi\u00e7\u00e3o e salvamento do bloco, se voc\u00ea quiser saber mais.<\/p>\nQuanto ao nosso primeiro bloco, vamos produzir algo b\u00e1sico. Retornaremos o mesmo para ambos edit<\/code>e save<\/code>; um “:)" envolto em <div><\/code>. Afinal, o \u00edcone do bloco \u00e9 um smiley.<\/p>\nedit:() => { \n return <div>:)<\/div> \n},\nsave:() => { \n return <div>:)<\/div> \n}<\/code><\/pre>\nOutras propriedades<\/h3>\n
Existem propriedades mais opcionais para registerBlockType<\/code>; parent<\/code>, supports<\/code>, transforms<\/code>, example<\/code>e styles<\/code>. Vamos ignor\u00e1-los por enquanto, pois a maioria \u00e9 para constru\u00e7\u00e3o de blocos mais avan\u00e7ada ou personalizada. Se voc\u00ea estiver interessado em ler mais sobre isso, d\u00ea uma olhada na documenta\u00e7\u00e3o do WordPress<\/a>.<\/p>\nC\u00f3digo do bloco de registro final<\/h2>\n
Nosso c\u00f3digo agora se parece com isso.<\/p>\n
const { registerBlockType } = wp.blocks;\n\u00a0\nregisterBlockType('awp\/firstblock', {\n title: 'My first block',\n category: 'common',\n icon: 'smiley',\n description: 'Learning in progress',\n keywords: ['example', 'test'],\n edit: () => { \n return <div>:)<\/div> \n },\n save: () => { \n return <div>:)<\/div> \n }\n});<\/code><\/pre>\nCom isso temos o suficiente para que nosso bloco seja registrado com sucesso como um bloco personalizado. Vamos ver na pr\u00e1tica dentro do editor Gutenberg.<\/p>\n
Voc\u00ea se lembrou de compilar seu Javascript? Na etapa anterior aprendemos que n\u00e3o podemos carregar este arquivo Javascript no Gutenberg; precisamos da vers\u00e3o compilada. Voc\u00ea normalmente desenvolveria com a npm run start<\/code>execu\u00e7\u00e3o em segundo plano, ou voc\u00ea pode apenas executar npm run build<\/code>uma vez agora. Isso deve compilar nosso Javascript de origem e coloc\u00e1-lo onde quer que voc\u00ea o tenha definido para ser colocado e nomeado em seu arquivo webpack.config.js<\/code>.<\/p>\nA parte PHP de registrar um bloco<\/h2>\n
Para cada bloco voc\u00ea precisa registrar o arquivo Javascript e isso \u00e9 o mesmo que voc\u00ea registraria qualquer outro script no WordPress \u2013 usando [wp_register_script](https:\/\/developer.wordpress.org\/reference\/functions\/wp_register_script\/)()<\/code>. Observe que registramos o script, n\u00e3o o enfileiramos. Isso ocorre porque tamb\u00e9m precisamos chamar uma fun\u00e7\u00e3o PHP para registrar cada bloco personalizado, e essa fun\u00e7\u00e3o \u00e9 respons\u00e1vel por enfileirar o script quando necess\u00e1rio.<\/p>\nEu prefiro manter o c\u00f3digo relacionado ao Gutenberg em um arquivo separado em meus temas. Mas voc\u00ea pode, e iremos neste tutorial, simplesmente escrever todo o c\u00f3digo PHP diretamente dentro do tema functions.php<\/code>para simplificar.<\/p>\nEu recomendo usar o init<\/code>gancho para sua fun\u00e7\u00e3o, e n\u00e3o enqueue_block_assets<\/code>. Podemos colocar ambos registrando o script e registrando o bloco juntos.<\/p>\nadd_action('init', function() {\n wp_register_script('awp-myfirstblock-js', get_template_directory_uri(). '\/assets\/js\/gutenberg\/block-awhitepixel-myfirstblock.js');\n\u00a0\n register_block_type('awp\/firstblock', [\n 'editor_script' => 'awp-myfirstblock-js',\n ]);\n});<\/code><\/pre>\nA fun\u00e7\u00e3o PHP que usaremos para registrar um novo bloco \u00e9 [register_block_type](https:\/\/developer.wordpress.org\/reference\/functions\/register_block_type\/)()<\/code>. Da mesma forma que o Javascript registerBlockType()<\/code>aceita dois par\u00e2metros; o namespace e o nome do bloco e um array com argumentos. Certifique-se de fornecer exatamente o mesmo namespace e nome em PHP e em Javascript.<\/p>\nNo segundo argumento existem alguns argumentos poss\u00edveis (alguns dos quais voltaremos mais tarde nesta s\u00e9rie). Mas o mais importante \u00e9 editor_script<\/code>onde voc\u00ea fornece o handle (primeiro par\u00e2metro de wp_register_script()<\/code>) do script registrado.<\/p>\nE \u00e9 isso!<\/p>\n
Nosso bloco no editor Gutenberg<\/h2>\n
Agora, quando voc\u00ea atualizar seu editor em algum post, voc\u00ea deve encontrar nosso bloco – abrindo a categoria Comum ou pesquisando qualquer uma das palavras-chave ou nome que voc\u00ea forneceu.<\/p>\n
![\"Criar](\"https:\/\/wordpress.mediadoma.com\/wp-content\/uploads\/2022\/01\/post-151978-61e4d216d1cdb.png\")
<\/a>![\"Criar](\"https:\/\/wordpress.mediadoma.com\/wp-content\/uploads\/2022\/01\/post-151978-61e4d217e1762.gif\")
<\/a><\/p>\nNosso bloco renderiza um simples “:)” tanto no editor quanto no frontend. A partir de agora voc\u00ea n\u00e3o pode editar nada no bloco, mas \u00e9 isso que vamos aprender nos pr\u00f3ximos passos!<\/p>\n