Utwórz niestandardowy blok Gutenberga – część 9: Dynamiczne bloki i renderowanie PHP

Do tej pory renderowaliśmy dane wyjściowe bloku w JavaScript. Jednak w przypadku dynamicznej zawartości, takiej jak ostatnie posty lub wyświetlanie posta, musimy renderować wyjście bloku w PHP. W tym poście dowiemy się jak i dlaczego.

Dlaczego musimy inaczej obsługiwać bloki dynamiczne?

Niektóre przykłady są oczywiste; blok wyświetlający najnowsze posty w kategorii jest dynamiczny, ponieważ posty będą się zmieniać w czasie. Nie wybierasz postów w bloku; zamiast tego prawdopodobnie będziesz mieć ustawienia wyboru kategorii, jakie informacje mają być wyświetlane dla każdego posta, liczba postów, liczba kolumn i tak dalej. Za każdym razem, gdy WordPress ładuje post z tym blokiem, musi w tym czasie zapytać WordPressa o najnowsze posty. Wyświetlenie tego samego posta miesiąc później może dać inne wyniki, nawet jeśli post z samym blokiem nie został zaktualizowany.

Jednak konieczność stosowania bloków dynamicznych czasami nie jest aż tak oczywista. Możesz sobie wyobrazić, że polecany blok postów, w którym wybierasz jeden konkretny post do wyświetlenia, niekoniecznie jest dynamiczny. Ale może być – i powinno być. Pamiętaj, że wybrany post może w dowolnym momencie zaktualizować tytuł, fragment lub wyróżniony obraz – i powinno to być odzwierciedlone w blokach, które zawierają ten post.

Aby utworzyć niedynamiczny blok do wyświetlania pojedynczego posta, musisz zapisać identyfikator posta, jego adres URL, adres URL polecanego obrazu, ciąg fragmentu lub cokolwiek, czego potrzebujesz, aby wyświetlić podgląd posta, w atrybutach bloku. I w tym tkwi problem. Jeśli zaktualizujesz polecany obraz wybranego posta, post z blokiem polecanego posta nie zaktualizuje automatycznie swoich atrybutów. Pozostanie zapisany z adresem URL starego polecanego obrazu. Dopiero gdy edytujesz post z blokiem i upewnisz się, że ponownie zapisze atrybuty ze zaktualizowanymi informacjami, blok wyświetli poprawne zaktualizowane informacje.

Tak więc zawsze, gdy mamy do czynienia z treściami dynamicznymi – postami, kategoriami lub czymkolwiek, co może się z czasem zmienić – mamy do czynienia z blokami dynamicznymi. A w przypadku bloków dynamicznych musimy użyć PHP – kodu po stronie serwera – do renderowania naszego bloku, aby zapewnić, że będzie pobierał zaktualizowane informacje za każdym razem, gdy jest renderowany.

Zmieniony charakter bloków dynamicznych w edytorze

Kiedy zaczniesz tworzyć dynamiczne bloki, zmieni się charakter Twojego bloku w edytorze. Funkcja Twojego bloku również editczęsto musi być dynamiczna. Na przykład w przypadku bloku polecanych postów musisz pobrać posty do wyboru, a w przypadku bloku najnowszych wiadomości musisz pobrać listę kategorii do wyboru przez użytkownika.

W pełni możliwe jest żądanie informacji z WordPressa z poziomu edytora, wykonując żądania AJAX – używając pakietów i komponentów lub wykonując je ręcznie za pomocą WordPress REST API. Niezależnie od wybranej metody blok musi obsługiwać asynchroniczny strumień danych wejściowych – ramy czasowe podczas oczekiwania na odpowiedź.

Istnieje wiele metod i wzorców tworzenia dynamicznego bloku dla Gutenberga. Najczęściej będziesz używał wzorca React zwanego komponentami wyższego rzędu, w którym WordPress zapewnia mnóstwo funkcji i komponentów.

Przyjrzymy się, jak pobierać posty i jak pobierać kategorie w naszym bloku w następnej części samouczka. Na razie musimy się nauczyć, jak sprawić, by PHP renderował nasz blok.

Przygotowanie naszego bloku do renderowania PHP

Główną częścią, którą musimy zrobić w JavaScript, jest savezwrócenie funkcji bloku null. Możesz zachować oryginalne wyjście, ale gdy powiemy WordPressowi, aby używał PHP do renderowania bloku, zostanie to zignorowane. Aby było jasne dla siebie i innych, że wyjście bloku nie jest obsługiwane w JavaScript, zmienimy savefunkcję.

Nie zapominaj, że zmiana funkcji zapisu spowoduje zerwanie wszystkich istniejących bloków. Ponownie dodaj blok. Blok powinien działać tak jak poprzednio; z ustawieniami i aktualizacją atrybutów. Teraz po prostu nie wypisze niczego w interfejsie. Będzie tam blok komentarza, przechowujący wszystkie atrybuty w JSON, ale nie jest renderowany żaden widoczny kod HTML.

