Зміст циклу статей «Повне керівництво по налаштуванню WordPress API»:

  • Повне керівництво по налаштуванню WordPress API, частина 1: вступ
  • Повне керівництво по налаштуванню WordPress API, частина 2: секції, поля та налаштування
  • Повне керівництво по налаштуванню WordPress API, частина 3: все про створення меню
  • Повне керівництво по налаштуванню WordPress API, частина 4: опції теми
  • Повне керівництво по налаштуванню WordPress API, частина 5: навігація закладочная
  • Повне керівництво по налаштуванню WordPress API, частина 6: сторінки меню
  • Повне керівництво по налаштуванню WordPress API, частина 7: валідація, очищення та елементи вводу
  • Повне керівництво по налаштуванню WordPress API, частина 8: валідація, очищення та елементи вводу
  • У минулій статті ми заглибилися у вивчення різних типів меню, які підтримує WordPress API. Хоча матеріал, розглянутий у попередній статті, і не є частиною Settings API, але дуже важливий у розробці, особливо при роботі над складними плагінами і темами.

    У цій статті розглядається практичне використання меню, так як тепер ми починаємо серйозно працювати над нашою темою Sandbox шляхом оптимізації існуючих установок і додавання декількох нових сторінок.

    Якщо ви тільки що приєдналися до нас, то, будь ласка, ознайомтеся з попередніми статтями і переконайтеся, що у вас встановлена остання версія теми Sandbox доступною в репозитарії на GitHub.

    У цій статті дуже багато коду. У її першій половині, ми будемо вдосконалювати існуючий код. А в другій половині – писати новий функціонал з нуля.

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

    «Прибирання» коду

    Якщо ви працювали з попередніми прикладами, то у вас у файлі functions.php є безліч функцій для створення різних пунктів меню. Так як в цій статті у нас більш практичний підхід, то частина існуючого коду, створеного в попередніх статтях циклу, потрібно видалити.

    Я знаю, вам здається недоцільним писати стільки коду тільки для того, щоб його потім видалити, але попередні приклади служили базою для розуміння основ написання коду для WordPress.

    Для початку нам потрібно знайти дві функції з попередніх статей, створювали підпункт меню «Додатки»:

    /**
    * Додавання одиночного підпункту в пункт меню «Плагіни»
    */
    function sandbox_example_plugin_menu() {
    add_plugins_page(
    ‘Плагін Sandbox’, // Текст, що відображається в заголовку вікна браузера.
    ‘Плагін Sandbox’, // Текст, що відображається у пункті меню
    ‘administrator’, // Група користувачів, що мають доступ до даного пункту меню
    ‘sandbox_plugin_options’, // Унікальний ID — псевдонім – для даного пункту
    ‘sandbox_plugin_display’ // Ім’я callback-функції
    );
    } // Кінець функції sandbox_example_plugin_menu
    add_action(‘admin_menu’, ‘sandbox_example_plugin_menu’);
    /**
    * Відображення простий сторінки налаштувань.
    */
    function sandbox_plugin_display() {
    // Створюємо заголовок в стандартному контейнері «wrap»
    $html =’
    ‘;
    $html .= ‘

    Опції плагіна Sandbox

    ‘;
    $html .= ‘

    Поки тут немає опцій. Це просто демонстрація.

    ‘;
    $html .= ‘
    ‘;
    // Посилаємо html-розмітку браузеру
    echo $html;
    } // Кінець функції sandbox_plugin_display

    Видаліть цей код з файлу functions.php.

    Далі, нам потрібно видалити функції, відповідальні за додавання меню верхнього рівня. Ми перепишемо цей шматок коду пізніше, але він сильно відрізнятиметься від початкового варіанта.

    /**
    * Додаємо нове меню верхнього рівня в нижню частину адміністративного меню WordPress.
    */
    function sandbox_create_menu_page() {
    add_menu_page(
    ‘Опції Sandbox’, // який Відображається в браузері заголовок для даного меню
    ‘Sandbox’, // Текст пункту меню
    ‘administrator’, // Користувачі, які можуть бачити цей пункт меню
    ‘sandbox’, // Унікальний ідентифікатор даного пункту меню
    ‘sandbox_menu_page_display’ // Ім’я функції, що викликається при відображенні меню
    );
    add_submenu_page(
    ‘sandbox’, // Реєстрація підпункту під певним вище пунктом меню
    ‘Опції Sandbox’, // Текст заголовка браузера при активованому пункті меню
    ‘Опції’, // Текст для цього підпункту
    ‘administrator’, // Група користувачів, яким доступний цей підпункт
    ‘sandbox_options’, // Унікальний ID — псевдонім – для цього підпункту меню
    ‘sandbox_options_display’ // Функція, яка використовується для виведення вмісту цього пункту меню
    );
    } // Кінець функції sandbox_create_menu_page
    add_action(‘admin_menu’, ‘sandbox_create_menu_page’);
    function sandbox_menu_page_display() {
    // Створення тега заголовка в стандартному контейнері «wrap»
    $html =’
    ‘;
    $html .= ‘

    Sandbox

    ‘;
    $html .= ‘
    ‘;
    // Посилаємо розмітку на висновок в браузер
    echo $html;
    } // Кінець функції sandbox_menu_page_display
    function sandbox_options_display() {
    // Створюємо заголовок в стандартному контейнері «wrap»
    $html =’
    ‘;
    $html .= ‘

    Опції Sandbox

    ‘;
    $html .= ‘
    ‘;
    // Посилаємо створену розмітку браузеру
    echo $html;
    } // кінець функції sandbox_options_display

    На даний момент, в адміністративній панелі WordPress, щодо оригіналу, є наступні модифікації:

    Підпункт «Тема Sandbox» знаходиться в меню «вигляд» (Appearance);
    Набір трьох опцій для управління видимістю контейнерів розташовується на вкладці «Загальні налаштування» (General) в меню «Налаштування» (Settings).

    Якщо у вас є перераховані модифікації, то можете сміливо рухатися далі. В іншому випадку, перевірте ваш файл functions.php і звірте його з кодом нижче:

    function sandbox_example_theme_menu() {
    add_theme_page(
    ‘Тема Sandbox’, // Текст в заголовку браузера
    ‘Тема Sandbox’, // Текст самого пункту меню в бічному меню WordPress
    ‘administrator’, // Групи користувачів, які мають доступ до даного меню
    ‘sandbox_theme_options’, // Унікальний ID — псевдонім – для даного пункту меню
    ‘sandbox_theme_display’ // Ім’я функції, що використовується для виводу пункту меню на екран
    );
    } // Кінець функції sandbox_example_theme_menu
    add_action(‘admin_menu’, ‘sandbox_example_theme_menu’);
    function sandbox_theme_display() {
    // Створимо тег заголовка в контейнері «wrap» у WordPress
    $html =’
    ‘;
    $html .= ‘

    Опції теми Sandbox

    ‘;
    $html .= ‘

    Поки тут немає опцій. Це просто демонстрація.

    ‘;
    $html .= ‘
    ‘;
    // Посилаємо розмітку браузеру
    echo $html;
    } // Кінець функції sandbox_theme_display
    /* —————————————————————-
    * Реєстрація налаштувань
    * —————————————————————-
    */
    /* Ініціалізація сторінки опцій теми, реєстрація секцій, полів і налаштувань.
    * Ця функція реєструється з допомогою хука admin_init.
    */
    function sandbox_initialize_theme_options() {
    //Спочатку ми реєструємо секцію. Це необхідно, оскільки декларовані далі опції будуть належати саме до цієї секції.
    add_settings_section(
    ‘general_settings_section’, // ID, що буде використовуватись для ідентифікації цієї секції і за яким ми будемо реєструвати опції
    ‘Опції Sandbox’, // Заголовок, який буде відображатися на сторінці адміністративної панелі
    ‘sandbox_general_options_callback’, // Виклик, який використовується для відображення опису секції
    ‘general’ // Сторінка, на яку буде додана секція
    );
    // Далі, ми створимо поле для перемикання видимості контейнерів в шаблоні
    add_settings_field(
    ‘show_header’, // Ідентифікатор, використовуваний для ідентифікації поля всередині теми
    ‘Контейнер header’, // Мітка ліворуч від елемента інтерфейсу
    ‘sandbox_toggle_header_callback’, // Ім’я функції, відповідальної за виведення елемента інтерфейсу
    ‘general’, // Сторінка, на яку буде виведена опція
    ‘general_settings_section’, // Ім’я секції, якій належить полі
    array( // Масив-аргументів, що передається callback-функції. В нашому випадку просто опис.
    ‘Ввімкніть цю опцію, щоб відобразити контейнер header.’
    )
    );
    add_settings_field(
    ‘show_content’,
    ‘Контейнер content’,
    ‘sandbox_toggle_content_callback’,
    ‘general’,
    ‘general_settings_section’,
    array(
    ‘Ввімкніть цю опцію, щоб відобразити контейнер content.’
    )
    );
    add_settings_field(
    ‘show_footer’,
    ‘Контейнер Footer’,
    ‘sandbox_toggle_footer_callback’,
    ‘general’,
    ‘general_settings_section’,
    array(
    ‘Ввімкніть цю опцію, щоб відобразити контейнер footer.’
    )
    );
    // Реєструємо поля у WordPress
    register_setting(
    ‘general’,
    ‘show_header’
    );
    register_setting(
    ‘general’,
    ‘show_content’
    );
    register_setting(
    ‘general’,
    ‘show_footer’
    );
    } // Кінець функції sandbox_initialize_theme_options
    add_action(‘admin_init’, ‘sandbox_initialize_theme_options’);
    /* —————————————————————-
    * Callback-функції для секцій
    * —————————————————————-
    */
    /*
    * Ця функція надає простий опис сторінки «Загальні налаштування».
    * Вона викликається з функції «sandbox_initialize_theme_options» та передається до неї як параметр
    */
    function sandbox_general_options_callback() {
    echo ‘

    Виберіть, які секції ви хочете показувати на сторінці.

    ‘;
    } // Кінець функції sandbox_general_options_callback
    /* ———————————————————————— *
    * Callback-функції для полів
    * ————————————————————————
    */
    /*
    * Ця функція виводить елемент інтерфейсу для зміни видимості контейнера header.
    * Вона отримує масив аргументів, в якому першим йде опис, яке буде відображено після чекбокса.
    */
    function sandbox_toggle_header_callback($args) {
    //Ідентифікатор і ім’я атрибута елемента повинні збігатися із зазначеними у функції add_settings_field
    $html = «;
    // Беремо перший елемент масиву і додаємо його до мітки чекбокса
    $html .= » . $args[0] . «;
    echo $html;
    } // Кінець функції sandbox_toggle_header_callback
    function sandbox_toggle_content_callback($args) {
    $html = «;
    $html .= » . $args[0] . «;
    echo $html;
    } // Кінець функції sandbox_toggle_content_callback
    function sandbox_toggle_footer_callback($args) {
    $html = «;
    $html .= » . $args[0] . «;
    echo $html;
    } // Кінець функції sandbox_toggle_footer_callback

    А тепер, пора почати по-справжньому!

    Ескізи наших майбутніх опцій

    До написання коду, нам слід спланувати наші дії. На даний момент у нас вже написана базова функціональність – ми дали користувачам можливість перемикати видимість контейнерів header, content і footer. Група цих опцій знаходиться на вкладці «Загальні» (General) на сторінці «Налаштування» (Settings).

    Однак, трьох цих опцій недостатньо для повноцінної теми. В наші дні практично всі користуються соціальними мережами в своїх блогах, так що давайте дамо можливість користувачам показувати посилання на їх акаунти в Twitter, Facebook і Google+.

    Для себе, у розумі, ми можемо скласти вигляд сторінки з настройками з двох секцій:

  • Відображення:
    • Контейнер Header;
    • Контейнер Content;
    • Контейнер Footer;
  • Соціальні мережі:
    • Twitter;
    • Facebook;
    • Google+
  • На наступному кроці, ми створимо ці опції на сторінці налаштувань нашої теми Sandbox, до якої можна отримати доступ з меню «вигляд» (Appearance). На додаток до всього іншого, кожна секція буде доступна на окремій вкладці навігаційної панелі.

    Створення опцій

    Переробка сторінки опцій

    Наша сторінка налаштувань стане більш функціональною за час проходження даного циклу статей, тому корисно буде підготуватися. Зараз наша callback-функція виглядає так:

    function sandbox_theme_display() {
    // Створимо тег заголовка в контейнері «wrap» у WordPress
    $html =’
    ‘;
    $html .= ‘

    Опції теми Sandbox

    ‘;
    $html .= ‘

    Поки тут немає опцій. Це просто демонстрація.

    ‘;
    $html .= ‘
    ‘;
    // Посилаємо розмітку браузеру
    echo $html;
    } // Кінець функції sandbox_theme_display

    Ось список удосконалень, які нам треба зробити:

    • Вказати іконку для сторінки опцій, щоб вона виглядала більш органічно і вписувалися в загальний вигляд WordPress;
    • Видалити опис сторінки;
    • Переробити PHP-рядки з HTML-кодом в блоки, щоб з ними було простіше працювати;
    • Написати функцію для відображення помилок;
    • Створити форму, яка буде використана для розміщення наших опцій.

    Перераховане реалізувати не так вже й складно. В даному випадку, прокомментированным кодом буде простіше показати, який сенс дій, ніж описувати це текстом.

    Вивчіть лістинг, розташований нижче, приділяючи особливу увагу коментарям, а потім додайте змінену callbackфункцію у ваш проект:

    function sandbox_theme_display() {
    ?>

    Опції теми Sandbox

    Якщо ви зробили помилку в коді, то ваша сторінка налаштувань повинна виглядати наступним чином:

    Переміщення налаштувань

    Тепер, коли сторінка набула задуманий нами вид, саме час перемістити налаштування на сторінку опцій теми. У минулій статті ми додали кожну опцію окремо на вкладку «Загальні» (General) і вони були згруповані під міткою «Опції Sandbox».

    Тепер, щоб перемістити їх на сторінку налаштувань нашої теми, потрібно зробити кілька модифікацій. Ми детально розглянемо кожен крок, щоб розуміти, що відбувається.

    Крок 1. Перевірка опцій на існування

    Після того, як ми стали додавати наші опції у створені групи, а не існуючі, виникла необхідність перевірки існування полів у базі даних.

    Щоб це зробити, ми викличемо функцію get_option. Якщо вона повертає значення false, то додаємо наш новий набір опцій з допомогою функції add_option.

    Для цього, додамо наступний блок коду початок функції sandbox_initialize_theme_options:

    if( false == get_option( ‘sandbox_theme_display_options’ ) ) {
    add_option( ‘sandbox_theme_display_options’ );
    } // Кінець конструкції if

    Крок 2. Перебудова секцій

    Знайдіть виклик функції add_settings_section, а в ній — аргумент title. Зараз ця функція виглядає так:

    add_settings_section(
    ‘general_settings_section’, // ID, що буде використовуватись для ідентифікації цієї секції і за яким ми будемо реєструвати опції
    ‘Опції Sandbox’, // Заголовок, який буде відображатися на сторінці адміністративної панелі
    ‘sandbox_general_options_callback’, // Виклик, який використовується для відображення опису секції
    ‘general’ // Сторінка, на яку буде додана секція
    );

    Так як наші опції тепер знаходяться на сторінці «Опції Sandbox», нам потрібно змінити назву секції. Замість цього тексту, давайте введемо «Опції відображення».

    add_settings_section(
    ‘general_settings_section’, // ID, що буде використовуватись для ідентифікації цієї секції і за яким ми будемо реєструвати опції
    ‘Опції відображення’, // Заголовок, який буде відображатися на сторінці адміністративної панелі
    ‘sandbox_general_options_callback’, // Виклик, який використовується для відображення опису секції
    ‘general’ // Сторінка, на яку буде додана секція
    );

    Нам більше не потрібно відображати опції на сторінці «Загальні налаштування» (General Settings), тому змінимо останній аргумент у функції вище id сторінки налаштувань нашої теми. Я вибрав ім’я sandbox_theme_display_options:

    add_settings_section(
    ‘general_settings_section’, // ID, що буде використовуватись для ідентифікації цієї секції і за яким ми будемо реєструвати опції
    ‘Опції відображення’, // Заголовок, який буде відображатися на сторінці адміністративної панелі
    ‘sandbox_general_options_callback’, // Виклик, який використовується для відображення опису секції
    ‘sandbox_theme_display_options’ // Сторінка, на яку буде додана секція
    );

    Крок 3. Оновлення полів

    Після завдання унікального ідентифікатора для сторінки, потрібно переконатися, що параметри мають правильні посилання на сторінки. Зараз, всі наші виклики функцій add_settings_field посилаються на сторінку «Загальні налаштування» (General Settings):

    add_settings_field(
    ‘show_header’, // Ідентифікатор, використовуваний для ідентифікації поля всередині теми
    ‘Контейнер header’, // Мітка ліворуч від елемента інтерфейсу
    ‘sandbox_toggle_header_callback’, // Ім’я функції, відповідальної за виведення елемента інтерфейсу
    ‘general’, // Сторінка, на яку буде виведена опція
    ‘general_settings_section’, // Ім’я секції, якій належить полі
    array( // Масив-аргументів, що передається callback-функції. В нашому випадку просто опис.
    ‘Ввімкніть цю опцію, щоб відобразити контейнер header.’
    )
    );

    Нам потрібно змінити четвертий аргумент, що відповідає за сторінку для виведення поля. Потрібно прописати в ньому ім’я нашої сторінки опцій теми, замість імені сторінки загальних параметрів.

    Це робиться простим зміною рядка на значення sandbox_theme_display_options. Тепер, три підкориговані опції повинні виглядати так:

    add_settings_field(
    ‘show_header’, // Ідентифікатор, використовуваний для ідентифікації поля всередині теми
    ‘Контейнер header’, // Мітка ліворуч від елемента інтерфейсу
    ‘sandbox_toggle_header_callback’, // Ім’я функції, відповідальної за виведення елемента інтерфейсу
    ‘sandbox_theme_display_options’, // Сторінка, на яку буде виведена опція
    ‘general_settings_section’, // Ім’я секції, якій належить полі
    array( // Масив-аргументів, що передається callback-функції. В нашому випадку просто опис.
    ‘Ввімкніть цю опцію, щоб відобразити контейнер header.’
    )
    );
    add_settings_field(
    ‘show_content’,
    ‘Контейнер content’,
    ‘sandbox_toggle_content_callback’,
    ‘sandbox_theme_display_options’,
    ‘general_settings_section’,
    array(
    ‘Ввімкніть цю опцію, щоб відобразити контейнер content.’
    )
    );
    add_settings_field(
    ‘show_footer’,
    ‘Контейнер Footer’,
    ‘sandbox_toggle_footer_callback’,
    ‘sandbox_theme_display_options’,
    ‘general_settings_section’,
    array(
    ‘Ввімкніть цю опцію, щоб відобразити контейнер footer.’
    )
    );

    Крок 4. Реєстрація нових налаштувань

    До цього моменту, ми реєстрували кожну опцію окремо, на сторінці загальних налаштувань, наступним чином:

    register_setting(
    ‘general’,
    ‘show_header’
    );
    register_setting(
    ‘general’,
    ‘show_content’
    );
    register_setting(
    ‘general’,
    ‘show_footer’
    );

    З створенням окремого меню теми Sandbox, ми можемо об’єднати три цих виклику в один, який зареєструє всі поля нашої нової секції опцій:

    register_setting(
    ‘sandbox_theme_display_options’,
    ‘sandbox_theme_display_options’
    );

    Звернувшись до другої статті ми згадаємо, що настройка це комбінація полів і секцій, яким вони належать. А так як всі наші поля тепер належать одній і тій же секції «Опції відображення», то ми можемо однією командою зареєструвати їх в WordPress.

    Крок 5. Оновлення елементів опцій

    Раніше наші опції зберігалися як окремі налаштування в базі даних. Це означає, що ми могли знайти їх по унікальному ID (наприклад, «get_option(‘show_header’)«).

    Але так як тепер у нас своя власна секція, вони є частиною набору опцій. Щоб прочитати опції, ми повинні спочатку отримати доступ до набору, а потім знайти в ньому цікавлячу нас поле.

    Зараз нам потрібно оновити всі елементи вводу. Знайдіть секцію callback-функцій у файлі functions.php. Функція для першої опції, перемикає видимість контейнера header, на даний момент повинна виглядати так:

    function sandbox_toggle_header_callback($args) {
    //Ідентифікатор і ім’я атрибута елемента повинні збігатися із зазначеними у функції add_settings_field
    $html = «;
    // Беремо перший елемент масиву і додаємо його до мітки чекбокса
    $html .= » . $args[0] . «;
    echo $html;
    } // Кінець функції sandbox_toggle_header_callback

    Як було відмічено вище, кожна опція є частиною набору опцій, тому нам необхідно змінити метод доступу до них. Ми повинні:

    • Прочитати набір опцій;
    • Отримати доступ до окремої опції з набору;
    • Оновити атрибути елемента вводу, щоб посилання вірно посилалися на елементи з набору.

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

    function sandbox_toggle_header_callback($args) {
    // Зчитуємо опції з групи
    $options = get_option(‘sandbox_theme_display_options’);
    // Оновлюємо імена атрибутів для доступу до ID елементів в контексті масиву відображуваних опцій
    // Отримуємо доступ до елемента show_header з групи опцій, викликаючи допоміжну функцію checked()
    $html = «;
    // Беремо перший елемент масиву і додаємо його вміст мітки чекбокса
    $html .= » . $args[0] . «;
    echo $html;
    } // Кінець функції sandbox_toggle_header_callback

    Просто, чи не правда? Після того, як у нас є три опції, потрібно внести відповідні зміни в кожну з них. Всі функції будуть виглядати схоже, за винятком імен опцій. Замість show_header, буде show_content або show_footer.

    Отже, фінальна версія для реалізації всіх трьох опцій виглядає так:

    function sandbox_toggle_header_callback($args) {
    $options = get_option(‘sandbox_theme_display_options’);
    $html = «;
    $html .= » . $args[0] . «;
    echo $html;
    } // Кінець функції sandbox_toggle_header_callback
    function sandbox_toggle_content_callback($args) {
    $options = get_option(‘sandbox_theme_display_options’);
    $html = «;
    $html .= » . $args[0] . «;
    echo $html;
    } // Кінець функції sandbox_toggle_content_callback
    function sandbox_toggle_footer_callback($args) {
    $options = get_option(‘sandbox_theme_display_options’);
    $html = «;
    $html .= » . $args[0] . «;
    echo $html;
    } // Кінець функції sandbox_toggle_footer_callback

    Крок 6. Висновок опцій

    Нарешті, ми готові відобразити наші опції на сторінці нашої теми. Це робиться простим викликом двох функцій Settings API:

    • settings_fields відповідає за безпеку при роботі з опціями на формі;
    • do_settings_sections виводить опції на сторінку.

    Кожна функція приймає ID сторінки, на якій повинен бути зроблений висновок. В нашому випадку, це sandbox_theme_display_options. Щоб відобразити наші опції, оновимо вміст форми:

    Оновіть сторінку опцій вашої теми і побачите три опції, як показано на зображенні нижче:

    Повне керівництво по налаштуванню WordPress API, частина 4: опції теми

    Підсумкова версія файлу functions.php представлена нижче:

    Опції теми Sandbox

    Створення налаштувань соціальних мереж

    У попередньому розділі було багато коду, і ми майже повністю переробили наш початковий варіант проекту. Настав час пустити в хід Settings API на повну котушку!

    Недостатньо просто зробити окрему сторінку з налаштуваннями. Щоб створити повноцінну сторінку налаштувань з новими корисними опціями, ми створимо ще один набір налаштувань.

    За традицією, складемо план наших подальших дій:

    • Спочатку створимо нову секцію;
    • Потім, додамо в неї три поля налаштувань: одне для Facebook, одне для Twitter і одне для Google+;
    • Нарешті, оновимо сторінку наших опцій, щоб з’явилися нові налаштування.

    Створення секцій, полів і налаштувань

    Секція з налаштуваннями соціальних мереж

    Для початку, давайте створимо нову функцію і додамо її до хуку admin_init. Ця функція буде призначена спеціально для налаштування опцій соціальних мереж.

    За аналогією з налаштуваннями відображення, необхідно виконати перевірку, щоб переконатися, що опції створені. Якщо ні, то слід їх створити.

    Ось функція ініціалізації. Слідкуйте за коментарями!

    /*
    * Ініціалізація параметрів соціальних мереж — реєстрація секцій, полів і налаштувань.
    * Ця функція реєструється з допомогою хука ‘admin_init’.
    */
    function sandbox_theme_intialize_social_options() {
    // Якщо опції соціальних мереж не створені, то створюємо їх.
    if( false == get_option( ‘sandbox_theme_social_options’ ) ) {
    add_option( ‘sandbox_theme_social_options’ );
    } // Кінець конструкції if
    } // Кінець функції sandbox_theme_intialize_social_options
    add_action( ‘admin_init’, ‘sandbox_theme_intialize_social_options’ );

    Далі, нам потрібно додати нову секцію для налаштувань. Це робиться відразу після вищенаведеного коду:

    add_settings_section(
    ‘social_settings_section’, // ID, що буде використовуватись для ідентифікації цієї секції і за яким ми будемо реєструвати опції
    ‘Опції соціальних мереж’, // Заголовок, який буде відображатися на сторінці адміністративної панелі
    ‘sandbox_social_options_callback’, // Виклик, який використовується для відображення опису секції
    ‘sandbox_theme_social_options’ // Сторінка, на яку буде додана секція
    );

    Але це ще не все! У третьому аргументі функції add_settings_section передається ім’я callback-функція. Не забудьте її визначити:

    function sandbox_social_options_callback() {
    echo ‘

    Заповніть URL-адреси на соціальні мережі, які ви хочете відобразити.

    ‘;
    } // кінець функції sandbox_general_options_callback

    Зараз ми можемо зробити перевірку, щоб переконатися, що секція дійсно була зареєстрована Settings API. Поверніться до функції sandbox_theme_display і додайте наступні два рядки форми.

    Вони повинні розташовуватися відразу після функції sandbox_theme_display_options:

    Якщо ви все зробили правильно, то побачите те, що зображено нижче:

    Повне керівництво по налаштуванню WordPress API, частина 4: опції теми

    Поля налаштувань соціальних мереж

    Тепер, ми готові додати поля налаштувань соціальних мереж на нашу сторінку. Почнемо з поля для Twitter. Нижче наведено виклик функції add_settings_section:

    add_settings_field(
    ‘twitter’,
    ‘Twitter’,
    ‘sandbox_twitter_callback’,
    ‘sandbox_theme_social_options’,
    ‘social_settings_section’
    );

    Зауважте, ми визначили callbackфункцію, як sandbox_twitter_callback, тому нам також потрібно не забути її реалізувати. За аналогією з попередніми опціями, нам потрібно отримати доступ до набору налаштувань, створити HTML-елемент для візуалізації і правильно задати всі атрибути.

    Особливу увагу зверніть на умовну конструкцію у коді нижче – для ясності вона прокоментована. Умова потрібно для того, щоб переконатися, що ми не намагаємося читати порожні опції:

    function sandbox_twitter_callback() {
    // Спочатку, читаємо увесь набір налаштувань
    $options = get_option( ‘sandbox_theme_social_options’ );
    // Далі перевіряємо, визначений елемент у наборі. Якщо ні, то визначаємо його.
    $url = «;
    if( isset( $options[‘twitter’] ) ) {
    $url = $options[‘twitter’];
    } // Кінець конструкції if
    // Вивід на екран
    echo «;
    } // Кінець функції sandbox_twitter_callback

    Нарешті, повернемось до функції sandbox_theme_intialize_social_options і зареєструють нову налаштування WordPress:

    register_setting(
    ‘sandbox_theme_social_options’,
    ‘sandbox_theme_social_options’,
    ‘sandbox_theme_sanitize_social_options’
    );

    Важлива відмінність: до цього моменту, функції register_setting ми передавали два аргументи – групу опцій і опції. Але зараз, ми використовуємо третій аргумент: ім’я callback-функції.

    Ця функція викликається ДО збереження в базу даних, що дозволяє перевірити їх на відповідність. Інакше кажучи, ми можемо перевірити дані на їх безпеку і правильність, перед їх збереженням.

    Давайте створимо заготівлю функції:

    function sandbox_theme_sanitize_social_options( $input ) {
    } // Кінець функції sandbox_theme_sanitize_social_options

    Callback-функція приймає єдиний аргумент, який ми назвали $input. Це набір опцій, який був створений для секції налаштувань соціальних мереж.

    Так як ми дозволяємо користувачеві ввести будь-який текст в поле введення, необхідно запобігти запис будь-якого шкідливого коду (такого, як JavaScript або SQL) .

    Ось наш план дій для реалізації механізмів захисту:

    • Створення масиву, який ми зможемо записувати оброблені дані;
    • Перевірка кожної опції і очищення даних;
    • Повернення обробленого набору даних.

    Давайте напишемо код, що реалізує це. Вставте цей код у файл functions.php:

    /* ————————————————————————
    * Callback-функції для налаштувань
    * ————————————————————————
    */
    function sandbox_theme_sanitize_social_options( $input ) {
    // Оголошення масиву для оброблених опцій
    $output = array();
    // Перевірка кожної опції і очищення даних
    foreach( $input as $key => $val ) {
    if( isset ( $input[$key] ) ) {
    $output[$key] = esc_url_raw( strip_tags( stripslashes( $input[$key] ) ) );
    } // Кінець конструкції if
    } // Кінець конструкції foreach
    // Повернення обробленого набору
    return apply_filters( ‘sandbox_theme_sanitize_social_options’, $output, $input );
    } // Кінець функції sandbox_theme_sanitize_social_options

    Вище, ми використовували три функції, кожна з яких послужила для реалізації механізмів очищення даних:

    • stripslashes рідна функція PHP для видалення екрануючих символів з рядків;
    • strip_tags ще одна рідна функція PHP, яка видаляє HTML — та PHP-теги з рядків;
    • esc_url_raw функція WordPress, яка зберігає чистий URL-адресу без кодування.

    Наведений вище код дуже суворий по відношенню до вмісту, але якщо потрібно дозволити зберігати в базу даних виключно URL-адреси, то він дуже ефективний.

    Останній рядок повертає результат роботи функції apply_filters, а не сам масив. Це дієвий спосіб, щоб переконатися в тому, що інші функції, прикріплені до цього ж хуку, також будуть викликані.

    У нашій простий темі, звичайно, немає інших функцій, однак ця рада актуальна при розробці складних професійних тем.

    А зараз, збережіть ваш проект і оновіть вікно браузера. Ваша сторінка опцій тепер відображає не тільки секцію «Параметри відображення», але також і першу опцію соціальних мереж. Більш того, ви можете ввести URL-адресу свого профілю на Twitter і зберегти його в базі даних.

    Повне керівництво по налаштуванню WordPress API, частина 4: опції теми

    Створення залишилися опцій

    Вставка опцій для Facebook і Google+ вимагатиме виконання точно таких же кроків, як і для Twitter. Основні кроки:

    • Визначення поля для налаштування;
    • Виклик callback-функції.

    Про все інше піклується Settings API. Звичайно, нам потрібно доробити опції для решти двох соціальних мереж.

    Визначимо два поля налаштувань:

    add_settings_field(
    ‘facebook’,
    ‘Facebook’,
    ‘sandbox_facebook_callback’,
    ‘sandbox_theme_social_options’,
    ‘social_settings_section’
    );
    add_settings_field(
    ‘googleplus’,
    ‘Google+’,
    ‘sandbox_googleplus_callback’,
    ‘sandbox_theme_social_options’,
    ‘social_settings_section’
    );

    Далі, визначимо для них дві callback-функції:

    function sandbox_facebook_callback() {
    $options = get_option( ‘sandbox_theme_social_options’ );
    $url = «;
    if( isset( $options[‘facebook’] ) ) {
    $url = $options[‘facebook’];
    } // Кінець конструкції if
    // Вивід на екран
    echo «;
    } // Кінець функції sandbox_facebook_callback
    function sandbox_googleplus_callback() {
    $options = get_option( ‘sandbox_theme_social_options’ );
    $url = «;
    if( isset( $options[‘googleplus’] ) ) {
    $url = $options[‘googleplus’];
    } // Кінець конструкції if
    // Вивід на екран
    echo «;
    } // Кінець функції sandbox_googleplus_callback

    Збережіть вашу роботу і знову оновіть вашу сторінку опцій. Має з’явитися два додаткових поля – одне для Facebook і одне для Google+. Спробуйте їх у дії.

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

    Пізніше, в даному циклі статей, ми їх розглянемо, коли будемо детально займатися полями вводу. Там буде показаний найбільш безпечний спосіб очищення даних перед їх збереженням.

    Висновок полів

    Навіщо потрібні опції, якщо до них немає доступу з сайту? Перед тим, як закінчити цю статтю, давайте зробимо маленьку модифікацію у файлі index.php нашої теми. А точніше, нам потрібно перевірити включення наших опцій, і показати інформацію про зазначених соціальних мережах:

    Повноцінний гід по Settings API | Тема Sandbox

    Заголовок Sandbox



    © Всі права захищені.

    Висновок

    Це була сама, без сумніву, сама об’ємна стаття в даному циклі. Якщо ви з нею впоралися, то готуйтеся до щільної роботи з Settings API. У двох наступних статтях, ми займемося нашими навігаційними меню – закладної навігацією і меню верхнього рівня.

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

    Поки у вас є час, поекспериментуйте з тим, що у нас вийшло на даний момент!

    Переклад статті «The Complete Guide To The WordPress Settings API, Part 4: On Theme Options» був підготовлений дружною командою проекту Сайтостроение від А до Я.