ACF na trzy sposoby

Jedną z fundamentalnych zalet WordPressa, która doprowadziła ten CMS do sukcesu, jest jego plastyczność. Zarówno frontend, jak i backend można w nim łatwo rozbudowywać, elastycznie dostosowując do wymagań najbardziej wymagających projektów. W panelu administracyjnym WordPressa możemy dodać własne metapola, co pozwala np. rozszerzać edytor wpisów i stron, tworzyć własne typy treści z niestandardowymi polami (Custom Post Types), kontrolować widoczność interfejsu w zależności od ról użytkowników czy przechowywać dodatkowe informacje. Innymi słowy – możemy sprawić, by użytkownik WordPressa wprowadzał i prezentował dane dokładnie tak, jak zakłada to nasz projekt. Jednak, by móc robić to szybko, komfortowo i bezpiecznie, zdecydowana większość developerów sięga po wtyczkę ACF, czyli Advanced Custom Fields.

ACF – standard niestandardowych pól

Wśród pluginów służących do zarządzania własnymi polami, ACF od lat jest zdecydowanym liderem. Pozwala definiować rozmaite typy pól – tekstowe, liczbowe, pliki, obrazy, listy wyboru, listy powtarzalne (tzw. repeater), relacje, daty, galerię, elastyczne bloki i inne – i umieszczać je swobodnie w interfejsie WordPressa. To, wraz z opcją uzależniania widoczności od różnego rodzaju warunków, sprawia, że panel administracyjny przyjmuje taką postać, jakiej oczekuje użytkownik końcowy. Sama wtyczka jest darmowa w podstawowym zakresie, jednak za bardziej zaawansowane możliwości (jak dodawanie pól do stron opcji, listy powtarzalne, pola bloków) trzeba zapłacić – ale nawet wersja bezpłatna wystarcza do większości zastosowań. Konkurencja istnieje (np. Toolset), niemniej ACF dominuje na rynku głównie dzięki intuicyjności, wsparciu społeczności i niezawodności.

ACF w panelu – wyklikaj, co potrzebujesz

Zdecydowana większość użytkowników zaczyna przygodę z ACF od wizualnego edytora pól. Proces polega na utworzeniu nowej grupy pól z poziomu menu „Custom Fields” (lub „ACF”), nadaniu jej nazwy oraz określeniu warunków wyświetlania (np. przypisania do wybranego typu postu). Następnie klikamy „Add Field” i definiujemy pola: wybieramy ich typ, klucz, nazwę wyświetlaną, opis oraz inne parametry, takie jak domyślna wartość, walidacja czy instrukcje dla użytkownika. Na końcu zapisujemy grupę i pola pojawiają się w wybranym kontekście edytora WordPressa.

Istotna cecha ACF to łatwa migracja konfiguracji pól między środowiskami (np. dev-staging-prod). Po utworzeniu folderu acf-json w katalogu motywu lub wtyczki, ACF zapisuje tam każdą zmianę w grupach pól jako osobny plik JSON. To pozwala przenosić pole ustalone na jednym środowisku na inne (np. przez Gita w ramach CI/CD), bez żmudnego klikania. Wystarczy skopiować katalog acf-json – przy pierwszym odświeżeniu panelu administracyjnego ACF zaimportuje pola z pliku. Uwaga: przy tym procesie może dojść do nadpisania już istniejących definicji pól. Naprzeciw wychodzą rozwiązania jak xfive Plato, który pomaga kontrolować synchronizację.

Nie każdy jednak wie, że ACF pozwala również na pełną rejestrację pól wyłącznie w kodzie. Dla programisty jest to wygodne i bardziej niezawodne rozwiązanie.

Programowa rejestracja własnych pól – porządek i kontrola

ACF udostępnia własne API do rejestracji pól w czystym PHP. Grupy i pola można definiować, nie dotykając panelu, co jest kluczowe, jeśli zależy nam na version control, powtarzalności deploymentów, audytowalności zmian, czy współpracy zespołowej. Większość programistów po pewnym czasie przechodzi właśnie na to podejście. Podstawowa funkcja, jakiej używamy to acf_add_local_field_group() – jej zadaniem jest dodanie grupy wraz z polami.

Przykład rejestracji pojedynczego pola tekstowego przy pomocy API ACF:

<?php
add_action('acf/init', function() {
    acf_add_local_field_group([
        'key'    => 'group_custom_example',
        'title'  => 'Moja Grupa Custom Fields',
        'fields' => [
            [
                'key'          => 'field_custom_text',
                'label'        => 'Tekst niestandardowy',
                'name'         => 'custom_text',
                'type'         => 'text',
                'instructions' => 'Podaj krótki opis',
                'required'     => 0,
            ],
        ],
        'location' => [
            [
                [
                    'param'    => 'post_type',
                    'operator' => '==',
                    'value'    => 'post',
                ],
            ],
        ],
    ]);
});

Tak zadeklarowaną grupę pól dodajemy do panelu bezpośrednio przez kod w pliku functions.php (lub w innym ładowanym przez motyw pliku) lub jako fragment własnej wtyczki. Jest do dość wygodne, ale składnia jest raczej rozwlekła, prawda?

Jeszcze szybciej, jeszcze sprytniej – ACF Builder

W praktyce ręczne „wstukiwanie” tablic z polami przy rozbudowanych projektach bywa kłopotliwe – szybko rośnie ilość powtarzalnego, podatnego na literówki kodu, brakuje podpowiedzi IDE, całość robi się niezbyt czytelna. Tutaj z pomocą przychodzi ACF Builder – narzędzie typu fluent interface, które pozwala deklarować grupy pól i pola jednym, czytelnym łańcuchem wywołań metod.

ACF Builder to klasa PHP (dostępna jako pakiet Composera), która owija niskopoziomowe API ACF i upraszcza składnię. Pozwala na zdefiniowanie grupy pól poprzez wywołania metod, które są czytelne, zwięzłe i odporne na literówki. Przykład użycia:

<?php

use StoutLogicAcfBuilderFieldsBuilder;

add_action('acf/init', function() {
    $fields = new FieldsBuilder('dane_produktu');
    $fields
        ->addText('producent', [
            'label'        => 'Producent',
            'instructions' => 'Wpisz nazwę producenta',
        ])
        ->addNumber('cena', [
            'label'   => 'Cena',
            'prepend' => 'PLN',
        ]);
acf_add_local_field_group($fields->build());
});

Dzięki temu budujemy nawet rozbudowane, wielopoziomowe struktury pól w sposób łatwy do czytania i utrzymania, ograniczając zarówno potencjalne pomyłki, jak i czas implementacji. Podejście to jest godne polecenia zespołom długoterminowo rozwijającym customowe rozwiązania na WordPressie, gdzie kluczowe jest bezpieczeństwo i przewidywalność zmian.

ACF – tak, chcesz go używać

ACF to konieczność dla każdego, kto rozwija niestandardowe projekty w ekosystemie WordPressa. Początkujący docenią prostotę wizualnego konfigurowania własnych pól. Bardziej zaawansowani szybciej, czytelniej i bezpieczniej rozwiną swoje funkcjonalności, korzystając z rejestracji programowej, która zapewnia to powtarzalność, kontrolę nad środowiskiem i pełen spokój ducha nawet przy najbardziej nietypowych konfiguracjach pól.

Fot. overrust/Adobe Stock

Więcej wpisów