Jednakże; jeśli którykolwiek z Twoich atrybutów korzysta z tej sourcewłaściwości, musisz to zmienić. Nie jest to obsługiwane w przypadku bloków renderowanych za pomocą PHP, ponieważ są one analizowane bezpośrednio z wyjścia zapisu – do czego teraz wracamy null. Używamy source na drugim RichTextw naszym bloku – dla akapitu. W tym momencie edytor w ogóle nie zapisze tego, co w nim umieścisz RichText.

Jeśli więc nadal używasz sourceatrybutu myRichText, musimy usunąć właściwości sourcei selector, aby upewnić się, że atrybuty będą przechowywane, a nie analizowane z savefunkcji:

attributes: {
    ...
    myRichText: {
        type: 'string',
    },
    ...

Po tym nasz blok jest gotowy do renderowania w PHP. Możemy zostawić pliki Javascript (nie zapomnij go zbudować), a resztę zrobimy w PHP.

Bloki renderowania w PHP

Aby nakazać WordPressowi renderowanie wyjścia bloku w PHP, dodajemy nowy argument do funkcji register_block_type(). Musimy dodać klucz render_callbackdo tablicy z wartością funkcji, którą ma uruchomić.

Funkcja renderowania PHP

Zdefiniujmy funkcję awp_myfirstblock_renderdalej functions.php(lub gdziekolwiek umieściłeś swój kod PHP). Nasza funkcja otrzyma dwa parametry; nazwiemy je $attri $content.

function awp_myfirstblock_render($attr, $content) {
    // return the block's output here
}

Parametr $attrbędzie tablicą asocjacyjną ze wszystkimi zapisanymi atrybutami. Drugi parametr, $content, dotyczy bloków wewnątrz naszego bloku. Dotyczy to tylko bloków, które obsługują bloki zagnieżdżone – co na przykład robią kolumny lub osłona.

Funkcja nigdy nie powinna echonic nie działać. Wszystkie dane wyjściowe muszą zostać zwrócone, więc musisz zbudować łańcuch i zwrócić go na końcu.

Należy pamiętać o atrybutach, że tylko zapisane atrybuty pojawią się w pierwszym parametrze funkcji. Jeśli atrybut nigdy nie został faktycznie zmieniony i zapisany – tj. polegał tylko na its default, atrybut nie zostanie w ogóle uwzględniony w naszej funkcji PHP.

Musisz poradzić sobie z tym problemem albo zawsze sprawdzając if (isset($attr['...'])), albo w preferowany sposób: definiując atrybuty w naszym register_block_type()wywołaniu. Możemy podać inny klucz attributesi ustawić jego wartość na tablicę ze wszystkimi atrybutami, które chcemy wyodrębnić z naszego bloku. Struktura powinna być identyczna z tą, którą zdefiniowałeś w JavaScript, ale zamiast obiektu JavaScript potrzebujesz go w tablicy PHP. Przedefiniowanie tych samych atrybutów może być trochę kłopotliwe, ale z inteligentnym edytorem kodu powinno być dość szybkie skopiowanie+wklejenie i wielowierszowa edycja do PHP.

Dodanie atrybutów dla naszej funkcji render

Dodajmy nowy attributeselement register_block_type()i wklejmy dokładnie te same atrybuty, które zdefiniowaliśmy w naszym pliku JavaScript:

Pamiętaj, że jeśli zdefiniujesz a defaultdla wszystkich atrybutów, $attrparametr Twojej funkcji powinien zawsze zawierać wszystkie atrybuty. Na przykład textAlignmentpowyższy atrybut będzie istniał tylko $attrwtedy, gdy został zmieniony – i musisz sprawdzić isset($attr['textAlignment']).

Niestety, w tej chwili są dwie rzeczy, których nie będziesz mieć w przypadku PHP block render. Jednym z nich jest classNamerekwizyt – więc musisz sam zbudować klasę owijania (jeśli chcesz). Druga to supportwłaściwość wyrównania bloków. Obecnie WordPress nie obsługuje tej właściwości w blokach dynamicznych. Nie zdobędziemy wartości wybranego wyrównania bloku, chyba że zmienimy go na atrybut i obsłużymy go ręcznie w JavaScript.

Jeśli chodzi o wyjście HTML funkcji, to w pełni zależy to od Ciebie!

Żądanie renderowania PHP z wewnątrz edytora

Możliwe jest zażądanie renderowania PHP naszego bloku wewnątrz edytora. Jest to przydatne, jeśli chcesz mieć możliwość podglądu wyjścia bloku w edytorze. Możemy to zrobić za pomocą komponentu wywoływanego ServerSideRenderz wp.editorpakietu.

Jako rekwizyty ServerSideRendermusisz zdefiniować wszystkie atrybuty, które chcesz przekazać. Jako minimum musisz podać nazwę bloku do prop block, aby WordPress wiedział, jakiej metody renderowania szukać. Jest to dostępne dla Ciebie w props.namefunkcji edit. Musisz również podać wszystkie potrzebne atrybuty w prop attributes. Jeśli chcesz, możesz tutaj również dodać niestandardowe zmienne poza atrybutami. Pamiętaj tylko, że będzie to działać tylko w edytorze wewnętrznym, a nie w interfejsie.

Nie możesz użyć ServerSideRenderw funkcji bloku save. Twoja savefunkcja musi nadal zwracać null.

Zaimplementujmy ServerSideRenderw naszym bloku, aby zobaczyć to w praktyce.

Używanie ServerSideRender do podglądu/edycji bloku

Jeśli wykonałeś poprzedni krok, w którym stworzyliśmy przełącznik trybu podglądu/edycji dla naszego bloku, możemy teraz użyć ServerSideRenderdo renderowania podglądu bloku z PHP, gdy przełączymy się do trybu podglądu.

Najpierw musimy pamiętać o destrukturyzacji ServerSideRenderna górze:

const { ServerSideRender } = wp.editor;

Jeśli pamiętasz z poprzedniego kroku, użyliśmy komponentów Disabledi/lub Placeholderdo trzymania podglądu. Problem z używaniem Placeholderpolega na tym, że otrzymujemy niechcianą stylizację na naszym wyjściu. Zastąpmy. Placeholder_ ServerSideRenderMożesz zachować Disabledkomponent, aby upewnić się, że żadna jego zawartość nie będzie klikalna ani przeciągana.

W kodzie do renderowania bloku, gdy atrybut editModema wartość false, robimy:

Teraz nasz niestandardowy przycisk na pasku narzędzi wyrenderuje dane wyjściowe z PHP, gdy przełączymy się w tryb podglądu. Dane wyjściowe powinny być identyczne podczas przeglądania posta w interfejsie użytkownika. Jest to dobry zwyczaj, aby upewnić się, że dane wyjściowe są identyczne zarówno w edytorze, jak i interfejsie.

Przykład: Dynamiczny blok pokazujący wybrany post

Dane wyjściowe w funkcji renderowania PHP mogą być dowolne i masz pełny dostęp do wszystkich funkcji WordPress. Załóżmy blok, w którym w atrybucie zostanie zapisany identyfikator posta. W render_callbackfunkcji PHP możesz wysłać zapytanie do wiadomości na podstawie identyfikatora i wyświetlić jego informacje. Powinno być dość oczywiste, jak to zrobić, ale oto szybki przykład.

Uwaga: w tym przykładzie po prostu dodamy tekst do edytora, aby ręcznie wprowadzić identyfikator posta. Nie jest to bardzo intuicyjne i przyjazne dla użytkownika rozwiązanie wyboru posta – ale o tym nauczymy się w następnym kroku. Skupiamy się tutaj na części PHP renderowania wybranego posta.

Dodajmy atrybut selectedPostIdo numerze typu:

attributes: {
    selectedPostId: {
        type: 'number'
    }
}

A gdzieś wewnątrz editfunkcji naszego bloku dodajemy TextControlkomponent. Może być gdziekolwiek chcesz – w bloku lub w Inspektorze.

Zwróć uwagę, że bardzo dbam o to, aby dane wejściowe poprawnie zapisały atrybut jako liczbę, konwertując go na liczbę całkowitą za pomocą parseInt(). Mimo że ustawiliśmy type prop typena number, aby wyrenderować dane wejściowe liczbowe, zmieniona wartość jest nadal interpretowana jako ciąg znaków. WordPress nie zapisze Twojego atrybutu, jeśli ma zły format.

Nie zapomnij dodać nowego atrybutu do swojego ServerSideRenderkomponentu, jeśli taki posiadasz:

Część PHP

To powinno zająć się częścią JavaScript. Przejdźmy do PHP. Najpierw musimy dodać nowy atrybut selectedPostIddo attributestablicy w register_block_type():

W render_callbackfunkcji możemy teraz uzyskać dostęp do identyfikatora posta za pomocą $attr['selectedPostId']. Możemy dzięki temu wykonać proste get_post()i wyprowadzić dane posta; jego link i tytuł:

To jest bardzo prosty przykład, który ma służyć jako trampolina do pisania bardziej zaawansowanego i niestandardowego kodu.

Teraz, gdy wiemy, jak radzić sobie z renderowaniem bloków dynamicznych, następnym krokiem jest nauczenie się, jak sprawić, by część edytora była również bardziej intuicyjna. W następnym kroku skupimy się na tym, jak wyszukiwać posty z poziomu edytora bloków i zapewnić użytkownikowi lepszy sposób wybierania postu.