Розробка кастомних полів (Custom Fields) через ACF для WordPress

Розробка користувацьких полів через ACF для WordPress

Advanced Custom Fields (ACF) — де факто стандарт для додавання структурованих даних до записів WordPress. Редактори отримують нормальні поля вводу замість вільного текстового мета-поля custom-fields. ACF PRO додає Repeater, Flexible Content, Gallery і clone — без нього складні структури даних практично нереалізуємі стандартними засобами. Настройка полів під задачу займає від кількох годин до 2 днів залежно від кількості груп і логіки умовного відображення.

Реєстрація груп полів через код

ACF дозволяє реєструвати групи полів програмно (а не через /wp-admin) — це обов'язково для production: конфігурація зберігається в коді, а не в БД:

add_action('acf/init', function () {
    acf_add_local_field_group([
        'key'      => 'group_project_details',
        'title'    => 'Деталі проекту',
        'fields'   => [
            [
                'key'           => 'field_project_client',
                'label'         => 'Клієнт',
                'name'          => 'project_client',
                'type'          => 'text',
                'required'      => 1,
                'placeholder'   => 'Назва компанії',
            ],
            [
                'key'           => 'field_project_year',
                'label'         => 'Рік реалізації',
                'name'          => 'project_year',
                'type'          => 'number',
                'min'           => 2000,
                'max'           => 2030,
                'default_value' => date('Y'),
            ],
            [
                'key'           => 'field_project_url',
                'label'         => 'URL проекту',
                'name'          => 'project_url',
                'type'          => 'url',
            ],
            [
                'key'           => 'field_project_tech_stack',
                'label'         => 'Технології',
                'name'          => 'project_tech_stack',
                'type'          => 'checkbox',
                'choices'       => [
                    'react'      => 'React',
                    'vue'        => 'Vue.js',
                    'laravel'    => 'Laravel',
                    'wordpress'  => 'WordPress',
                    'nextjs'     => 'Next.js',
                ],
                'layout'        => 'horizontal',
            ],
            [
                'key'           => 'field_project_gallery',
                'label'         => 'Галерея скриншотів',
                'name'          => 'project_gallery',
                'type'          => 'gallery',
                'min'           => 0,
                'max'           => 20,
                'mime_types'    => 'jpg,jpeg,png,webp',
                'return_format' => 'array',
            ],
        ],
        'location' => [
            [['param' => 'post_type', 'operator' => '==', 'value' => 'project']],
        ],
        'menu_order'     => 0,
        'position'       => 'normal',
        'style'          => 'seamless',
        'label_placement' => 'top',
    ]);
});

Repeater — повторювальні блоки даних

[
    'key'     => 'field_project_results',
    'label'   => 'Результати проекту',
    'name'    => 'project_results',
    'type'    => 'repeater',
    'min'     => 1,
    'max'     => 10,
    'layout'  => 'table',
    'button_label' => 'Додати результат',
    'sub_fields' => [
        [
            'key'   => 'field_result_metric',
            'label' => 'Метрика',
            'name'  => 'metric',
            'type'  => 'text',
            'placeholder' => 'Конверсія',
        ],
        [
            'key'   => 'field_result_before',
            'label' => 'До',
            'name'  => 'before',
            'type'  => 'text',
            'placeholder' => '1.2%',
        ],
        [
            'key'   => 'field_result_after',
            'label' => 'Після',
            'name'  => 'after',
            'type'  => 'text',
            'placeholder' => '3.8%',
        ],
    ],
],

Вивід Repeater на фронтенді:

if (have_rows('project_results')) {
    echo '<table class="results-table">';
    echo '<thead><tr><th>Метрика</th><th>До</th><th>Після</th></tr></thead><tbody>';
    while (have_rows('project_results')) {
        the_row();
        printf(
            '<tr><td>%s</td><td>%s</td><td>%s</td></tr>',
            esc_html(get_sub_field('metric')),
            esc_html(get_sub_field('before')),
            esc_html(get_sub_field('after'))
        );
    }
    echo '</tbody></table>';
}

Flexible Content — конструктор сторінок

Flexible Content дозволяє редакторам збирати сторінку з блоків різних типів — по суті внутрішній page builder:

[
    'key'     => 'field_page_sections',
    'label'   => 'Секції сторінки',
    'name'    => 'page_sections',
    'type'    => 'flexible_content',
    'button_label' => 'Додати секцію',
    'layouts' => [
        'hero' => [
            'key'        => 'layout_hero',
            'name'       => 'hero',
            'label'      => 'Hero-баннер',
            'sub_fields' => [
                ['key' => 'field_hero_title',  'label' => 'Заголовок', 'name' => 'title',  'type' => 'text'],
                ['key' => 'field_hero_bg',     'label' => 'Фон',       'name' => 'bg',     'type' => 'image', 'return_format' => 'array'],
                ['key' => 'field_hero_button', 'label' => 'Кнопка',    'name' => 'button', 'type' => 'link'],
            ],
        ],
        'text_columns' => [
            'key'        => 'layout_text_columns',
            'name'       => 'text_columns',
            'label'      => 'Текст у колонках',
            'sub_fields' => [
                ['key' => 'field_tc_cols', 'label' => 'Колонки', 'name' => 'columns', 'type' => 'repeater',
                 'sub_fields' => [
                    ['key' => 'field_tc_text', 'name' => 'text', 'label' => 'Текст', 'type' => 'wysiwyg'],
                 ]],
            ],
        ],
    ],
],

Рендер:

if (have_rows('page_sections')) {
    while (have_rows('page_sections')) {
        the_row();
        $layout = get_row_layout();
        get_template_part("template-parts/sections/{$layout}");
    }
}

Умовне відображення полів

ACF підтримує conditional_logic — показувати поле лише при певному значенні іншого:

[
    'key'               => 'field_show_cta',
    'label'             => 'Показати CTA',
    'name'              => 'show_cta',
    'type'              => 'true_false',
    'ui'                => 1,
],
[
    'key'               => 'field_cta_text',
    'label'             => 'Текст кнопки',
    'name'              => 'cta_text',
    'type'              => 'text',
    'conditional_logic' => [
        [['field' => 'field_show_cta', 'operator' => '==', 'value' => '1']],
    ],
],

Синхронізація через JSON

ACF PRO підтримує синхронізацію груп через файли /acf-json/*.json. При змінені структури через інтерфейс — файл оновлюється автоматично. Коммітимо файли в git, на іншому оточенні натискаємо "Sync" або вызиваємо acf_sync_field_groups().

Отримання полів поза циклом

// Поле конкретного запису
$client = get_field('project_client', $post_id);

// Поле опції (option page ACF)
$phone = get_field('company_phone', 'option');

// Поле терміну таксономії
$color = get_field('category_color', 'project_category_' . $term_id);

ACF — інструмент для швидкого старту. При розростанні проекту складні Flexible Content з десятками layout стають вузьким місцем: запити до wp_postmeta з JOIN-ами по 100+ рядків замовляють сторінки. На цьому етапі варто розглядати користувацькі таблиці або перехід на headless архітектуру.