Standardowe pola WordPress wystarczają do pierwszego niestandardowego projektu. Gdy trzeba wyprowadzić cechy produktu na kartę, dodać galerię do strony lub dołączyć blok z warunkami dostawy, od razu napotyka się ograniczenia edytora: tytuł, treść, kategorie i to wszystko.

Jest na to sposób i nie jest nim ACF Pro za 149 USD rocznie. Niestandardowe metaboksy dodają dowolne pola bezpośrednio do interfejsu edycji wpisu, bez wizualnego kreatora i bez dziesiątki zbędnych modułów. CMB2 robi dokładnie to: udostępnia PHP API do opisywania metaboksów kodem, który znajduje się w systemie kontroli wersji, a nie w bazie danych.

Poniżej pełny cykl: od instalacji wtyczki po wyświetlenie danych na frontendzie. Na końcu artykułu otrzymają Państwo gotowy plik metaboksów, który można dostosować do dowolnego typu treści, od stron po produkty WooCommerce.

💡 Szybki przegląd:

• Zainstaluj CMB2 z katalogu WordPress.org: wtyczka jest bezpłatna i instaluje się ją dwoma kliknięciami.
• Utwórz plik metaboxes.php w folderze motywu i opisz potrzebne pola za pomocą haka cmb2_admin_init.
• Podłącz plik w functions.php jedną linijką require_once i sprawdź metaboks w panelu administracyjnym.
• Wyświetl zapisane dane na frontendzie za pomocą get_post_meta() z poprawnym eskejpowaniem.

Czym jest CMB2: kod zamiast wizualnego kreatora

CMB2 to biblioteka dla programistów, która tworzy metaboksy, pola niestandardowe i formularze w WordPress. Od razu po instalacji obsługuje dziesiątki typów pól: tekst, edytor WYSIWYG, przesyłanie plików, wybór daty, próbnik koloru, przyciski radiowe, listy rozwijane, pola powtarzalne i grupy.

Główna różnica w porównaniu z ACF: CMB2 nie ma wizualnego kreatora. Wszystkie metaboksy opisuje się w plikach PHP motywu. Dla programisty to zaleta: konfiguracja znajduje się w Git, nie można jej przypadkowo usunąć przez panel administracyjny, a przenoszenie między staging a production sprowadza się do wdrożenia kodu. Jednocześnie CMB2 jest całkowicie darmowa, podczas gdy ACF Pro kosztuje od 149 USD rocznie za pola powtarzalne i grupy.

Biblioteka jest aktywnie rozwijana od 2014 roku. Na WordPress.org wtyczka ma ocenę 5 gwiazdek i ponad 300 000 aktywnych instalacji. Repozytorium GitHub otrzymuje regularne aktualizacje: ostatnie wydanie zapewniło zgodność z PHP 8.4 i WordPress 6.7. To nie jest porzucony projekt, który zostanie zaniechany po pół roku.

Krok 1: Instalujemy wtyczkę

Proszę przejść do Wtyczki → Dodaj nową, wpisać „CMB2" w wyszukiwarce i kliknąć „Zainstaluj". Po aktywacji wtyczka ładuje silnik, ale sama w sobie niczego nie zmienia w panelu administracyjnym, metaboksy pojawią się dopiero po opisaniu ich w kodzie.

Jeśli podłączają Państwo CMB2 ręcznie wewnątrz motywu, bez instalacji przez panel administracyjny, proszę dodać na początku functions.php:

1
require_once __DIR__ . '/cmb2/init.php';

