Cree un panel de personalización utilizando los componentes del editor de bloques de WordPress (Gutenberg)

En nuestra última guía, analizamos la creación de una página de configuración utilizando los componentes del Editor de bloques de WordPress (Gutenberg). En esta guía vamos a ir más allá y usaremos los componentes de Gutenberg dentro del Personalizador de WordPress.

El personalizador con componentes de Gutenberg

requisitos previos

• Haber seguido la guía Crear un complemento para el editor de bloques de WordPress (Gutenberg)
• Haber seguido la guía Usar opciones para almacenar datos en el editor de bloques de WordPress (Gutenberg)
• Haber seguido la guía Agregar puntos de entrada a la guía Crear script de bloque de WordPress
• Haber seguido la guía Crear una página de configuración usando el editor de bloques de WordPress (Gutenberg)

Crear un punto de entrada en el paquete web

Siguiendo con la guía Agregar puntos de entrada a la guía WordPress Create Block Script, cree un nuevo punto de entrada en el webpack.config.jsarchivo extendido que creó en esa guía.

const defaultConfig = require( '@wordpress/scripts/config/webpack.config' );
const path = require( 'path' );

module.exports = {
    ...defaultConfig,
    entry: {
        ...defaultConfig.entry,
        customizer: path.resolve( process.cwd(), 'src', 'customizer.js' ),
    }
};

Cree dos nuevos archivos en su solución:

• /src/customizer.js
• /src/customizer.scss

Los usaremos para crear nuestro complemento.

Registre la configuración y los componentes del personalizador en PHP

Siguiendo las guías en los requisitos previos, abra el archivo PHP raíz del complemento (en este caso wholesome-plugin.php) y agregue lo siguiente:

Registrar el Control Personalizador

Necesitamos crear un control Personalizador personalizado. Agregue el siguiente código a su archivo que generará una llamada que genera el a <div>con una ID a la que nuestro JavaScript puede conectarse.

function wholesomecode_wholesome_plugin_customizer_register( $wp_customize) {

    class Wholesome_Plugin_Gutenberg_Control extends WP_Customize_Control {

        public $type = 'wholesome-plugin-gutenberg-control';

        public function render_content() {}

        public function content_template() {
            ?>
                <div id="wholesome-plugin-customizer"></div>
            <?php
        }
    }

    $wp_customize->register_control_type( 'Wholesome_Plugin_Gutenberg_Control' );
}
add_action( 'customize_register', 'wholesomecode_wholesome_plugin_customizer_register', 10 );

En la parte inferior de este archivo registramos el control con el register_control_typeque nos permite acceder a este control en JavaScript.

Registrar la configuración del personalizador

En el mismo bloque de código necesitamos registrar la configuración que vamos a utilizar en el personalizador. Para hacer eso, agregue el siguiente bloque de código después de la línea que hace el register_control_type.

$wp_customize->add_setting( 'wholesomecode_wholesome_plugin_example_select' );
$wp_customize->add_setting( 'wholesomecode_wholesome_plugin_example_text' );
$wp_customize->add_setting( 'wholesomecode_wholesome_plugin_example_text_2', [ 'type' => 'option' ] );
$wp_customize->add_setting( 'wholesomecode_wholesome_plugin_example_toggle', [ 'type' => 'option' ] );

Tenga en cuenta que se podrá acceder a las dos primeras configuraciones a través de la get_theme_modfunción predeterminada, mientras que las dos configuraciones inferiores pasan los argumentos 'type' => 'option', lo que significa que estas configuraciones se registrarán como campos únicos dentro de la tabla de opciones y se podrá acceder a ellas mediante get_option.

Para estas dos configuraciones inferiores, debemos asegurarnos de que estén registradas a través de register_settingy show_in_restpara truecada una, de modo que se pueda acceder a ellas a través de Gutenberg.

Registre la configuración de ‘Opción’

Registre las dos configuraciones de personalización inferiores (a las que accederemos a través get_optionde) con el siguiente bloque de código:

