Cómo adaptar su complemento para Gutenberg: Parte 1 (API de bloque)

Cómo adaptar su complemento para Gutenberg: Parte 1 (API de bloque)

“Tengo un complemento” tu dices, “¿Cómo lo preparo para Gutenberg?”

La historia es simple; Gutenberg es la nueva experiencia de editor en WordPress, que se fusionará con el kernel en la próxima versión principal. Muchos complementos que no siguen esto se volverá obsoleto. Por lo tanto, es esencial que adapte su complemento para Gutenberg antes de que sea demasiado tarde.

¿A quién le preocupa?

Casi todos los complementos que tengan algo que ver con el editor de publicaciones se verán afectados por Gutenberg. Por ejemplo, si su complemento agrega un botón en TinyMCE y luego coloca un código corto en el editor, malas noticias; ese será el final.

Adapte su complemento para Gutenberg: Parte 1 (API de bloque)

“¿Tengo que adaptar mis complementos para Gutenberg?”

Entonces, ¿qué complementos deben actualizarse para Gutenberg? Todos los complementos que funcionan con:

  • Metaboxes personalizados
  • Códigos cortos
  • Botones TinyMCE
  • o cualquier función de editor

Si bien algunos complementos todavía funcionan con Gutenberg, como un complemento que agrega un metabox simple, por ejemplo, no será una experiencia tan fluida para sus usuarios.

Même les shortcodes continueront de fonctionner comme avant, mais il ne s’agira que d’un nœud de texte brut dans l’éditeur, tandis que tous les plugins de shortcode pour Gutenberg suivront son interface utilisateur en bloc et seront plus faciles à utiliser pour los usuarios.

Entonces, sí, los usuarios preferirán los complementos diseñados para la experiencia de Gutenberg. Y aquellos que se quedarán atrás serán reemplazados por un complemento de la competencia.

Solo para darle una idea, aquí hay un ejemplo de cómo se ve la experiencia de usuario estándar del editor anterior con uno de nuestros complementos. (a), entonces, ¿cómo se ve en Gutenberg? (B) – con el complemento optimizado para esto.

¡No tengas miedo! Estamos aquí para ayudarlo a preparar sus complementos para Gutenberg. Hay muchas formas de integrar su complemento con Gutenberg, dependiendo de cómo funcione su complemento, que cubriremos en este artículo.

Cosas que debe saber de antemano

Gutenberg está escrito en React. Y los complementos de Gutenberg están codificados en JavaScript, lo que también puede ser una transición difícil para los desarrolladores que solo codifican en PHP. Si bien no necesita saber React para crear complementos para Gutenberg, necesitará una comprensión básica de JavaScript. Si ha trabajado en React y JSX antes, esto será por razones similares para usted.

Aunque no hay suficiente documentación oficial de Gutenberg, su repositorio de Github contiene mucha información valiosa para los desarrolladores. Si desea aprender el desarrollo de Gutenberg en profundidad, debe estar atento a todo lo que sucede en el repositorio de GitHub de Gutenberg, ya que el proyecto avanza muy rápido y las cosas cambian todos los días.

Cómo adaptar su complemento para Gutenberg

La API de Gutenberg nos ofrece muchas formas de ampliar el editor, como Block API, Shortcode API, etc. Qué API usar depende del tipo de complemento que estamos construyendo.

Si su complemento es un complemento de código corto simple, entonces Block API se puede usar para crear un buen bloque para el editor. Pero si su complemento usa metaboxes complejos donde un bloque no es suficiente, podemos usar la API de la barra lateral.

Además, utilizaremos una pila moderna de herramientas de desarrollo de JavaScript, como NodeJS, NPM, webpack y ESNext. Le proporcionaremos archivos de muestra para que no tenga que preocuparse por configurar su entorno de desarrollo.

En este artículo veremos cómo hacer que su complemento Gutenberg sea compatible con API Block. Cubriremos los otros métodos (API de barra lateral, panel de publicaciones, barra de estado y API similares) en la segunda parte si es necesario.

Puede encontrar todos los ejemplos mencionados en este repositorio de GitHub.

