Advanced Custom Fields (ACF) w WordPressie — poradnik z przykładami kodu

Advanced Custom Fields (ACF) to wtyczka do WordPressa, która pozwala dodać do edytora własne pola — np. cenę, datę wydarzenia, adres, galerię czy powiązane wpisy — i wyświetlić je w motywie jedną funkcją PHP get_field(). Dzięki temu redaktor wypełnia uporządkowany formularz, zamiast wpisywać wszystko w treść, a programista dostaje dane w przewidywalnej strukturze.

W tym poradniku przejdziemy przez cały proces na przykładzie strony z wydarzeniami: od instalacji, przez tworzenie grupy pól, po wyświetlanie wartości w szablonie, pola powtarzalne i filtrowanie wpisów po polach.

Czym są pola niestandardowe i do czego służy ACF

WordPress od zawsze pozwala zapisywać przy wpisie dodatkowe dane w tabeli wp_postmeta (para klucz–wartość). Natywny panel „Własne pola” jest jednak surowy: każdą wartość wpisujesz ręcznie jako tekst, bez walidacji, list wyboru czy wyboru obrazka z biblioteki.

ACF nakłada na ten mechanizm wygodny interfejs. Typowe zastosowania:

• katalogi i oferty — nieruchomości (metraż, liczba pokoi, cena), samochody, produkty bez sklepu,
• wydarzenia — data, godzina, miejsce, link do biletów,
• zespół i referencje — stanowisko, zdjęcie, profil LinkedIn,
• strony firmowe — edytowalne sekcje strony głównej, dane kontaktowe w ustawieniach motywu,
• headless WordPress — uporządkowane dane wystawiane przez REST API lub GraphQL do aplikacji frontendowej (więcej w artykule WordPress jako headless CMS).

ACF, ACF PRO i Secure Custom Fields — którą wtyczkę zainstalować

Od października 2024 roku sytuacja jest mniej oczywista niż kiedyś. W trakcie sporu między Automattic a WP Engine (właścicielem ACF) zespół WordPress.org utworzył fork o nazwie Secure Custom Fields (SCF). W efekcie istnieją dwie rozwijane niezależnie wtyczki o wspólnym rodowodzie:

Przy instalacji z katalogu wtyczek zwróć uwagę na nazwę autora. Kod motywu opisany w tym poradniku działa w każdej z tych wtyczek, ale nie instaluj dwóch naraz.

Krok 1: instalacja i rejestracja własnego typu wpisu

1. W panelu przejdź do Wtyczki → Dodaj nową wtyczkę, wyszukaj Advanced Custom Fields, zainstaluj i włącz (wersję PRO wgrywasz jako plik ZIP przez Wyślij wtyczkę na serwer).
2. W menu pojawi się pozycja ACF. Od wersji 6.1 możesz w niej zarejestrować własny typ wpisu bez kodu: ACF → Typy treści → Dodaj nowy.
3. Utwórz typ „Wydarzenia” (liczba pojedyncza „Wydarzenie”, klucz wydarzenie). Zaznacz, czy ma mieć archiwum i być widoczny w REST API.

Jeśli wolisz kod (np. w motywie potomnym lub wtyczce), odpowiednik wygląda tak:

add_action( 'init', function () {
    register_post_type( 'wydarzenie', [
        'label'        => 'Wydarzenia',
        'public'       => true,
        'has_archive'  => true,
        'show_in_rest' => true,
        'menu_icon'    => 'dashicons-calendar-alt',
        'supports'     => [ 'title', 'editor', 'thumbnail' ],
        'rewrite'      => [ 'slug' => 'wydarzenia' ],
    ] );
} );

Po dodaniu nowego typu wpisu wejdź w Ustawienia → Bezpośrednie odnośniki i kliknij Zapisz zmiany, żeby odświeżyć reguły adresów — inaczej podstrony wydarzeń zwrócą błąd 404.

Krok 2: tworzenie grupy pól

1. Przejdź do ACF → Grupy pól → Dodaj nową.
2. Nazwij grupę, np. „Dane wydarzenia”.
3. Dodaj pola (dla każdego ustaw etykietę, nazwę i typ):

4. W sekcji Ustawienia → Reguły lokalizacji wybierz: Typ treści jest równy Wydarzenie.
5. Opcjonalnie w ustawieniach grupy zaznacz Pokaż w REST API, jeśli dane mają być dostępne dla aplikacji zewnętrznych.
6. Zapisz. Przy dodawaniu nowego wydarzenia pod edytorem pojawi się formularz z polami.

Wskazówka: Utwórz w katalogu motywu pusty folder acf-json. ACF zacznie zapisywać tam definicje grup pól jako pliki JSON, które możesz trzymać w repozytorium Git i przenosić między środowiskiem testowym a produkcją bez ręcznego odtwarzania pól.

Krok 3: wyświetlanie pól w szablonie motywu

Pola odczytujesz w pliku szablonu, np. single-wydarzenie.php w motywie potomnym. Funkcja get_field() zwraca wartość, a o bezpieczne wyświetlenie dbasz sam:

<?php
$data   = get_field( 'data_wydarzenia' );
$miejsce = get_field( 'miejsce' );
$cena   = get_field( 'cena_biletu' );
$link   = get_field( 'link_bilety' );
$plakat = get_field( 'plakat' ); // ID obrazka
?>

