WordPress. API настроек (опций). Часть 1 из 4

15.07.2019

Теги: API • CMS • Web-разработка • WordPress • Настройка

API опций было добавлено в версии 2.7 и позволяет создавать как сами настройки, так и поля форм для сохранения значений в базу данных. Можно добавлять как отдельные настройки, так и целые секции настроек. И размещать элементы формы как на уже существующих страницах (Общие, Чтение, Медиафайлы), так и создавать под настройки новые страницы в админке.

Функции для работы с опциями

  • Функция add_option() добавляет настройку (название и значение опции) в базу данных. Ничего не делает, если опция уже существует. Можно записать массив — перед записью в БД он будет сериализован.
  • Функция update_option() обновляет значение опции (настройки) в базе данных. Ожидает не экранированную строку. Может быть использована для того, чтобы добавлять новые опции, вместо add_options().
  • Функция get_option() получает значение указанной настройки (опции). Функция получает данные из кэша, если это возможно, если нет, то данные берутся из базы данных. Возвращает значение опции или false, если указанной опции не существует.
  • Функция delete_option() удаляет настройку (запись из таблицы wp_options базы данных). Возвращает true — если настройка была найдена и удалена и false — в противном случае.

Примеры использования функций: 

// создаем новую опцию
add_option('some_option', 'some_value');
// обновляем значение опции
update_option('some_option', 'other_value');
// получаем значение опции
get_option('some_option', 'default value');
// удаляем созданную опцию
delete_option('some_option');

Добавляем поле опции

Для добавления поля формы на страницу опций предназначена функция add_settings_field(). WordPress сам позаботится о сохранении опции в базу данных после отправки данных формы. Добавляемая опция должна быть сначала зарегистрирована функцией register_setting(), иначе она не будет сохраняться и обновляться. 

add_action('admin_init', function () {
    /*
     * Регистрируем новую опцию, указываем страницу меню
     */
    register_setting(
        /*
         * Страница меню «Настройки», куда будет добавлена опция:
         * general, reading, discussion, media, permalink
         */
        'general',
        /*
         * Название новой опции
         */
        'some_option'
    );
    /*
     * Добавляем поле формы для редактирования значения опции
     */
    add_settings_field(
        'some_option', // идентификатор поля формы
        'Заголовок поля', // заголовок поля формы
        function () { // выводит html-код поля формы
            ?>
            <input
                type="text"
                id="some_option"
                name="some_option"
                value="<?= esc_attr(get_option('some_option')); ?>"
            />
            <?php
        },
        'general' // страница меню «Настройки»
    );
});

Функции обратного вызова может быть передан в качестве аргумента массив. В этом случае массив должен быть описан при вызове add_settings_field(): 

add_action('admin_init', function () {
    /*
     * Регистрируем новую опцию, указываем страницу меню
     */
    register_setting(
        /*
         * Страница меню «Настройки», куда будет добавлена опция:
         * general, reading, discussion, media, permalink
         */
        'general',
        /*
         * Название новой опции
         */
        'some_option'
    );
    /*
     * Добавляем поле формы для редактирования значения опции
     */
    add_settings_field(
        'some_option', // идентификатор поля формы
        'Заголовок поля', // заголовок поля формы
        function ($args) { // выводит html-код поля формы
            $id = $args['option_id'];
            $name = $args['option_name'];
            $value = $args['option_value'];
            ?>
            <input
                type="text"
                id="<?= $id; ?>"
                name="<?= $name; ?>"
                value="<?= esc_attr($value); ?>"
            />
            <?php
        },
        'general', // страница меню «Настройки»
        'default', // секция настроек
        /*
         * Этот массив будет передан функции обратного вызова
         */
        [
            'option_id' => 'some_option',
            'option_name' => 'some_option',
            'option_value' => get_option('some_option', '')
        ]
    );
});

Создаем секцию настроек

Функция add_settings_section() позволяет создать новый блок (секцию), в котором выводятся поля настроек. Т.е. в этот блок затем добавляются опции с помощью add_settings_field(). Такие секции можно увидеть на страницах настроек WordPress или плагинов.

При создании плагина можно просто создать новую секцию на уже существующей странице настроек WordPress, вместо того, чтобы создавать отдельную страницу настроек. Это немного упростит создание плагина, и избавит от лишнего пункта в панели управления.

Давайте создадим три настройки и объединим их в секцию. Секцию разместим на странице «Настройки • Общие» и зададим для нее заголовок и описание. 