Entorno de desarrollo de Gutenberg

Desarrollar para Gutenberg requiere que configure muchas herramientas, como NPM, Webpack, Babel y JSX. Requiere mucho tiempo y esfuerzo, por eso hemos preparado el entorno para ti.

Gutenberg Boilerplate es un complemento con una configuración y ejemplos mínimos de desarrollo de Gutenberg. Contiene un bloque de ejemplo y una barra lateral. Puede usarlo para extender su bloque personalizado.

Placa de caldera Gutenberg

Puedes bifurcar o clonar Depósito de placas de caldera Gutenberg para usted / wp-content / plugins / y utilícelo como entorno de desarrollo.

Después de eso, debe instalar NodeJS en su máquina para comenzar. Vaya a la carpeta Gutenberg Boilerplate y ejecute npm install

A partir de este momento, debe conocer tres comandos que utilizará durante el proceso de desarrollo:

  • npm install – Instale las dependencias del proyecto cuando clone el proyecto.
  • npm run dev – Compilar el código durante el proceso de desarrollo. Debe ejecutarlo una vez y continuará monitoreando los cambios.
  • npm run build – Compile el código para una compilación optimizada después de que se complete el proceso de desarrollo.

API de bloque

Los bloques son el bloque de construcción fundamental de Gutenberg, al ser un editor basado en bloques. Block API te permite crear bloques para Gutenberg. Puede crear bloques que pueden representar HTML básico, códigos cortos o incluso crear bloques dinámicos para mostrar, por ejemplo, sus últimas publicaciones.

El proceso basado en un complemento existente

En nuestro ejemplo, adoptaremos un código corto Click to Tweet en un bloque de Gutenberg. Este código abreviado de Click to Tweet muestra un área de Tweet con su texto y un botón para twittear este texto. Así:

Haga clic para twittear el diseño

Nuestro shortcode se ve así:

[clicktotweet tweet="Text to be displayed" tweetsent="Text to be tweeted" button="Tweet" theme="click-to-tweet"]

Nuestro shortcode tiene cuatro parámetros:

  • tweet: Texto que aparece en su sitio.
  • tweetsent: Texto que va a Twitter.
  • button: Texto del botón Tweet.
  • theme: Es click-to-tweet o click-to-tweet-alt como el tema de la caja.

Adaptación de complementos para Gutenberg con Block API

Hay dos formas de hacer esto con Gutenberg, o podemos renderizar el HTML en el front-end o podemos usar nuestro bloque de Gutenberg para renderizar el shortcode en el front-end. Para este artículo, haremos lo último.

Todo el código está disponible en Repositorio de complementos de Hello Gutenberg en GitHub. Puede clonar el repositorio para ver el complemento en acción o modificar el código.

Cola de scripts / estilos para Gutenberg

Primero, necesitamos poner en cola nuestros scripts y estilos en el editor de Gutenberg usando enqueue_block_assets:

/**
 * Enqueue front end and editor JavaScript and CSS
 */
function hello_gutenberg_scripts() {
	$blockPath="/dist/block.js";
	$stylePath="/dist/block.css";

	// Enqueue the bundled block JS file
	wp_enqueue_script(
		'hello-gutenberg-block-js',
		plugins_url( $blockPath, __FILE__ ),
		[ 'wp-i18n', 'wp-blocks', 'wp-editor', 'wp-components' ],
		filemtime( plugin_dir_path(__FILE__) . $blockPath )
	);

	// Enqueue frontend and editor block styles
	wp_enqueue_style(
		'hello-gutenberg-block-css',
		plugins_url( $stylePath, __FILE__ ),
		'',
		filemtime( plugin_dir_path(__FILE__) . $stylePath )
	);

}

// Hook scripts function into block editor hook
add_action( 'enqueue_block_assets', 'hello_gutenberg_scripts' );
Hemos agregado cuatro dependencias a nuestro script que usaremos en nuestro bloque. Primero echemos un vistazo a estas dependencias:

wp-i18n es la versión de Gutenberg de las funciones de internacionalización, como __ (). wp-blocks se utiliza para registerBlockType función que guarda su bloque. Usamos scripts wp-editor y wp-components para varios componentes en nuestro bloque.

