Полное руководство по настройке WordPress API, часть 8: валидация, очистка и элементы ввода

Содержание цикла статей "Полное руководство по настройке WordPress API":

  1. Полное руководство по настройке WordPress API, часть 1: введение
  2. Полное руководство по настройке WordPress API, часть 2: секции, поля и настройки
  3. Полное руководство по настройке WordPress API, часть 3: все о создании меню
  4. Полное руководство по настройке WordPress API, часть 4: опции темы
  5. Полное руководство по настройке WordPress API, часть 5: закладочная навигация
  6. Полное руководство по настройке WordPress API, часть 6: страницы меню
  7. Полное руководство по настройке WordPress API, часть 7: валидация, очистка и элементы ввода
  8. Полное руководство по настройке WordPress API, часть 8: валидация, очистка и элементы ввода
Содержание

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

В данной статье, мы узнаем о трех оставшихся элементах ввода и о том, как вывести их в нашей теме.

Примечание: статья предполагает, что вы уже знакомы с Settings API и опциями темы. Рекомендуется сначала ознакомиться с предыдущими статьями цикла.

Полное руководство по настройке WordPress API, часть 7: валидация, очистка и элементы ввода

Типы элементов, продолжение

Чекбокс (Checkbox)

В предыдущих статьях, мы уже добавляли чекбоксы. Мы можем к ним вернуться и изменить.

Сначала, давайте создадим чекбокс для функции sandbox_theme_initialize_input_examples:

add_settings_field(  
    'Checkbox Element',  
    'Checkbox Element',  
    'sandbox_checkbox_element_callback',  
    'sandbox_theme_input_examples',  
    'input_examples_section'  
);

Затем, добавьте следующую функцию в свой проект:

function sandbox_checkbox_element_callback() {  
  
    $options = get_option( 'sandbox_theme_input_examples' );  
      
    $html = '<input type="checkbox" id="checkbox_example" name="sandbox_theme_input_examples[checkbox_example]" />';  
    $html .= '<label for="checkbox_example">Это пример чекбокса</label>';  
      
    echo $html;  
  
} // Конец функции sandbox_checkbox_element_callback

В данном отрывке кода мы добавили тег <label>, чтобы можно было для переключения чекбокса кликать на весь элемент с меткой, а не прицеливаться курсором на квадратик с флажком.

Чтобы связать метку с чекбоксом, нужно передать в тег <label> атрибут id со значением идентификатора чекбокса, к которому привязана метка.

Теперь, обновите вашу страницу опций и увидите там новый элемент. Но пока невозможно сохранить его или прочитать из базы данных. Создадим атрибут value для чекбокса. Задав для него значение 1, мы установим флаг чекбокса:

$html = '<input type="checkbox" id="checkbox_example" name="sandbox_theme_input_examples[checkbox_example]" value="1" />';

Далее, подумаем, как происходит сохранение значений:

  • Пользователь устанавливает флаг и сохраняет заданное значение;
  • После обновления страницы, сохраненное значение флага должно остаться;
  • Пользователь снимает флаг и сохраняет заданное значение;
  • После обновления страницы, сохраненное значение флага должно остаться.

Все относительно просто, верно? Воспользуемся преимуществами функции WordPress checked для чтения, проверки и установки значений. Данная функция принимает три аргумента, но обязательным является только первый:

  1. Первое значение является одним из сравниваемых;
  2. Второе значение сравнивается, если первое не истинно;
  3. Выводить/ не выводить значение checked в браузер.
Полное руководство по настройке WordPress API, часть 1: введение

Давайте обновим наш код, добавив эту функцию:

$html = '<input type="checkbox" id="checkbox_example" name="sandbox_theme_input_examples[checkbox_example]" value="1"' . checked( 1, $options['checkbox_example'], false ) . '/>';

Обновите страницу, проверьте и установите/сбросьте флаг, затем сохраните и повторите.

Если что-то вам не понятно, обратитесь к предыдущим статьям, где мы рассмотрели значение каждого атрибута.

Наконец, давайте обновим страницу нашей темы, чтобы выполнить проверку этой опции и вывести строку текста, основанную на состоянии чекбокса. Вспомните, когда мы создавали элемент, то атрибуту value присвоили значение «1».

Это значит, что когда флаг чекбокс установлен и сохранен, то сохраненным значением будет единица. Нам нужно написать условную конструкцию, которая будет проверять значение опции, и выводить соответствующий текст. В файл index.php, добавьте следующий блок кода:

<?php if( $input_examples['checkbox_example'] == '1' ) { ?>  
    <p>Флаг чекбокса установлен .</p>  
<?php } else { ?>  
    <p>Флаг чекбокса не установлен.</p>  
<?php } // Конец конструкции if ?>

Теперь, вернитесь на страницу настроек, и попробуйте переключить чекбокс, сохранить значение и обновить страницу.

Как было замечено выше, стоит вернуться к странице «Опции отображения», которую мы создавали ранее в данной серии статей, и взглянуть там на реализацию элементов ввода, потому как на данном этапе все будет гораздо более понятно.

Радиокнопки (Radio Buttons)

Радиокнопки это элементы, которые обычно объединяются в группы. Радиокнопки предоставляют пользователям возможность выбрать один из взаимоисключающих вариантов.

По какой-то причине, создание радиокнопок часто вызывает трудности у разработчиков, работающих с WordPress. Надеюсь, что смогу объяснить настолько просто, насколько это возможно, как создать радиокнопки в нашем проекте. Определим план наших дальнейших действий:

  • Сначала создадим две опции, из которых пользователь может выбрать одну. Мы дадим им метки;
  • Первая опция будет радиоэлементом, с меткой «Опция 1» и будет иметь значение 1;
  • Вторая опция будет радиоэлементом, с меткой «Опция 2» и будет иметь значение 2.