function wholesomecode_wholesome_plugin_register_settings() {
    register_setting(
        'wholesomecode_wholesome_plugin_settings',
        'wholesomecode_wholesome_plugin_example_text_2',
        [
            'default'      => '',
            'show_in_rest' => true,
            'type'         => 'string',
        ]
    );

    register_setting(
        'wholesomecode_wholesome_plugin_settings',
        'wholesomecode_wholesome_plugin_example_toggle',
        [
            'default'      => '',
            'show_in_rest' => true,
            'type'         => 'string',
        ]
    );
}
add_action( 'init', 'wholesomecode_wholesome_plugin_register_settings', 10 );

Poner en cola los scripts

Finalmente, registre los recursos del personalizador con el siguiente código (consulte la guía Agregar puntos de entrada para obtener más información).

function wholesomecode_wholesome_plugin_customizer_scripts() {
    $dir = __DIR__;

    $script_asset_path = "$dir/build/customizer.asset.php";
    if (! file_exists( $script_asset_path)) {
        throw new Error(
            'You need to run `npm start` or `npm run build` for the "wholesomecode/wholesome-plugin" block first.'
        );
    }
    $customizer_js = 'build/customizer.js';
    $script_asset  = require( $script_asset_path );
    wp_enqueue_script(
        'wholesomecode-wholesome-plugin-customizer-editor',
        plugins_url( $customizer_js, __FILE__ ),
        $script_asset['dependencies'],
        $script_asset['version']
    );
    wp_set_script_translations( 'wholesomecode-wholesome-plugin-block-editor', 'wholesome-plugin' );

    wp_localize_script(
        'wholesomecode-wholesome-plugin-customizer-editor',
        'WholesomePluginSettings',
        [
            'wholesomecode_wholesome_plugin_example_select' => get_theme_mod( 'wholesomecode_wholesome_plugin_example_select', '' ),
            'wholesomecode_wholesome_plugin_example_text'   => get_theme_mod( 'wholesomecode_wholesome_plugin_example_text', '' ),
        ]
    );

    $customizer_css = 'build/customizer.css';
    wp_enqueue_style(
        'wholesomecode-wholesome-plugin-customizer',
        plugins_url( $customizer_css, __FILE__ ),
        ['wp-components'],
        filemtime( "$dir/$customizer_css") );
}
add_action( 'customize_controls_enqueue_scripts', 'wholesomecode_wholesome_plugin_customizer_scripts', 10 );

Tenga en cuenta que también usamos wp_localize_scripten este bloque de código para pasar la configuración a la que accederemos get_theme_moda JavaScript.

Echemos un vistazo a esta parte del código con más detalle:

wp_localize_script(
  'wholesomecode-wholesome-plugin-customizer-editor',
  'WholesomePluginSettings',
  [
    'wholesomecode_wholesome_plugin_example_select' => get_theme_mod( 'wholesomecode_wholesome_plugin_example_select', '' ),
    'wholesomecode_wholesome_plugin_example_text'   => get_theme_mod( 'wholesomecode_wholesome_plugin_example_text', '' ),
  ]
);

Tenga en cuenta que estamos usando las mismas claves de configuración que registramos cuando registramos la configuración del personalizador con $wp_customize->add_settinganterioridad (las que no estaban configuradas para usar una opción).

Cree el panel de personalización en JavaScript

Agregue el siguiente código en el /src/customizer.jsarchivo.

En su mayor parte, este código (el Appcomponente) es una reelaboración del código de la guía Crear página de configuración. Utiliza los mismos componentes y sigue configurando statedesde la API de configuración, pero elimina el botón de guardar y el área de avisos.

import './customizer.scss';

const { api } = wp;

import {
    Panel,
    PanelBody,
    Placeholder,
    SelectControl,
    Spinner,
    TextControl,
    ToggleControl,
} from '@wordpress/components';

import {
    Fragment,
    render,
    Component,
} from '@wordpress/element';

import { __ } from '@wordpress/i18n';

const { customize } = wp;

class App extends Component {
    constructor() {
        super( ...arguments );

        this.state = {
            exampleSelect: '',
            exampleText: '',
            exampleText2: '',
            exampleText3: '',
            exampleToggle: false,
            isAPILoaded: false,
        };
    }