Ahora que hemos puesto en cola sus activos, podemos comenzar a escribir nuestro bloque para /src/block.js bajar ó dejar algo.

Importar dependencias

Si está utilizando Gutenberg Boilerplate, su block.js El archivo debe tener una estructura de bloques básica que pueda usar para crear complementos para Gutenberg:

/**
 * Internal block libraries
 */
const { __ } = wp.i18n;

const { registerBlockType } = wp.blocks;

/**
 * Register block
 */
export default registerBlockType( 'gutenberg-boilerplate/block', {
	// Block Title
	title: __( 'Gutenberg Boilerplate' ),
	// Block Description
	description: __( 'An example block.' ),
	// Block Category
	category: 'common',
	// Block Icon
	icon: 'admin-site',
	// Block Keywords
	keywords: [
		__( 'Boilerplate' ),
		__( 'Hello World' ),
		__( 'Example' ),
	],
	attributes: {
	},
	// Defining the edit interface
	edit: props => {
		return (
			<h2>{ __( 'Hello Backend' ) }</h2>
		);
	},
	// Defining the front-end interface
	save: props => {
		return (
			<h2>{ __( 'Hello Frontend' ) }</h2>
		);
	},
});
Tu puedes correr npm run dev para empezar a compilar nuestro código en tiempo real.

Primero, importaremos todos los componentes y bibliotecas que necesitamos para el bloque superior:

/**
 * Block dependencies
 */

import classnames from 'classnames';

/**
 * Internal block libraries
 */
const { __ } = wp.i18n;

const { registerBlockType } = wp.blocks;

const {
	RichText,
	InspectorControls,
	BlockControls,
} = wp.editor;

const {
	PanelBody,
	TextareaControl,
	TextControl,
	Dashicon,
	Toolbar,
	Button,
	Tooltip,
} = wp.components;

Las primeras importaciones nombres de clases que instalamos usando npm para usar múltiples clases en nuestro código, porque JSX no permite múltiples clases en elementos.

Aprenderemos sobre otros componentes que importamos a medida que los usemos.

Definir atributos

Ahora definiremos cuatro atributos para nuestro bloque de Gutenberg, idénticos a nuestro shortcode:

attributes: {
	tweet: {
		type: 'string',
	},
	tweetsent: {
		type: 'string',
	},
	button: {
		type: 'string',
		default: __( 'Tweet' ),
	},
	theme: {
		type: 'boolean',
		default: false,
	},
},

Como puede ver, todos los atributos son iguales a nuestro shortcode. Todos los atributos tienen una clave de tipo, que le dice a Gutenberg su tipo de datos. Puede utilizar cadena, número, booleano y objeto como tipos aceptados.

Algunos de los atributos también contienen un valor predeterminado. Los atributos también pueden tener otras propiedades, como fuente y selectores, que no usaremos en nuestro ejemplo, pero puede Lee más sobre ellos aquí.

Modificar interfaz

Ahora crearemos la interfaz de edición para nuestro bloque, que será la pantalla; los usuarios verán esto al editar el bloque en Gutenberg.

Para tener una idea básica, primero podemos codificar nuestro bloque y construirlo reemplazando la siguiente área en nuestro código:

// Defining the edit interface
edit: props => {
	return (
		<h2>{ __( 'Hello Backend' ) }</h2>
	);
},

Con el siguiente código:

// Defining the edit interface
edit: props => {
	return [
		<div className={ props.className }>
			<div className="click-to-tweet">
				<div className="ctt-text">Pumpkins and Penguins</div>
				<p><a href="https://twitter.com/intent/tweet?text=Pumpkins%20and%20Penguins" className="ctt-btn">Tweet</a></p>
			</div>
		</div>
	];
},
Esto debería darle una idea de nuestro resultado final. Se verá algo como esto:

Complementos para Gutenberg

El primer elemento del bloque es el cuadro de texto del tweet. Lo reemplazaremos con un campo de texto editable, similar al bloque de encabezado de Gutenberg.