Dwie ważne kwestie. Po pierwsze: init.php musi być załadowany jak najwcześniej, poza jakimikolwiek hakami. Proszę nie opakowywać go w warunki if ( ! class_exists(..., CMB2 sam obsługuje konflikty ponownego ładowania. Po drugie: w przypadku ręcznego podłączenia aktualizacje CMB2 trzeba będzie wykonywać ręcznie, w przeciwieństwie do automatycznych aktualizacji przez panel administracyjny.

Krok 2: Piszemy plik metaboksów

Proszę utworzyć folder cmb2-metaboxes w katalogu głównym motywu potomnego i plik metaboxes.php w jego wnętrzu. W tym pliku zbierzemy wszystkie definicje pól.

Poniżej działający kod, który dodaje edytor tekstu, krótki opis i listę rozwijaną z odznaką do produktów WooCommerce. Proszę skopiować go do metaboxes.php:

1
add_action( 'cmb2_admin_init', 'sdstudio_register_metaboxes' );
2
 
3
function sdstudio_register_metaboxes() {
4
 
5
    $prefix = '_sdstudio_';
6
 
7
    $cmb = new_cmb2_box( array(
8
        'id'           => 'product_extra_info',
9
        'title'        => __( 'Дополнительная информация о товаре', 'cmb2' ),
10
        'object_types' => array( 'product' ),
11
        'context'      => 'normal',
12
        'priority'     => 'high',
13
        'show_names'   => true,
14
    ) );
15
 
16
    $cmb->add_field( array(
17
        'name'    => __( 'Описание для карусели на главной', 'cmb2' ),
18
        'desc'    => __( 'Текст, который будет показан в слайдере товаров.', 'cmb2' ),
19
        'id'      => $prefix . 'carousel_desc',
20
        'type'    => 'wysiwyg',
21
        'options' => array(
22
            'textarea_rows' => 5,
23
        ),
24
    ) );
25
 
26
    $cmb->add_field( array(
27
        'name' => __( 'Короткое описание', 'cmb2' ),
28
        'desc' => __( 'Одна строка — для карточки товара в сетке.', 'cmb2' ),
29
        'id'   => $prefix . 'short_desc',
30
        'type' => 'textarea_small',
31
    ) );
32
 
33
    $cmb->add_field( array(
34
        'name' => __( 'Бейдж товара', 'cmb2' ),
35
        'desc' => __( 'Метка «Новинка», «Хит» или «Распродажа».', 'cmb2' ),
36
        'id'   => $prefix . 'badge',
37
        'type' => 'select',
38
        'show_option_none' => true,
39
        'options'          => array(
40
            'new'   => __( 'Новинка', 'cmb2' ),
41
            'hit'   => __( 'Хит', 'cmb2' ),
42
            'sale'  => __( 'Распродажа', 'cmb2' ),
43
        ),
44
    ) );
45
 
46
}

Co tu się dzieje: hak cmb2_admin_init uruchamia się podczas ładowania panelu administracyjnego i rejestruje metaboks na stronie edycji produktu. new_cmb2_box() tworzy kontener z tytułem „Dodatkowe informacje o produkcie", a trzy wywołania add_field() dodają do niego pola: edytor WYSIWYG, kompaktowe pole tekstowe i listę rozwijaną z predefiniowanymi opcjami. Każde pole otrzymuje unikalny id z prefiksem _sdstudio_, co wyklucza konflikty z innymi wtyczkami.

Jeśli zamiast WooCommerce potrzebne są zwykłe strony, proszę zamienić 'object_types' => array( 'product' ) na 'object_types' => array( 'page' ). Dla kilku typów treści proszę podać je listą: array( 'page', 'post' ).

Pełną listę typów pól można znaleźć w oficjalnej dokumentacji CMB2 na GitHub. Od razu dostępne są dziesiątki opcji: od zwykłego tekstu i edytora WYSIWYG po przesyłanie plików, próbnik koloru, przyciski radiowe i taksonomie. Który typ wybrać do konkretnego zadania, proszę decydować na podstawie dokumentacji, a nie domysłów.

Krok 3: Podłączamy w functions.php

Teraz trzeba załadować utworzony plik. Proszę otworzyć functions.php motywu potomnego i dodać jedną linijkę przed zamykającym tagiem ?>, lub na końcu pliku, jeśli tagu nie ma:

1
require_once __DIR__ . '/cmb2-metaboxes/metaboxes.php';

Przed dodaniem kodu proszę zrobić kopię zapasową functions.php. Błąd składniowy w require_once położy witrynę z krytycznym błędem PHP, a przywrócenie pliku będzie możliwe tylko przez FTP lub panel hostingu. Po zapisaniu proszę otworzyć dowolny produkt w panelu administracyjnym i upewnić się, że metaboks „Dodatkowe informacje o produkcie" pojawił się pod edytorem treści.

Proszę wypełnić testowe pola i kliknąć „Aktualizuj". CMB2 automatycznie zapisuje dane w tabeli wp_postmeta. Żadne dodatkowe wywołania haka save_post nie są potrzebne: biblioteka przechwytuje zapis wpisu i sama obsługuje swoje pola.

Krok 4: Wyświetlamy dane na frontendzie

Dane są zapisane w bazie, pozostało pokazać je odwiedzającym. Proszę otworzyć plik motywu odpowiedzialny za stronę produktu, zazwyczaj jest to single-product.php lub content-single-product.php. Proszę dodać kod wewnątrz pętli WordPress:

1
<?php
2
$carousel_desc = get_post_meta( get_the_ID(), '_sdstudio_carousel_desc', true );
3
$badge         = get_post_meta( get_the_ID(), '_sdstudio_badge', true );
4
 
5
if ( ! empty( $carousel_desc ) ) : ?>
6
    <div class="product-carousel-desc">
7
        <?php echo wp_kses_post( $carousel_desc ); ?>
8
    </div>
9
<?php endif; ?>
10
 
11
<?php if ( ! empty( $badge ) ) : ?>
12
    <span class="product-badge product-badge--<?php echo esc_attr( $badge ); ?>">
13
        <?php echo esc_html( $badge ); ?>
14
    </span>
15
<?php endif; ?>
16

Analiza: get_post_meta() pobiera wartość według ID pola. Dla pola WYSIWYG proszę użyć wp_kses_post(), przepuszcza ona dozwolone tagi HTML i filtruje potencjalnie niebezpieczne. Dla zwykłego tekstu lub listy rozwijanej wystarczy esc_html(), która przekształca znaki specjalne na encje HTML i wyklucza XSS.

Jeśli metaboks został utworzony dla stron ('object_types' => array( 'page' )), proszę umieścić ten sam kod w page.php lub content-page.php. Mechanika jest taka sama: get_post_meta() wewnątrz pętli, eskejpowanie według typu pola.

Wideo: CMB2 od instalacji do działającego metaboksa

W tym 20-minutowym samouczku autor przechodzi pełny cykl: instalację, tworzenie pól, podłączenie pliku i wyświetlenie danych na frontendzie. Warto obejrzeć, jeśli instrukcja tekstowa pozostawiła luki.

⁉️🤔 Często zadawane pytania

Czym CMB2 różni się od ACF?

ACF udostępnia wizualny kreator pól bezpośrednio w panelu administracyjnym: można zbudować metaboks bez ani jednej linijki kodu. CMB2 wymaga opisywania pól w plikach PHP motywu. Dla programisty, który przechowuje konfigurację w Git, CMB2 jest wygodniejszy: metaboksy nie zależą od stanu bazy danych, nie można ich przypadkowo usunąć przez panel administracyjny, a przenoszenie między staging a production sprowadza się do wdrożenia kodu. ACF Pro kosztuje od 149 USD rocznie za pola powtarzalne i grupy, CMB2 jest bezpłatne.

Czy można używać CMB2 bez instalowania wtyczki?

Tak. Proszę skopiować folder CMB2 do wnętrza motywu i podłączyć init.php w functions.php, jak pokazano w kroku 1. Takie podejście jest wygodne w przypadku motywów premium, które muszą działać od razu po aktywacji, bez wymogu instalowania zewnętrznej wtyczki. Minus: aktualizacje CMB2 trzeba będzie wykonywać ręcznie z każdą nową wersją.

Czy pola CMB2 działają w edytorze Gutenberg?

Tak, metaboksy CMB2 są wyświetlane pod edytorem Gutenberg w standardowej formie, w sekcji pod treścią. Jednak od razu po instalacji nie integrują się one z blokami edytora. Jeśli trzeba osadzić pole bezpośrednio w bloku, konieczne będzie dodatkowe programowanie przez CMB2 API i register_block_type().

Co zrobić, jeśli metaboks nie pojawia się w panelu administracyjnym?

Proszę sprawdzić trzy rzeczy. Po pierwsze: czy object_types zgadza się z typem edytowanego wpisu, dla produktów WooCommerce wymagane jest 'product', a nie 'post'. Po drugie: czy nie ma błędu składniowego w PHP, proszę włączyć WP_DEBUG w wp-config.php i przejrzeć log. Po trzecie: czy prefiks id pól nie koliduje z inną wtyczką, proszę używać unikalnego prefiksu, takiego jak _sdstudio_.

Czy można tworzyć powtarzalne grupy pól?

Tak. CMB2 obsługuje pola powtarzalne przez flagę 'repeatable' => true i grupy powtarzalne przez $cmb->add_group_field(). Grupa pozwala dodać blok „Cecha: wartość" i tworzyć nowe wystąpienia przyciskiem „Dodaj wiersz" bezpośrednio w panelu administracyjnym.

Czy CMB2 działa z multisite?

Tak, wtyczka jest w pełni kompatybilna z WordPress Multisite. Metaboksy można rejestrować globalnie w functions.php aktywnego motywu sieci lub osobno dla każdej witryny. Wywołanie get_post_meta() działa identycznie w obu trybach.

CMB2 czy ACF: które podejście wybrać do swojego zadania

CMB2 realizuje dokładnie jedno zadanie: tworzenie niestandardowych metaboksów przez kod, z przechowywaniem konfiguracji w plikach motywu, a nie w bazie danych. Wybór sprowadza się do Państwa procesu pracy, a nie do abstrakcyjnego „co jest lepsze".

• Jeśli są Państwo programistą i przechowują całą konfigurację projektu w Git, proszę wybrać CMB2. Metaboksy żyją w metaboxes.php, są wdrażane razem z motywem i nie wymagają synchronizacji bazy danych między staging a production.

• Jeśli potrzebują Państwo wizualnego kreatora, powtarzalnych pól elastycznych i gotowych bloków do Gutenberg bez linijki kodu, proszę wybrać ACF Pro. Subskrypcja od 149 USD rocznie zwraca się szybkością prototypowania.

• Jeśli projekt już używa CMB2 i metaboksy działają stabilnie, proszę przy nim pozostać. Biblioteka nie jest porzucona, nie wymaga pilnej migracji i regularnie otrzymuje aktualizacje zgodności.

Proszę wypróbować oba podejścia na witrynie testowej: zbudować ten sam metaboks w CMB2 i w ACF. Różnica w podejściu stanie się oczywista w ciągu 20 minut. A jakiego narzędzia Państwo używają, proszę napisać w komentarzach.