    componentDidMount() {

        api.loadPromise.then(() => {
            this.settings = new api.models.Settings();

            const { isAPILoaded } = this.state;

            if (isAPILoaded === false) {
                this.settings.fetch().then( (response) => {
                    this.setState( {
                        exampleSelect: WholesomePluginSettings[ 'wholesomecode_wholesome_plugin_example_select' ],
                        exampleText: WholesomePluginSettings[ 'wholesomecode_wholesome_plugin_example_text' ],
                        exampleText2: response[ 'wholesomecode_wholesome_plugin_example_text_2' ],
                        exampleText3: response[ 'wholesomecode_wholesome_plugin_example_text_3' ],
                        exampleToggle: Boolean( response[ 'wholesomecode_wholesome_plugin_example_toggle' ] ),
                        isAPILoaded: true,
                    } );
                } );
            }
        } );
    }

    render() {
        const {
            exampleSelect,
            exampleText,
            exampleText2,
            exampleToggle,
            isAPILoaded,
        } = this.state;

        if (! isAPILoaded) {
            return (<Placeholder>
                    <Spinner />
                </Placeholder>
            );
        }

        return (<Fragment>
                <div className="wholesome-plugin__main">
                    <Panel>
                        <PanelBody
                            title={ __( 'Panel Body One', 'wholesome-plugin') }
                            icon="admin-plugins"
                        >
                            <SelectControl
                                help={ __( 'An example dropdown field.', 'wholesome-plugin') }
                                label={ __( 'Example Select', 'wholesome-plugin') }
                                onChange={ (exampleSelect) => {
                                    this.setState( { exampleSelect } );
                                    customize.value('wholesomecode_wholesome_plugin_example_select')(exampleSelect);
                                }}
                                options={ [
                                    {
                                        label: __( 'Please Select...', 'wholesome-plugin' ),
                                        value: '',
                                    },
                                    {
                                        label: __( 'Option 1', 'wholesome-plugin' ),
                                        value: 'option-1',
                                    },
                                    {
                                        label: __( 'Option 2', 'wholesome-plugin' ),
                                        value: 'option-2',
                                    },
                                ] }
                                value={ exampleSelect }
                            />
                        </PanelBody>
                        <PanelBody
                            title={ __( 'Panel Body Two', 'wholesome-plugin') }
                            icon="admin-plugins"
                        >
                            <TextControl
                                help={ __( 'This is an example text field.', 'wholesome-plugin') }
                                label={ __( 'Example Text', 'wholesome-plugin') }
                                onChange={ (exampleText) => {
                                    this.setState( { exampleText } );
                                    customize.value('wholesomecode_wholesome_plugin_example_text')(exampleText);
                                }}
                                value={ exampleText }
                            />

                        </PanelBody>
                        <PanelBody
                            title={ __( 'Panel Body Three', 'wholesome-plugin') }
                            icon="admin-plugins"
                        >
                            <TextControl
                                help={ __( 'Use PanelRow to place controls inline.', 'wholesome-plugin') }
                                label={ __( 'Example Text 2', 'wholesome-plugin') }
                                onChange={ (exampleText2) => {
                                    this.setState( { exampleText2 } );
                                    customize.value('wholesomecode_wholesome_plugin_example_text_2')(exampleText2);
                                }}
                                value={ exampleText2 }
                            />
                        </PanelBody>
                        <PanelBody
                            title={ __( 'Panel Body Four', 'wholesome-plugin') }
                            icon="admin-plugins"
                        >
                            <ToggleControl
                                checked={ exampleToggle }
                                help={ __( 'An example toggle.', 'wholesome-plugin') }
                                label={ __( 'Example Toggle', 'wholesome-plugin') }
                                onChange={ (exampleToggle) => {
                                    this.setState( { exampleToggle } );
                                    customize.value('wholesomecode_wholesome_plugin_example_toggle')(exampleToggle);
                                }}
                            />
                        </PanelBody>
                    </Panel>
                </div>
            </Fragment>) }
}

Un cambio notable es el interior componentDidMount, donde la configuración se carga desde la API. Tenga en cuenta que se accede a las dos configuraciones a las que se accederá get_theme_modmediante la variable WholesomePluginSettingsque creamos en la wp_localize_scriptfunción anteriormente en esta guía.