Usaremos Texto rico componente que importamos previamente para reemplazar nuestro texto codificado.

<div className="ctt-text">
	<RichText
		format="string"
		formattingControls={ [] }
		placeholder={ __( 'Tweet, tweet!' ) }
		onChange={ onChangeTweet }
		value={ props.attributes.tweet }
	/>
</div>

Nuestro componente RichText tiene cinco argumentos. format es una cadena, porque usaremos nuestro código corto para mostrar los elementos en el front-end. Si quisiéramos usar un selector en nuestro atributo, entonces el formato habría sido una matriz.

RichText tiene algunas opciones de formato predeterminadas, como negrita y cursiva, que desactivamos al pasar una matriz vacía en formattingControls argumento.

placeholder es el texto del marcador de posición cuando no hay texto en el campo, y onChange disparará onChangeTweet función cuando ocurre un evento de cambio.

Para terminar, value será el valor de nuestro campo, que se tomará del atributo tweet que definimos anteriormente.

Una vez que hemos definido nuestra área RichText, necesitamos construir onChangeTweet función que se disparará cuando el valor cambie en nuestro campo de texto.

// Definición de la interfaz de edición: props => {const onChangeTweet = value => {props.setAttributes ({tweet: value});  };  volver [
	...rest of the code

We pass value of RichText field to onChangeTweet function, which uses props.setAttributes function to update the value of tweet attribute.

You will see the power of Gutenberg now when you use your block.

RichField in Gutenberg

Isn’t it awesome?

Block Inspector

When building plugins for Gutenberg, you don’t need to reinvent the wheel every time to make option panels for your plugins. Gutenberg provides us with a simplified way to allow block customization and ensures that every user has a consistent experience with built-in UI patterns.

Similarly to RichText component, InspectorControls component adds a sidebar when the block is selected. Something like this:

Gutenberg Inspector Controls

We will also be using TextareaControl and TextControl to add a textarea and text input field to our Inspector area.

We will be adding the following code to your return statement:

!! props.isSelected && (
	<InspectorControls key="inspector">
		<PanelBody title={ __( 'Tweet Settings' ) } >
			<TextareaControl
				label={ __( 'Tweet Text' ) }
				value={ props.attributes.tweetsent }
				onChange={ onChangeTweetSent }
				help={ __( 'You can add hashtags and mentions here that will be part of the actual tweet, but not of the display on your post.' ) }
			/>
			<TextControl
				label={ __( 'Button Text' ) }
				value={ props.attributes.button }
				onChange={ onChangeButton }
			/>
		</PanelBody>
	</InspectorControls>
),
props.isSelected checks to make sure that the Inspector only appears when the block is selected.

TextareaControl and TextControl components, similarly to RichText, have a value and onChange method.

We also need to change the code of your block display to accommodate new changes. In our case, we only need to add Button Text to our block as Tweet Text will be added to the link, so we don’t need to show it in our backend.

You can replace hyperlink in our initial code with the following:

<a className="ctt-btn">
	{ props.attributes.button }
</a>

As mentioned before, we are removing hyperlink from our code because we don’t need to show it in the backend. This will make our block look like so:

Gutenberg Click to Tweet Inspector Controls

Block Inspector can be a potent tool for your block. If your plugin has advanced options that are too complicated for editor area, then you can put them in the Inspector area.

We will add one last option to our block to finish the JavaScript part in the next section.

Block Toolbar

Block Toolbar is another pre-built UI component that we can use to add more options to our block. It will appear above your block when you select it. Example:

Gutenberg Block Toolbar

Ideally, Block Toolbar should contain the primary controls of your block, with Inspector hosting the secondary controls. However, that is debatable and depends on your block.

We will be using the Block Toolbar area to host our alternative style control.

Similar to Block Inspector, we need to add the following code to our return statement to add Block Toolbar to our block:

!! props.isSelected && (
	<BlockControls key="custom-controls">
		<Toolbar
			className="components-toolbar"
		>
			<Tooltip text={ __( 'Alternative Design' ) }>
				<Button
					className={ classnames(
						'components-icon-button',
						'components-toolbar__control',
						{ 'is-active': props.attributes.theme },
					) }
					onClick={ toggletheme }
				>
					<Dashicon icon="tablet" />
				</Button>
			</Tooltip>
		</Toolbar>
	</BlockControls>
),
We use BlockControls and Toolbar components to add a toolbar to our block. Similar to Block Inspector, props.isSelected makes sure our toolbar only appears when we put focus on our block.

We also use Tooltip and Button components for our control. Tooltip component is wrapped around Button component to make sure there’s a tooltip when you hover over the control to give you more context.

Button component is using classnames module that we imported earlier in the article. We used classnames function to give three classes to our control. The third class, is-active, only appears when our theme attribute value is true.

Its onChange function toggles the theme attribute to true/false. In the end, Dashicon components is used to display an icon for our control.

We will also have to change our block code for it to work with the changes. We need to replace the following line:

<div className="click-to-tweet">

With:

<div className={ ( props.attributes.theme ? 'click-to-tweet-alt' : 'click-to-tweet' ) }>

We are checking if the theme attribute is true or false, and assigning a class to our block accordingly.

Now your block should look something like this:

Click to Tweet Toolbar

We have finished the JavaScript-side part of our Gutenberg block. You can find the entire source code of the file here.

Now we will finish our block by handling the server-side output.

Server-side rendering

Gutenberg allows you to use server-side rendering to show your blocks on the front-end. That server-side rendering makes it possible for us to create blocks for shortcodes.

First, we will make our save method to return null by replacing it with the following code:

// Defining the front-end interface
save() {
	// Rendering in PHP
	return null;
},

We will use register_block_type PHP function to register our block type in PHP:

if ( function_exists( 'register_block_type' ) ) {
	// Hook server side rendering into render callback
	register_block_type(
		'hello-gutenberg/click-to-tweet', [
			'render_callback' => 'hello_gutenberg_block_callback',
			'attributes'	  => array(
				'tweet'	 => array(
					'type' => 'string',
				),
				'tweetsent' => array(
					'type' => 'string',
				),
				'button'	=> array(
					'type'	=> 'string',
					'default' => 'Tweet',
				),
				'theme'	 => array(
					'type'	=> 'boolean',
					'default' => false,
				),
			),
		]);  }
Nuestra register_block_type función. Primero le pasamos nuestro nombre de bloque, junto con una matriz de argumentos.

El primer argumento es el render_callback función, que llama a nuestro hello_gutenberg_block_callback función para la representación del lado del servidor.

Después de nuestra devolución de llamada de renderizado, pasamos los atributos como una matriz, similar al archivo block.js, que usamos en nuestra función de devolución de llamada de renderizado.

Nuestra función de devolución de llamada de renderización se ve así:

function hello_gutenberg_block_callback( $attr ) {
	extract( $attr );
	if ( isset( $tweet ) ) {
        $theme = ( $theme === true ? 'click-to-tweet-alt' : 'click-to-tweet' );
		$shortcode_string = '[clicktotweet tweet="%s" tweetsent="%s" button="%s" theme="%s"]';
        return sprintf( $shortcode_string, $tweet, $tweetsent, $button, $theme );
	}
}
Extraemos todos los atributos y luego los devolvemos a nuestro shortcode. Eso es todo lo que se necesita para adaptar sus complementos de código corto para Gutenberg.

Puede encontrar todo el código utilizado en este artículo en este hola-gutenberg depositar.

En la siguiente parte, veremos otras formas de adaptar los complementos existentes para Gutenberg, incluida la API de barra lateral.

Otras lecturas:

Si tiene alguna pregunta sobre cómo adaptar su complemento para Gutenberg, ¡no dude en preguntar en los comentarios!

No olvide unirse a nuestro curso intensivo sobre cómo acelerar su sitio de WordPress. Con algunas correcciones simples, puede reducir su tiempo de carga en un 50-80%:

O inicie la conversación en nuestro Grupo de Facebook para profesionales de WordPress. Encuentre respuestas, comparta consejos y obtenga ayuda de otros expertos en WordPress. Únase a él ahora es gratis)!

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

Ir arriba