Выглядит очень просто. Давайте добавим поле к нашей странице опций:

add_settings_field(  
    'Элемент радиокнопка',  
    'Элемент радиокнопка',  
    'sandbox_radio_element_callback',  
    'sandbox_theme_input_examples',  
    'input_examples_section'  
);

Также, реализуем callback-функцию для этого радиоэлемента. Сначала напишем код, а затем его разберем:

function sandbox_radio_element_callback() {  
  
    $options = get_option( 'sandbox_theme_input_examples' );  
      
    $html = '<input type="radio" id="radio_example_one" name="sandbox_theme_input_examples[radio_example]" value="1"' . checked( 1, $options['radio_example'], false ) . '/>';  
    $html .= '<label for="radio_example_one">Опция 1</label>';  
      
    $html .= '<input type="radio" id="radio_example_two" name="sandbox_theme_input_examples[radio_example]" value="2"' . checked( 2, $options['radio_example'], false ) . '/>';  
    $html .= '<label for="radio_example_two">Опция 2</label>';  
      
    echo $html;  
  
} // Конец функции sandbox_radio_element_callback
Полное руководство по настройке WordPress API, часть 3: все о создании меню

Первое, что бросается в глаза при работе с радиокнопками это то, что они ведут себя не так, как остальные элементы при задании атрибутов id и name. Заметим, что атрибут id уникален и не должен совпадать с другими значениями элемента.

Также, каждая метка для элемента ввода использует атрибут id для определения принадлежности. Это привязывает метку к радиокнопке, поэтому пользователи могут кликать по метке для изменения состояния элемента.

Атрибут name одинаков для каждой радиокнопки, однако значения атрибута value отличаются. Все это делает радиокнопки особенными – каждый радиоэлемент требует, чтобы значение атрибута name было одинаково, а атрибута value - уникально.

Наконец, мы можем приступить к написанию условной конструкции, для страницы нашей темы, которая бы устанавливала значение элемента. В файл functions.php вашей темы, добавьте следующий блок кода:

<?php if( $input_examples['radio_example'] == 1 ) { ?>  
    <p>Была выбрана первая опция.</p>  
<?php } elseif( $input_examples['radio_example'] == 2 ) { ?>  
    <p>Была выбрана вторая опция.</p>  
<?php } // Конец конструкции if  ?>

Взгляните на страницу вашей темы, попробуйте переключить опции и обновить страницу.

Выпадающий список (Select Box)

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

  • Определим элемент. В нашем примере, будет три значения;
  • Значениями будут «Никогда», «Иногда» и «Всегда»;
  • Установим опцию по умолчанию, которая будет показываться при загрузке страницы.

А далее, начнем типичные рутинные действия, которые нам уже очень хорошо знакомы. Определим поле:

add_settings_field(  
    'Элемент выпадающего списка',  
    'Элемент выпадающего списка',  
    'sandbox_select_element_callback',  
    'sandbox_theme_input_examples',  
    'input_examples_section'  
);

Определим callback-функцию. Ознакомьтесь с кодом, а затем мы обсудим пример:

function sandbox_select_element_callback() {  
  
    $options = get_option( 'sandbox_theme_input_examples' );  
      
    $html = '<select id="time_options" name="sandbox_theme_input_examples[time_options]">';  
        $html .= '<option value="default">Выберите вариант...</option>';  
        $html .= '<option value="never"' . selected( $options['time_options'], 'never', false) . '>Никогда</option>';  
        $html .= '<option value="sometimes"' . selected( $options['time_options'], 'sometimes', false) . '>Иногда</option>';  
        $html .= '<option value="always"' . selected( $options['time_options'], 'always', false) . '>Всегда</option>';  
    $html .= '</select>';  
      
    echo $html;  
  
} // Конец функции sandbox_radio_element_callback

Обновите страницу опций и убедитесь, что выбранное значение сохраняется. Скорее всего, все работает, поэтому давайте разберем код, представленный выше.

При создании выпадающего списка, мы передаем атрибутыid и name так же, как мы делали это в предыдущих примерах. Далее, каждой опции присваивается уникальное значение атрибута value и текстовой метки. Хотя этого делать не обязательно, я считаю полезным делать это в своих проектах.

Наконец, мы будем использовать функцию selected, которую предоставляет WordPress. Она очень похожа на функцию checked , которую мы использовали в предыдущих примерах, за исключением того, что она заточена под опции выпадающего списка.

Последним шагом, мы обновим главную страницу нашего сайта так, чтобы устанавливалось значение выбранной опции после сохранения. Добавьте следующий блок кода в файл index.php:

<?php if( $input_examples['time_options'] == 'never' ) { ?>  
    <p>Никогда не отображать это.</p>  
<?php } elseif( $input_examples['time_options'] == 'sometimes' ) { ?>  
    <p>Иногда отображать это.</p>  
<?php } elseif( $input_examples['time_options'] == 'always' ) { ?>  
    <p>Всегда отображать это.</p>  
<?php } // Конец конструкции if/else ?>

Вновь посетите главную страницу вашего сайта, измените опцию, а затем обновите страницу – убедитесь, что ваш выбор сохраняется.

Заключение

Наконец-то мы закончили данную серию статей. Settings API это мощное средство WordPress , которое дает нам возможность создавать хорошие и безопасные страницы настроек, но требует правильного обращения. К сожалению, это, наверное, одна из самых игнорируемых многими разработчиками платформ.

Моей главной целью было провести читателей через дебри API от самых элементарных вещей до самых сложных и показать, как все это работает изнутри. Надеюсь, у меня это получилось.

РедакцияПеревод статьи «The Complete Guide To The WordPress Settings API, Part 8: Validation, Sanitisation, and Input II»