this.setState( {
  exampleSelect: WholesomePluginSettings[ 'wholesomecode_wholesome_plugin_example_select' ],
  exampleText: WholesomePluginSettings[ 'wholesomecode_wholesome_plugin_example_text' ],
  exampleText2: response[ 'wholesomecode_wholesome_plugin_example_text_2' ],
  exampleText3: response[ 'wholesomecode_wholesome_plugin_example_text_3' ],
  exampleToggle: Boolean( response[ 'wholesomecode_wholesome_plugin_example_toggle' ] ),
  isAPILoaded: true,
} );

Manejar el guardado

Realmente no necesitamos hacer nada especial para manejar los cambios. Lo único que tenemos que hacer es engancharnos customizey dejar que el Personalizador de WordPress maneje el guardado, por ejemplo:

onChange={ (exampleSelect) => {
  this.setState( { exampleSelect } );
  customize.value('wholesomecode_wholesome_plugin_example_select')(exampleSelect);
}}

En este ejemplo onChange, pasa el valor del campo de entrada (en este caso, nuestro <select>) y actualiza el estado, y luego pasa este valor al Personalizador a través de la wp.customize.value()función.

Cree la sección y el panel del personalizador con JavaScript

En la parte inferior del /src/customizer.jsarchivo, agregue el siguiente código:

customize.bind('ready', function() {
    const panelKey = 'wholesomecode-wholesome-plugin-customizer-panel';
    const sectionKey = 'wholesomecode-wholesome-plugin-customizer-section';

    customize.panel.add(
        new customize.Panel( panelKey, {
              description: __( 'Wholesome Plugin Example Panel', 'wholesome-plugin' ),
            priority: 1000,
            title: __( 'Wholesome Plugin Panel', 'wholesome-plugin' ),
        })
    );
    customize.section.add(
        new customize.Section( sectionKey, {
            customizeAction: __( 'Wholesome Plugin ▸ Section', 'wholesome-plugin' ),
            panel: panelKey,
             title: __( 'Wholesome Plugin Section', 'wholesome-plugin' ),
        })
    );

    customize.control.add(
        new customize.Control( 'wholesomecode-wholesome-plugin-customizer-gutenberg-control', {
            section: sectionKey,
            type: 'wholesome-plugin-gutenberg-control',
        })
    );

    const htmlOutput = document.getElementById( 'wholesome-plugin-customizer' );
    if (htmlOutput) {
        render(
            <App />,
            htmlOutput
        );
    }
});

Este código crea la sección del Personalizador y el Panel en JavaScript.

El código también agrega nuestro control Gutenberg personalizado al registrar una new customize.Controlclase y pasar el typecon el mismo nombre typeque establecimos cuando registramos el control en PHP.

También usamos este código para encontrar el <div>que registramos en nuestro control personalizado de Gutenberg y convertir los componentes de Gutenberg en este archivo <div>.

Agregar el SCSS

Necesitamos ordenar un poco el panel agregando el siguiente SCSS en /src/customizer.scss:

#wholesome-plugin-customizer {

    .components-placeholder {
        background: #f1f1f1;
    }

    .wholesome-plugin__main {
        margin-left: auto;
        margin-right: auto;

        .components-panel {
            background: none;
            border: none;
        }

        .components-panel__body {
            background: #ffffff;
            border: 1px solid #e2e4e7;
            margin-bottom: 1rem;
        }
    }

    .components-base-control__help {
        margin-top: .5rem;
    }

    .components-panel__row {
        > div {
            flex-grow: 1;
            margin-right: 1rem;

            &:last-of-type {
                margin-right: 0;
            }
        }
    }

    .wholesome-plugin__notices {
        .components-snackbar {
            bottom: .5rem;
            position: fixed;
        }
    }
}

Ver el Personalizador

Navegue hasta el personalizador de WordPress y vea el panel del personalizador de Gutenberg en acción:

El personalizador con componentes de Gutenberg

• Eche un vistazo a la creación de bloques secundarios anidados con el InnerBlockscomponente
• Eche un vistazo al uso de metacampos de publicación en bloques de Gutenberg