add_action('admin_init', function () {

    /*
     * Регистрируем три опции, указываем страницу меню
     */
    register_setting(
        'general',
        'some_option'
    );
    register_setting(
        'general',
        'other_option'
    );
    register_setting(
        'general',
        'another_option'
    );

    /*
     * Регистрируем новую секцию для трех настроек с заголовком
     */
    add_settings_section(
        'some_section', // идентификатор секции
        'Секция из трех настроек', // заголовок секции
        function () { // выводит описание секции
            ?>
            <p>
            Lorem ipsum dolor sit amet, consectetur adipisicing elit. Accusamus
            architecto beatae commodi consequatur cum deleniti ea expedita impedit
            ipsum molestias pariatur perferendis qui similique, veritatis, vitae.
            </p>
            <?php
        },
        'general'
    );

    /*
     * Добавляем поле формы для первой опции
     */
    add_settings_field(
        'some_option', // идентификатор поля формы
        'Заголовок первой опции', // заголовок поля формы
        function () { // выводит html-код поля формы
            ?>
            <input
                type="text"
                id="some_option"
                name="some_option"
                value="<?= esc_attr(get_option('some_option')); ?>"
            />
            <?php
        },
        'general', // страница меню «Настройки»
        'some_section' // идентификатор секции
    );
    /*
     * Добавляем поле формы для второй опции
     */
    add_settings_field(
        'other_option', // идентификатор поля формы
        'Заголовок второй опции', // заголовок поля формы
        function () { // выводит html-код поля формы
            ?>
            <input
                type="text"
                id="other_option"
                name="other_option"
                value="<?= esc_attr(get_option('other_option')); ?>"
            />
            <?php
        },
        'general', // страница меню «Настройки»
        'some_section' // идентификатор секции
    );
    /*
     * Добавляем поле формы для третьей опции
     */
    add_settings_field(
        'another_option', // идентификатор поля формы
        'Заголовок третьей опции', // заголовок поля формы
        function () { // выводит html-код поля формы
            ?>
            <input
                type="text"
                id="another_option"
                name="another_option"
                value="<?= esc_attr(get_option('another_option')); ?>"
            />
            <?php
        },
        'general', // страница меню «Настройки»
        'some_section' // идентификатор секции
    );
});

Посмотрим, как можно сохранить массив в таблице wp_options базы данных. Создадим одну настройку и три поля, которые пользователь может заполнить. И сохраним все три значения в одной опции. 

add_action('admin_init', function () {

    /*
     * Регистрируем новую опцию, которая содержит три значения
     */
    register_setting(
        'general',
        'multiple_option'
    );

    /*
     * Регистрируем новую секцию для этой опции из трех значений
     */
    add_settings_section(
        'multiple_section', // идентификатор секции
        'Секция для опции из трех значений', // заголовок секции
        function () { // выводит описание секции
            ?>
            <p>
            Lorem ipsum dolor sit amet, consectetur adipisicing elit. Accusamus
            architecto beatae commodi consequatur cum deleniti ea expedita impedit
            ipsum molestias pariatur perferendis qui similique, veritatis, vitae.
            </p>
            <?php
        },
        'general'
    );

    /*
     * Добавляем поле формы для первого значения опции
     */
    add_settings_field(
        'multiple_option_some', // идентификатор поля формы
        'Заголовок для первого значения', // заголовок поля формы
        function () { // выводит html-код поля формы
            $value = '';
            $option = get_option('multiple_option');
            if (isset($option['some'])) {
                $value = $option['some'];
            }
            ?>
            <input
                type="text"
                id="multiple_option_some"
                name="multiple_option[some]"
                value="<?= esc_attr($value); ?>"
            />
            <?php
        },
        'general', // страница меню «Настройки»
        'multiple_section' // идентификатор секции
    );
    /*
     * Добавляем поле формы для второго значения опции
     */
    add_settings_field(
        'multiple_option_other', // идентификатор поля формы
        'Заголовок для второго значения', // заголовок поля формы
        function () { // выводит html-код поля формы
            $value = '';
            $option = get_option('multiple_option');
            if (isset($option['other'])) {
                $value = $option['other'];
            }
            ?>
            <input
                type="text"
                id="multiple_option_other"
                name="multiple_option[other]"
                value="<?= esc_attr($value); ?>"
            />
            <?php
        },
        'general', // страница меню «Настройки»
        'multiple_section' // идентификатор секции
    );
    /*
     * Добавляем поле формы для третьего значения опции
     */
    add_settings_field(
        'multiple_option_another', // идентификатор поля формы
        'Заголовок для третьего значения', // заголовок поля формы
        function () { // выводит html-код поля формы
            $value = '';
            $option = get_option('multiple_option');
            if (isset($option['another'])) {
                $value = $option['another'];
            }
            ?>
            <input
                type="text"
                id="multiple_option_another"
                name="multiple_option[another]"
                value="<?= esc_attr($value); ?>"
            />
            <?php
        },
        'general', // страница меню «Настройки»
        'multiple_section' // идентификатор секции
    );
});

Поиск: API • Web-разработка • WordPress • Настройка • Опция • Option • Setting • add_option • update_option • get_option • delete_option • register_setting • add_settings_field • add_settings_section

Каталог оборудования
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Производители
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Функциональные группы
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.