Nella nostra ultima guida abbiamo esaminato la creazione di una pagina delle impostazioni utilizzando i componenti di WordPress Block Editor (Gutenberg). In questa guida andremo ancora oltre e utilizzeremo i componenti Gutenberg all’interno del Customizer di WordPress.
Il Customizer con i componenti Gutenberg
Prerequisiti
- Ho seguito la guida Creazione di un plug-in per l’editor di blocchi di WordPress (Gutenberg).
- Ho seguito la guida Utilizzo delle opzioni per archiviare i dati nella guida di WordPress Block Editor (Gutenberg).
- Ho seguito la guida Aggiungi punti di ingresso alla guida Crea script di blocco di WordPress
- Ho seguito la guida ai componenti Crea una pagina delle impostazioni utilizzando WordPress Block Editor (Gutenberg).
Crea un punto di ingresso nel webpack
Seguendo la guida Aggiungi punti di ingresso alla guida Crea script di blocco di WordPress, crea un nuovo punto di ingresso nel webpack.config.jsfile esteso che hai creato in quella guida.
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' ),
}
};
Crea due nuovi file nella tua assolo:
/src/customizer.js/src/customizer.scss
Li useremo per creare il nostro plugin.
Registra le impostazioni e i componenti della personalizzazione in PHP
Seguendo le guide nei prerequisiti, apri il file PHP di root del plugin (in questo caso wholesome-plugin.php) e aggiungi quanto segue:
Registra il controllo della personalizzazione
Abbiamo bisogno di creare un controllo Customizer personalizzato. Aggiungi il codice seguente al tuo file che visualizzerà una chiamata che restituisce a <div>con un ID a cui il nostro JavaScript può agganciarsi.
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 );
In fondo a questo file registriamo il controllo con il register_control_typequale ci consente di accedere a questo controllo in JavaScript.
Registra le impostazioni della personalizzazione
Nello stesso blocco di codice dobbiamo registrare le impostazioni che utilizzeremo nel personalizzatore. Per farlo, aggiungi il seguente blocco di codice dopo la riga che esegue il file 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' ] );
Si noti che le prime due impostazioni saranno accessibili tramite la get_theme_modfunzione predefinita, mentre le due ultime impostazioni passano negli argomenti, il 'type' => 'option'che significa che queste impostazioni verranno registrate come campi univoci all’interno della tabella delle opzioni e saranno accessibili tramite get_option.
Per queste due impostazioni inferiori dobbiamo assicurarci che siano registrate tramite register_settinge show_in_restper trueciascuna, in modo che sia possibile accedervi tramite Gutenberg.
Registra le impostazioni ‘Opzioni’
Registra le ultime due impostazioni di personalizzazione (a cui accederemo tramite get_option) con il seguente blocco di codice:
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 );
Accoda gli script
Infine, registra gli asset di personalizzazione con il codice seguente (consulta la guida Aggiungi punti di ingresso per maggiori informazioni).
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 );
Nota che usiamo anche wp_localize_scriptin questo blocco di codice per passare le impostazioni a cui accederemo get_theme_modin JavaScript.
Diamo un’occhiata a questa parte del codice in modo più dettagliato:
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', '' ),
]
);
Si noti che stiamo utilizzando le stesse chiavi di impostazione che abbiamo registrato quando abbiamo registrato le impostazioni di personalizzazione con in $wp_customize->add_settingprecedenza (quelle che non erano state configurate per utilizzare un’opzione).
Costruisci il pannello di personalizzazione in JavaScript
Aggiungi il codice seguente nel /src/customizer.jsfile.
Per la maggior parte, questo codice (il Appcomponente) è una rielaborazione del codice della guida Crea pagina delle impostazioni. Utilizza gli stessi componenti e imposta ancora l’ stateAPI delle impostazioni, ma elimina il pulsante di salvataggio e l’area degli avvisi.
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 cambiamento notevole è quello inside componentDidMount, dove le impostazioni vengono caricate dall’API. Si noti che si accede alle due impostazioni tramite cui get_theme_modsi accede utilizzando la variabile WholesomePluginSettingsche abbiamo creato nella wp_localize_scriptfunzione in precedenza in questa guida.
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,
} );
Gestisci il salvataggio
Non abbiamo davvero bisogno di fare nulla di speciale per gestire i cambiamenti. L’unica cosa che dobbiamo fare è agganciarci customizee lasciare che il Customizer di WordPress gestisca il salvataggio, ad esempio:
onChange={ (exampleSelect) => {
this.setState( { exampleSelect } );
customize.value('wholesomecode_wholesome_plugin_example_select')(exampleSelect);
}}
In questo esempio onChangepassa il valore del campo di input (in questo caso il nostro <select>) e aggiorna lo stato, quindi passa questo valore al Customizer tramite la wp.customize.value()funzione.
Costruisci la sezione Customizer e il pannello con JavaScript
In fondo al /src/customizer.jsfile aggiungi il seguente codice:
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
);
}
});
Questo codice crea la sezione Customizer e il pannello in JavaScript.
Il codice aggiunge anche il nostro controllo Gutenberg personalizzato registrando una new customize.Controlclasse e passando typecon lo stesso nome che typeabbiamo impostato quando abbiamo registrato il controllo in PHP.
Usiamo questo codice anche per trovare quello <div>che abbiamo registrato nel nostro controllo Gutenberg personalizzato e renderizzare i componenti Gutenberg in questo <div>.
Aggiungi l’SCSS
Abbiamo bisogno di riordinare un po’ il pannello aggiungendo il seguente SCSS in /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;
}
}
}
Visualizzazione del Customizer
Passa al Customizer di WordPress e visualizza il pannello di personalizzazione di Gutenberg in azione:
Il Customizer con i componenti Gutenberg
- Dai un’occhiata alla creazione di blocchi figlio nidificati con il
InnerBlockscomponente - Dai un’occhiata all’utilizzo dei meta-campi post nei blocchi di Gutenberg