Créer un panneau de personnalisation à l’aide des composants WordPress Block Editor (Gutenberg)
Dans notre dernier guide, nous avons examiné la création d’une page de paramètres à l’aide des composants WordPress Block Editor (Gutenberg). Dans ce guide, nous allons aller encore plus loin et utiliser les composants Gutenberg dans WordPress Customizer.
Le personnalisateur avec les composants Gutenberg
Conditions préalables
- Avoir suivi le guide Création d’un plugin pour l’éditeur de blocs WordPress (Gutenberg)
- Avoir suivi le guide Utilisation des options pour stocker des données dans l’éditeur de blocs WordPress (Gutenberg)
- Avoir suivi le guide Ajouter des points d’entrée au guide WordPress Créer un script de bloc
- Avoir suivi le guide des composants Créer une page de paramètres à l’aide de WordPress Block Editor (Gutenberg)
Créer un point d’entrée dans le webpack
Suite au guide Ajouter des points d’entrée au guide WordPress Créer un script de bloc, créez un nouveau point d’entrée dans le fichier étendu webpack.config.jsque vous avez créé dans ce guide.
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' ),
}
};
Créez deux nouveaux fichiers dans votre solution :
/src/customizer.js/src/customizer.scss
Nous les utiliserons pour créer notre plugin.
Enregistrez les paramètres et les composants du personnalisateur en PHP
Suite aux guides des prérequis, ouvrez le fichier PHP racine du plugin (dans ce cas wholesome-plugin.php) et ajoutez ce qui suit :
Enregistrez le contrôle de personnalisation
Nous devons créer un contrôle Customizer personnalisé. Ajoutez le code suivant à votre fichier qui rendra un appel qui sortira le a <div>avec un ID auquel notre JavaScript peut se connecter.
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 bas de ce fichier nous enregistrons le contrôle avec register_control_typequi nous permet d’accéder à ce contrôle en JavaScript.
Enregistrer les paramètres de personnalisation
Dans le même bloc de code, nous devons enregistrer les paramètres que nous allons utiliser dans le personnalisateur. Pour ce faire, ajoutez le bloc de code suivant après la ligne qui fait le 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' ] );
Notez que les deux premiers paramètres seront accessibles via la get_theme_modfonction par défaut, tandis que les deux derniers paramètres passent dans les arguments 'type' => 'option', ce qui signifie que ces paramètres seront enregistrés en tant que champs uniques dans la table des options et seront accessibles via get_option.
Pour ces deux paramètres inférieurs, nous devons nous assurer qu’ils sont enregistrés via register_settinget show_in_restpour truechacun d’eux, afin qu’ils soient accessibles via Gutenberg.
Enregistrez les paramètres ‘Option’
Enregistrez les deux derniers paramètres de personnalisation (auxquels nous accéderons via get_option) avec le bloc de code suivant :
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 );
Mettre les scripts en file d’attente
Enfin, enregistrez les actifs du personnalisateur avec le code suivant (voir le guide Ajouter des points d’entrée pour plus d’informations).
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 );
Notez que nous utilisons également wp_localize_scriptdans ce bloc de code pour transmettre les paramètres auxquels nous accéderons via get_theme_moden JavaScript.
Voyons plus en détail cette partie du code :
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', '' ),
]
);
Notez que nous utilisons les mêmes clés de réglage que nous avons enregistrées lorsque nous avons enregistré les paramètres de personnalisation avec $wp_customize->add_settingplus tôt (ceux qui n’ont pas été configurés pour utiliser une option).
Construire le panneau de personnalisation en JavaScript
Ajoutez le code suivant dans le /src/customizer.jsfichier.
Pour l’essentiel, ce code (le Appcomposant) est une refonte du code du guide Créer une page de paramètres. Il utilise les mêmes composants et définit toujours stateles paramètres de l’API, mais supprime le bouton de sauvegarde et la zone des avis.
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 changement notable est celui à l’intérieur componentDidMountde, où les paramètres sont chargés à partir de l’API. Notez que les deux paramètres accessibles via get_theme_modsont accessibles à l’aide de la variable WholesomePluginSettingsque nous avons créée dans la wp_localize_scriptfonction plus haut dans ce guide.
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,
} );
Gérer la sauvegarde
Nous n’avons pas vraiment besoin de faire quoi que ce soit de spécial pour gérer les changements. La seule chose que nous devons faire est de nous connecter customizeet de laisser le WordPress Customizer gérer la sauvegarde, par exemple :
onChange={ (exampleSelect) => {
this.setState( { exampleSelect } );
customize.value('wholesomecode_wholesome_plugin_example_select')(exampleSelect);
}}
Dans cet exemple, le onChangepasse la valeur du champ de saisie (dans ce cas, notre <select>) et met à jour l’état, puis passe cette valeur dans le Customizer via la wp.customize.value()fonction.
Construire la section et le panneau de personnalisation avec JavaScript
En bas du /src/customizer.jsfichier ajoutez le code suivant :
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
);
}
});
Ce code crée une section et un panneau de personnalisation en JavaScript.
Le code ajoute également notre contrôle Gutenberg personnalisé en enregistrant une new customize.Controlclasse et en transmettant le typeavec le même nom que celui que typenous avons défini lorsque nous avons enregistré le contrôle en PHP.
Nous utilisons également ce code pour trouver le <div>we enregistré dans notre contrôle Gutenberg personnalisé et restituer les composants Gutenberg dans this <div>.
Ajouter le SCSS
Nous devons ranger un peu le panneau en ajoutant le SCSS suivant dans/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;
}
}
}
Affichage du personnalisateur
Accédez à WordPress Customizer et affichez le panneau Gutenberg Customizer en action :
Le personnalisateur avec les composants Gutenberg
- Découvrez comment créer des blocs enfants imbriqués avec le
InnerBlockscomposant - Jetez un œil à l’utilisation des champs post-méta dans les blocs Gutenberg