Створіть панель налаштування за допомогою компонентів WordPress Block Editor (Gutenberg).

У нашому останньому посібнику ми розглядали створення сторінки налаштувань за допомогою компонентів WordPress Block Editor (Gutenberg). У цьому посібнику ми збираємося підійти далі й використати компоненти Gutenberg у налаштувачі WordPress.

Настроювач із компонентами Gutenberg

передумови

• Дотримуйтесь посібника «Створення плагіна для редактора блоків WordPress» (Gutenberg).
• Дотримуйтесь посібника «Використання параметрів для зберігання даних у редакторі блоків WordPress» (Gutenberg).
• Дотримуйтесь інструкцій із додавання точок входу до посібника зі створення сценарію блоку WordPress
• Слідкуйте за посібником із створення сторінки налаштувань за допомогою редактора блоків WordPress (Gutenberg) .

Створіть точку входу в webpack

Дотримуючись посібника «Додати точки входу» до посібника «Створити сценарій блоку WordPress », створіть нову точку входу в розширеному webpack.config.jsфайлі, створеному в цьому посібнику.

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' ),
    }
};

Створіть два нових файли у своєму рішенні:

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

Ми використаємо їх для створення плагіна.

Зареєструйте налаштування та компоненти настроювача в PHP

Дотримуючись посібників у попередніх вимогах, відкрийте кореневий файл PHP плагіна (у цьому випадку wholesome-plugin.php) і додайте наступне:

Зареєструйте елемент керування настроювачем

Нам потрібно створити настроюваний елемент керування. Додайте наступний код до свого файлу, який відтворить виклик, що виводить a <div>з ідентифікатором, який може підключити наш JavaScript.

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 );

У нижній частині цього файлу ми реєструємо елемент керування за допомогою, register_control_typeякий дозволяє отримати доступ до цього елемента керування в JavaScript.

Зареєструйте налаштування настроювача

У цьому ж блоці коду нам потрібно прописати налаштування, які ми збираємося використовувати в кастомайзері. Для цього додайте наступний блок коду після рядка, який виконує 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' ] );

Зверніть увагу, що перші два параметри будуть доступні через get_theme_modфункцію за замовчуванням, тоді як два нижні параметри передаються в аргументи 'type' => 'option', що означає, що ці параметри будуть зареєстровані як унікальні поля в таблиці параметрів і будуть доступні через get_option.

Для цих двох нижніх налаштувань нам потрібно переконатися, що вони зареєстровані через register_settingі show_in_restдля trueкожного з них, щоб до них можна було отримати доступ через Gutenberg.

Зареєструйте параметри «Параметри».

Зареєструйте два нижні налаштування настроювача (до яких ми матимемо доступ через get_option) за допомогою такого блоку коду:

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 );

Поставте сценарії в чергу

Нарешті, зареєструйте активи настроювача за допомогою наступного коду (додаткову інформацію див. у посібнику з додавання точок входу ).

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 );

Зауважте, що ми також використовуємо wp_localize_scriptв цьому блоці коду для передачі параметрів, до яких ми матимемо доступ через get_theme_modJavaScript.

Давайте розглянемо цю частину коду більш детально:

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', '' ),
  ]
);

Зауважте, що ми використовуємо ті самі ключі налаштувань, які ми зареєстрували, коли реєстрували налаштування настроювача $wp_customize->add_settingраніше (ті, які не були налаштовані на використання параметра).

Створіть панель налаштування в JavaScript

Додайте наступний код у /src/customizer.jsфайл.

Здебільшого цей код (Appкомпонент) є переробленим кодом із посібника «Створити сторінку налаштувань». Він використовує ті самі компоненти та все ще встановлює stateз API налаштувань, але не використовує кнопку збереження та область повідомлень.

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>) }
}

Одна помітна зміна полягає в тому, що всередині componentDidMount, де налаштування завантажуються з API. Зауважте, що доступ до двох налаштувань, до яких буде доступно через get_theme_mod, можна отримати за допомогою змінної WholesomePluginSettings, яку ми створили у wp_localize_scriptфункції раніше в цьому посібнику.

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,
} );

Обробка збереження

Нам насправді не потрібно робити нічого особливого, щоб впоратися зі змінами. Єдине, що нам потрібно зробити, це підключитися до customizeWordPress Customizer і дозволити йому зберегти, наприклад:

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

У цьому прикладі onChangeпередає значення поля введення (у цьому випадку наше <select>) і оновлює стан, а потім передає це значення в настроювач через wp.customize.value()функцію.

Створіть розділ і панель настроювача за допомогою JavaScript

У нижній частині /src/customizer.jsфайлу додайте такий код:

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
        );
    }
});

Цей код створює розділ і панель настроювача в JavaScript.

Код також додає наш власний елемент керування Gutenberg, реєструючи new customize.Controlклас і передаючи typeз тим же ім’ям, яке typeми встановили під час реєстрації елемента керування в PHP.

Ми також використовуємо цей код, щоб знайти <div>зареєстровані нами елементи керування Gutenberg і відобразити в цьому компоненти Gutenberg <div>.

Додайте SCSS

Нам потрібно трохи впорядкувати панель, додавши наступний SCSS у /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;
        }
    }
}

Перегляд настроювача

Перейдіть до настроювача WordPress і перегляньте панель налаштувань Gutenberg у дії:

Настроювач із компонентами Gutenberg

• Подивіться на створення вкладених дочірніх блоків за допомогою InnerBlocksкомпонента
• Подивіться на використання пост мета-полів у блоках Гутенберга