<div class="wydarzenie-meta">
    <?php if ( $plakat ) : ?>
        <?php echo wp_get_attachment_image( $plakat, 'large' ); ?>
    <?php endif; ?>

    <?php if ( $data ) : ?>
        <p>Data: <?php echo esc_html( $data ); ?></p>
    <?php endif; ?>

    <?php if ( $miejsce ) : ?>
        <p>Miejsce: <?php echo esc_html( $miejsce ); ?></p>
    <?php endif; ?>

    <?php if ( '' !== $cena && null !== $cena ) : ?>
        <p>Cena: <?php echo esc_html( number_format_i18n( (float) $cena, 2 ) ); ?> zł</p>
    <?php endif; ?>

    <?php if ( $link ) : ?>
        <a href="<?php echo esc_url( $link ); ?>">Kup bilet</a>
    <?php endif; ?>
</div>

Kilka zasad, które oszczędzą Ci problemów:

• Sprawdzaj, czy pole ma wartość, zanim wyświetlisz etykietę — inaczej na stronie pojawią się puste „Miejsce:”.
• the_field() wypisuje wartość od razu i w nowszych wersjach ACF filtruje niebezpieczny HTML, ale jawne esc_html() i esc_url() przy get_field() są czytelniejsze i bezpieczniejsze.
• Pole z innego wpisu odczytasz, podając jego ID: get_field( 'miejsce', 123 ). Dla użytkownika użyj 'user_5', dla kategorii 'category_7', dla strony opcji 'option'.

Jeśli szablon nie wyświetla pól i nie wiesz dlaczego, włącz tryb debugowania WordPressa — literówka w nazwie pola nie generuje błędu, tylko zwraca null.

Pola powtarzalne i elastyczne (ACF PRO)

Pole Repeater pozwala dodać dowolną liczbę wierszy o tej samej strukturze — np. harmonogram wydarzenia z godziną i opisem punktu programu:

<?php if ( have_rows( 'harmonogram' ) ) : ?>
    <ul class="harmonogram">
        <?php while ( have_rows( 'harmonogram' ) ) : the_row(); ?>
            <li>
                <strong><?php echo esc_html( get_sub_field( 'godzina' ) ); ?></strong>
                <?php echo esc_html( get_sub_field( 'punkt_programu' ) ); ?>
            </li>
        <?php endwhile; ?>
    </ul>
<?php endif; ?>

Flexible Content idzie krok dalej: redaktor składa stronę z gotowych układów (np. „tekst ze zdjęciem”, „galeria”, „cennik”), a każdy układ ma własny zestaw pól. To popularna metoda budowania stron firmowych bez kreatorów wizualnych. Alternatywą są bloki ACF — własne bloki edytora Gutenberg, których pola wypełnia się bezpośrednio w edytorze blokowym (o samym edytorze przeczytasz w poradniku Gutenberga).

Filtrowanie i sortowanie wpisów po polach ACF

Ponieważ ACF zapisuje wartości w wp_postmeta, możesz używać ich w WP_Query. Pole Date Picker zapisuje datę w bazie zawsze w formacie Ymd (np. 20261015), niezależnie od formatu wyświetlania. Lista nadchodzących wydarzeń, posortowana od najbliższego:

$wydarzenia = new WP_Query( [
    'post_type'      => 'wydarzenie',
    'posts_per_page' => 10,
    'meta_key'       => 'data_wydarzenia',
    'orderby'        => 'meta_value',
    'order'          => 'ASC',
    'meta_query'     => [
        [
            'key'     => 'data_wydarzenia',
            'value'   => wp_date( 'Ymd' ),
            'compare' => '>=',
        ],
    ],
] );

Pamiętaj, że zapytania po meta_query są wolniejsze niż po taksonomiach, bo kolumna meta_value nie jest dobrze indeksowana. Do kategoryzowania (np. „koncert”, „warsztat”) lepiej użyć taksonomii, a pól — do wartości indywidualnych, takich jak data czy cena.

Uwaga: Nie zmieniaj nazwy (klucza) pola, które ma już wypełnione dane. ACF zapisze nowe wartości pod nową nazwą, a stare pozostaną w bazie pod starą — szablon nagle przestanie je widzieć. Zmieniaj tylko etykietę albo przenieś dane skryptem.

Alternatywy dla ACF

• Natywny panel „Własne pola” — w edytorze blokowym włączysz go w menu ⋮ → Preferencje → Ogólne → Zaawansowane → Własne pola. Wystarczy do prostych, pojedynczych wartości.
• register_post_meta() — rejestracja pól w kodzie z typem danych i widocznością w REST API, bez żadnej wtyczki.
• Meta Box, Pods, Carbon Fields — inne frameworki pól. Pods dodatkowo zarządza typami treści i relacjami, Carbon Fields definiuje wszystko w kodzie PHP.

Jeśli dopiero zaczynasz z PHP i chcesz lepiej rozumieć kod szablonów, zajrzyj do wprowadzenia do PHP. A gdy dane z ACF mają trafić do aplikacji mobilnej lub frontendu w JavaScripcie, podstawy pracy z API znajdziesz w tekście REST API — jak zacząć.