W tym artykule przedstawię możliwości pól niestandardowych i jednej z obowiązkowych wśród profesjonalnych WordPress deweloperów wtyczki Advanced Custom Fields. Chciałem zrobić tylko wprowadzenie a wyszedł praktycznie kompletny kurs standardowego mechanizmu Custom Fields oraz możliwości wtyczki ACF.
Wpis ten będzie uzupełnieniem artykułów o katalogu produktów i tworzenia własnych szablonów (i motywów) w WordPressie gdzie wspominałem o samym mechanizmie pól niestandardowych jak i wtyczce ACF. Zanim przejdziemy do praktycznych przykładów i kursu Advanced Custom Fields (także w wersji Pro), na początek warto zasięgnąć nieco teorii i zrozumieć czym są własne pola niestandardowe i jak działają.
Spis treści:
- Czym są własne pola (custom fields) w WordPressie?
- Tworzenie własnych pól w WordPress
- Advanced Custom Fields
- Pole powtarzalne
- Galeria zdjęć w ACF
- PageBuilder w ACF
- Własny blok Gutenberga w ACF
- Własne pola w Widgetach
- Własne pola w Menu
- Własna strona opcji w ACF
Czym są własne pola w WordPress?
Własne pola (ang. Custom Fields) zwane czasem polami niestandardowymi to dodatkowe informacje (metadane), które możemy dołączyć do dowolnego typu postu WordPress. Wartości przechowywane są w tabeli wp_postmeta i polegają na powiązanych z danym postem par typu klucz-wartość.
Metadane w Informatyce to dane opisujące inne dane.
Standardowy obiekt postu WordPressa składa się z kilku podstawowych pól. Możemy edytować ich wartości, umieszczać w szablonie strony a także dzięki nim filtrować i wyszukiwać konkretne wpisy w wyszukiwarkach. Pola które możemy dowolnie modyfikować to:
- tytuł artykułu,
- zalążek (ang. excerpt),
- treść artykułu.
Niektóre pola można edytować ale wymuszają na nas konkretny format danych:
- data opublikowania – wymaga formatu daty,
- data ostatniej edycji – jak wyżej,
- obrazek wyróżniający (ang. featured image) – wymagający pliku graficznego,
- slug – wymaga formatu zgodnego z wymogami adresów URL,
Niektóre pola mają charakter relacyjny i choć mamy na nie pewien wpływ, nie można ich dowolnie edytować:
- autor,
- poprzedni artykuł,
- następny artykuł
W przypadku nawet bardzo skomplikowanego bloga taka kolekcja pól, które możemy wypełnić własnymi wartościami jest w pełni wystarczająca.
Chcąc stworzyć katalog produktów, w którym powiedzmy, produkty mają jakiś konkretny kolor standardowe pola stają się nie wystarczające. Możemy oczywiście w treści napisać, że ten produkt ma kolor czerwony ręcznie stworzyć tabelkę ze specyfikacją albo, napisać, że dana praca w portfolio została wykonana dla konkretnej firmy.
Problem w tym, że takie informacje już trudniej przefiltrować, zaprezentować w listingu, sortować lub zastosować globalnie dla tych danych inne formatowanie lub fajnie ułożyć je we własnym szablonie.
Tworzenie niestandardowych pól w WordPress
Takie możliwości dają pola niestandardowe (ang. Custom Fields). WordPress bez żadnych dodatkowych wtyczek pozwala dodać niestandardowe pola meta do stron i wpisów, oraz nadawać im wartości bezpośrednio w trakcie edytowania strony w panelu.
Wystarczy w „Opcje” w „Zaawansowane panele” zaznaczyć opcję „Własne pola”.
Jeżeli korzystamy z edytora standardowego, włączenie własnych pól znajduje się w „Opcje ekranu” u góry po prawej stronie. Od tego momentu mamy dostęp do dodatkowego panelu z własnymi polami. Standardowo jest wyświetlany pod edytorem głównej treści.
Raz wprowadzone klucze można później wygodnie wybrać z listy – to ułatwia edycję kolejnych wpisów, które korzystają z tych samych pól. W każdym momencie można też dodawać nowe własne pola.
Wyświetlenie pól niestandardowych we własnym szablonie
Tak stworzone pola niestandardowe można łatwo wywołać we własnym szablonie wystarczy użyć instrukcji:
<?php echo get_post_custom_values('nazwa_pola'); ?>
Dla naszego przykładu nad albo pod instrukcją the_content(), która drukuje w szablonie główną zawartość podstrony można zrobić coś takiego:
Kolor: <?php echo get_post_custom_values('kolor_produktu'); ?>
Producent: <?php echo get_post_custom_values('producent'); ?>
Takie wykorzystanie własnych pól spokojnie wystarczy do stworzenia dedykowanych szablonów dla wpisów i stron. Niestety, mechanizm ten nie działa dla własnych typów postów ale w dalszych punktach pokażę jak to obejść.
Wyszukiwanie postów według wartości Custom Fields
Takie dane można też wykorzystać w filtrowaniu w trakcie wyszukiwania konkretnych postów. We wpisie o wyszukiwarce WordPress oraz w kursie tworzenia własnych szablonów, kod który wyszukiwał artykuł z daną frazą wyglądał tak:
$args = array( 's' => esc_html( get_search_query( false ) ), 'posts_per_page' => 32 );
Jeżeli chcemy przefiltrować strony w ramach wyszukiwarki lub stworzyć po prostu osobną stronę z konkretną wartością danego pola niestandardowego wystarczy do argumentów dodać tablicę meta_query:
$args = array(
'meta_query' => array(
array(
'key' => 'kolor_produktu',
'value' => 'czerwony')
)
);
W ten sposób WordPress zwróci nam wszystkie posty z daną wartością pola niestandardowego. Możemy stosować złożoną logikę z AND i OR (potrzebne dla zakresów) oraz porównywać wartości numeryczne np. większe bądź równe od parametru X i mniejsze bądź równe od parametru Y:
'meta_query' = array(
"relation" => "AND",
array(
"key" => "masa_minimum",
"value" => $_GET["masa_min"],
"type" => "numeric",
"compare" => "<="
),
array(
"key" => "masa_maksimum",
"value" => $_GET["masa_maks"],
"type" => "numeric",
"compare" => ">="
)
);
Advanced Custom Fields
Jeżeli możliwości pól niestandardowych wydają ci się w tym momencie nieograniczone to zapewniam, że to dopiero wierzchołek góry lodowej. Za pomocą specjalnej wtyczki ACF Advanced Custom Fields (autor: Elliot Condon) można wzbogacić panel do edycji – jak sama nazwa wskazuje – o zaawansowane formularze a dane niestandardowe mogą przybierać bardzo złożone struktury. Do tego wszystkiego dochodzi możliwość uproszczonego przechwytywania danych w kodzie szablonu. ACF pozwala też stworzyć dodatkowe pola we własnych typach postów.
Wtyczka ACF wykorzystując mechanizm pól niestandardowych pozwala między innymi na:
- dodawanie do stron edycji dodatkowych wygodnych i spersonalizowanych formularzy,
- dodawanie pól niestandardowych do postów, menu, widgetów, mediów, użytkowników a nawet ustawień WordPress,
- Stosowanie pól powtarzalnych, i elastycznych układów które można organizować za pomocą „przeciągnij i upuść”,
- tworzenie zaawansowanych galerii,
- wykorzystać pola niestandardowe we własnych blokach,
i wiele, wiele więcej.
Po instalacji wtyczki w wersji darmowej lub płatnej do WordPressa dochodzi nam kolejna podstrona o nazwie „Własne pola”. Możemy tam stworzyć Grupę pól a następnie przypisać ją do:
- konkretnego typu wpisu,
- szablonu,
- kategorii,
- taksonomii,
- konkretnej strony lub wpisu,
- widgetu,
- menu,
- bloku Gutenberga,
- Strony opcji
Za pomocą wygodnego kreatora możemy stworzyć spersonalizowany formularz z różnymi typami pól formularza:
Dla koloru można przypisać prawdziwy selektor koloru znany z aplikacji webowych a pole producenta możemy ograniczyć do konkretnych opcji:
Kiedy przejdziemy na wybrany typ wisu, pod edytorem ukażą się odpowiednie formularze. Można wybrać wartości domyślne i dodać instrukcje dla klienta. ACF pozwala też skonfigurować zasady logiczne dzięki którym ukryjemy dane pola w zależności od innych wartości. Trzeba przyznać, że edycja wartości w ten sposób jest dużo wygodniejsza i jest teraz w pełni profesjonalna.
ACF jest bardzo przyjazny dla deweloperów, dane można wygodnie otrzymać za pomocą krótkich instrukcji:
Kolor: <?php the_field( 'kolor' ); ?>
Producent: <?php the_field( 'producent' ); ?>
Kiedy chcemy tylko pobrać wartość bez wyświetlania jej, służy do tego instrukcja get_field(); Możemy też pobrać wartość pola niestandardowego z dowolnego innego posta dołączając jego ID jako drugi parametr tych funkcji:
get_field("kolor", 32);
Wartość własnego pola można też wplatać w treść za pomocą specjalnych makr czyli shortcode:
[acf field="kolor"]Posługiwanie się takimi shortcode’ami może być przydatne np. przy tworzeniu szablonów w Elementorze.
funkcja get_field() zwraca konkretną wartość lub obiekt. W przypadku chęci wygenerowania wartości w szablonie, wystarczy użyć funkcji the_field() lub get_field(). W przypadku obrazów mamy możliwość wyboru, czy funkcja ma zwracać id obrazka, adres url do oryginału czy całą tablicę.
Stosowanie tablicy jest naturalną metodą wyświetlenia zdjęcia załadowanego z biblioteki WordPress. Taki kod pozwala wyświetlić jego podstawowe pola:
<?php $obraz = get_field( 'obraz' ); ?>
<?php if ( $obraz ) { ?>
<img src="<?php echo $obraz['url']; ?>" alt="<?php echo $obraz['alt']; ?>" />
<?php } ?>
Jeżeli chcemy użyć konkretnego rozmiaru obrazka, wystarczy odwołać się do pod-tablicy sizes:
$obraz = get_field("obraz");
$miniaturka = $obraz["sizes"]["thumbnail"];
$duzy_rozmiar = $obraz["sizes"]["large"]
$oryginal = $obraz["url"]
Pole powtarzalne (PRO)
Pole powtarzalne to jak sama nazwa wskazuje, grupa pól, które możemy powielać w jednym miejscu. Przykładowym zastosowaniem tego elementu ACF może być lista ikon z linkami, sekcja FAQ lub slajder z napisami i linkami.
Pole powtarzalne jest tylko kontenerem na inne pola. Dla zobrazowania możemy wykonać pole, które obsługiwałoby funkcjonalność slajdera:
Pola można sortować za pomocą „przeciągnij i upuść. Przy okazji wklejane linki są walidowane pod kątem zgodność z wymogami url a zdjęcia są ładowane standardowo do biblioteki co pozwala wykorzystać automatycznie generowane rozmiary. Z perspektywy użytkownika edytującego stronę całość wygląda tak.
Jeżeli chcemy w szablonie wyciągnąć wszystkie pola, całość będzie wyglądać mniej więcej tak:
<?php if ( have_rows( 'slajder' ) ) : ?>
<?php while ( have_rows( 'slajder' ) ) : the_row(); ?>
<?php $obraz = get_sub_field( 'obraz' ); ?>
<?php if ( $obraz ) { ?>
<img src="<?php echo $obraz['url']; ?>" alt="<?php echo $obraz['alt']; ?>" />
<?php } ?>
<?php the_sub_field( 'tekst' ); ?>
<a href="<?php the_sub_field( 'link' ); ?>">Czytaj więcej</a>
<?php endwhile; ?>
<?php else : ?>
<?php // no rows found ?>
<?php endif; ?>
Tworzenie galerii zdjęć w ACF
WordPress od zawsze umożliwiał tworzyć galerię zdjęć. Problem pojawia się wtedy, kiedy chcemy mieć stu procentową kontrolę nad wygenerowanym przez galerię kodem HTML. Oczywiście istnieje mnóstwo technik z użyciem str_replace, filtrów i tym podobnych sztuczek. Za pomocą ACF możemy bez stresu stworzyć własną strukturę galerii. Idea jest bardzo podobna do pola powtarzalnego z tym, że jest możliwe „hurtowe” dodawanie zdjęć i łatwo je można sortować.
Tak wygląda galeria z perspektywy użytkownika:
A tak będzie wyglądał kod służący wygenerowaniu takiej galerii na front-endzie:
<?php $galeria_images = get_field( 'galeria' ); ?>
<?php if ( $galeria_images ) : ?>
<?php foreach ( $galeria_images as $galeria_image ): ?>
<a href="<?php echo $galeria_image['url']; ?>">
<img src="<?php echo $galeria_image['sizes']['thumbnail']; ?>" alt="<?php echo $galeria_image['alt']; ?>" />
</a>
<p><?php echo $galeria_image['caption']; ?></p>
<?php endforeach; ?>
<?php endif; ?>
Tworzenie własnego PageBuildera – Elastyczna treść ACF
Wyobraźmy sobie pole powtarzalne, których elementy podrzędne nie muszą mieć jednego szablonu a kilka. Tym sposobem możemy zaimplementować do naszego szablonu coś na kształt PageBuildera.
Wystarczy wybrać pole elastyczna treść i tak jak tworzyliśmy zawartość pola powtarzalnego, tak możemy stworzyć kilka jego wariantów:
W back-endzie generujemy frontend za pomocą szeregu elseif:
<?php if ( have_rows( 'content' ) ): ?>
<?php while ( have_rows( 'content' ) ) : the_row(); ?>
<?php if ( get_row_layout() == 'sekcja_4-4-4' ) : ?>
<?php the_sub_field( 'tytul' ); ?>
<?php the_sub_field( 'podtytul' ); ?>
<?php the_sub_field( 'pole_1' ); ?>
<?php the_sub_field( 'pole_2' ); ?>
<?php the_sub_field( 'pole_3' ); ?>
<?php elseif ( get_row_layout() == 'galeria_odnosnikow' ) : ?>
<?php the_sub_field( 'tytul' ); ?>
<?php the_sub_field( 'podtytul' ); ?>
<?php if ( have_rows( 'element' ) ) : ?>
<?php while ( have_rows( 'element' ) ) : the_row(); ?>
<?php $obrazek = get_sub_field( 'obrazek' ); ?>
<?php if ( $obrazek ) { ?>
<img src="<?php echo $obrazek['url']; ?>" alt="<?php echo $obrazek['alt']; ?>" />
<?php } ?>
<?php the_sub_field( 'tytul' ); ?>
<?php the_sub_field( 'strona' ); ?>
<?php endwhile; ?>
<?php else : ?>
<?php // brak elementów ?>
<?php endif; ?>
<?php endif; ?>
<?php endwhile; ?>
<?php else: ?>
<?php // brak elementów ?>
<?php endif; ?>
Dzięki temu mamy możliwość w edycji posta lub strony wykorzystać nasz PageBuilder:
W ten sposób stworzyłem między innymi własną stronę główną i stosuję w projektach klientów zawsze wtedy, kiedy potrzeba wygodnego, szybkiego i wydajnego PageBuildera. w którym mamy kontrolę nad każdą linijką kodu
Tworzenie własnego bloku Gutenberg w ACF
Niesamowicie przydatną funkcjonalnością najnowszej wersji ACF Pro jest możliwość stworzenia własnego bloku. Tworzenie własnego bloku bez wsparcia ze strony frameworka ACF w WordPressie może być bardzo problematyczne – wymaga napisania sporo kodu PHP i JavaScript.
W ACF można dosłownie „wyklikać” własny blok i zdefiniować strukturę HTML jaką chcemy osiągnąć po umieszczeniu go w Gutenbergu.
Na samym początku musimy zarejestrować blok:
function my_acf_init() {
if( function_exists('acf_register_block') ) {
acf_register_block(array(
'name' => 'karuzela',
'title' => ('Testowy blok'), 'description' => ('Blok dla testów'),
'render_callback' => 'acf_testowy_blok_callback',
'category' => 'formatting',
'icon' => 'admin-comments',
'keywords' => array( 'carousel', 'karuzela', 'slajder' ),
));
}
}
add_action('acf/init', 'my_acf_init');
Teraz możemy dodać blok w panelu ACF:
Następnie tworzymy callback. Dla testu chcemy osiągnąć napis Wartość pola i wartość wpisaną w bloku:
function acf_testowy_blok_callback( $block ) {
$avatar = get_field('avatar');
$id = 'testowyblok-' . $block['id'];
$align_class = $block['align'] ? 'align' . $block['align'] : '';
?>
<h2>Wartość pola: <?php the_field('test-bloku'); ?></h2>
<?php
}
Jak widać do Gutenberga doszedł nasz blok:
Wpisujemy wartość (lub dodajemy zdjęcia w sidebarze) i na bieżąco dokonuje się renderowanie bloku:
W sidebarze może być pole powtarzalne, galeria lub elastyczna treść – dokładnie ten sam zestaw jaki można wykorzystać w tradycyjnych custom fields.
Własne pola na stronie kategorii i w innych taksonomiach
Pewnie nie raz zaistniała lub zaistnieje potrzeba edytowania tła strony lub nagłówka na stronie kategorii – a może chcieliśmy nadać kategoriom własny, odróżniający je od innych kolor? Nic prostszego, wystarczy stworzyć grupę w ACF i wybrać kategorię jako obiekt do którego chcemy je przypisać:
Na standardowej stronie edycji kategorii pojawią się dodatkowe pola – w tym przypadku wybór obrazka:
Aby wyświetlić zdjęcie na front-endzie strony kategorii (lub przypisanego do kategorii posta), wystarczy użyć takiego kodu:
<?php $taxonomy_prefix = "category"; $categories = get_the_category(); $category_id = $categories[0]->cat_ID; $term_id_prefixed = $taxonomy_prefix .'_'. $category_id; $obraz_kategorii = get_field( 'obraz_kategorii', $term_id_prefixed );
Podobnie postępujemy z innymi taksonomiami (także własnymi) zmieniając wartość zmiennej $taxonomy_prefix.
Advanced Custom Fields w widgetach
Niestandardowe pola ACF można dodawać do widgetów. Ręczne tworzenie i obsługa skomplikowanych formularzy w widgetach może być męcząca. ACF rozwiązuje ten problem. Można wyklikać dany formularz i dodać klika linijek kodu do funkcji widgeta.
Czytaj więcej jak tworzyć i programować własne widgety WordPress.
Niestandardowe pola ACF w menu
Praktycznym przykładem wykorzystania ACF w menu jest chęć dodania ikon do elementów menu lub tła obrazkowego. Taka funkcjonalność przyda się w najbardziej wymyślnych i kreatywnych realizacjach. W jednej z realizacji umożliwiłem tworzyć skomplikowane mega-menu-wykorzystując ten mechanizm:
Czytaj więcej o tym jak w funkcji menu przechwytywać dane z ACF w artykule tworzenie i programowanie własnego menu w WordPress.
Własna strona opcji / ustawień motywu w ACF
Za pomocą ACF jest możliwość łatwego stworzenia własnej strony z ustawieniami dotyczącymi np. bieżącego motywu. Można stworzyć kilka rodzajów nagłówka i umożliwić klientowi wybór jednego z nich. Strona ustawień to też miejsce na dostosowanie kolorystyki czy stałych tekstów.
Zamiast tworzyć osobny widget można utworzyć grupę pól a następnie odwoływać się do nich z dowolnego miejsca w szablonie. Najpierw musimy zarejestrować stronę z Ustawieniami. Można stworzyć także osobne podstrony:
if( function_exists('acf_add_options_page') ) {
acf_add_options_page(array('page_title' => __('Ustawienia ACF')));
}
Teraz przechodzimy do wtyczki ACF i przypisujemy utworzoną grupę do dodanej strony ustawień:
Możemy teraz przystąpić do edycji naszych ustawień. Załóżmy, że parametryzujemy tekst widoczny zazwyczaj pod stopką każdej podstrony konwencjonalnego serwisu.
Aby wyświetlić wprowadzone dane wystarczy użyć znanej już funkcji get_field() lub the_field(), drugim argumentem funkcji będzie 'option’:
<?php the_field( 'copyright', 'option' ); ?>
Jeżeli chcemy stworzyć podstrony ustawień – bo przykładowo jest ich dużo i chcemy uczynić je bardziej czytelnymi wystarczy użyć funkcji acf_add_options_sub_page(). Sprawdź przykład z jednej z mojej realizacji: https://github.com/mansfeld/wordpress/blob/master/theme-customization/acf-settings.php
Dodatkowe pola w formularzu rejestracji i profilu użytkownika
Wtyczka ACF pozwala także łatwo dodać niestandardowe formularze do okna rejestracji oraz do podstrony gdzie edytujemy szczegóły o użytkownikach. Otwiera to przed nami ogrom możliwości pod kątem tworzenia specjalnych stref klienta lub paneli użytkownika. Sprawdź osobny wpis na temat panelu klienta w WordPress.
Wsparcie wielojęzyczności w ACF
Tak jak i w innych przypadkach także przy polach ACF można wykorzystać specjalną funkcję do zapewnienia wsparcia wielojęzyczności w WordPress. Wystarczy, że wszelkie wyrażenia typu:
<?php echo get_field("pole"); ?>
Będziemy otaczać według wymogów WMPL:
<?php _e(get_field("pole"), "my-textdomain") ?>
W przypadku droższych wersji WPML otrzymujemy wtyczkę wspierającą strony stworzone przy użyciu ACF.
Dla każdego pola w ACF możemy wybrać, czy pole ma być skopiowane, oddzielnie tłumaczone, czy pominięte na innych wersjach językowych konkretnej strony.
Wsparcie REST API
Przez pewien czas wartości przechowywane w polach ACF były nieosiągalne w REST API. Deweloperzy byli zmuszeni do skorzystania z wtyczek np. ACF to REST API autora Aires Gonçalves. Po zainstalowaniu wtyczki pola są osiągalne z endpointu /wp-json/wp/v2/. Wtyczka dodaje osobny obiekt ACF, który przechowuje wszystkie pola w postach, własnych typach postów itd… Od wersji 5.11 rozszerzenie ACF natywnie wspiera WP REST API. Czytaj więcej o WordPress REST API
Przydatne wtyczki współpracujące z ACF
Wtyczka ACF jest na tyle popularna, że powstało wiele wtyczek współpracujących lub rozbudowujących możliwości Advanced Custom Fields.
- WPML (w wersji conajmniej Multilingual CMS) – dodaje do ACF opcje związane z wielojęzycznością,
- ACF Theme Code / Pro – umożliwia automatyczne wygenerowanie szkieletu kodu potrzebnego do zakodowania skonfigurowanych pól w szablonie,
- Advanced Forms / Pro – pozwala tworzyć formularze za pomocą ACF, które można umieścić na front-endzie WordPressa.
Częste problemy z innymi wtyczkami
Niektóre wtyczki nie są przygotowane na przechowywanie treści we własnych polach i wykorzystywanie wtyczki ACF / ACF Pro
Yoast SEO
Dosyć często klienci korzystają z Yoast SEO i funkcji analizy tekstu pod kątem ilości występowania danych słów w tekście. Yoast SEO nie bierze pod uwagę tekstu zapisanego we własnych polach. Aby temu zaradzić wystarczy zainstalować kolejną wtyczkę: ACF Content Analysis for Yoast SEO.
Podsumowanie
Mechanizm własnych pól można znaleźć w praktycznie większości profesjonalnych i nowoczesnych systemów CMS. Z wykorzystaniem ACF, które jest czymś w rodzaju standardu w środowisku WordPress developerów, możemy tworzyć i rozszerzać wpisy, strony i własne typy postów o niemal nieograniczonej ilości pól.
Popularność wtyczki Advanced Custom Fields powoduje jej ciągłe wsparcie oraz dostępność integracji z innymi wtyczkami. Coraz to nowe wersje WordPressa i ACF otwierają przed deweloperami ogromne możliwości: własny PageBuilder, własny blok Gutenberga czy własna strona opcji w WordPressie a to wszystko bez nadmiernego kodowania.
Mateusz W pisze: 
karol 
Ela 
Lukas 
Andrzej 
Odpowiedz lub skomentuj