Headless CMS – WordPress jako backend Twojego serwisu

Headless CMS to pojęcie, które w ostatnim czasie zyskuje na popularności, zwłaszcza wśród osób zajmujących się frontendem. Dlaczego tak się dzieje i czym jest headless CMS?

W skrócie – Headless CMS polega na odseparowaniu od siebie backendu (body) i frontendu (head) aplikacji. Mianem body określa się CMS dostarczający narzędzi do tworzenia i zarządzania treścią, która jest udostępniana przez interfejs API. Warstwę prezentacji nazywamy head. Head to, na przykład, strona WWW, sklep internetowy, aplikacja mobilna i tym podobne. Dzięki oddzieleniu head od body zyskujesz wyraźnie odseparowaną warstwę backendową od frontendowej. Taka architektura umożliwia programistom frontend tworzenie zaawansowanych stron bez znajomości technologii backendowych.

Przeciwieństwem headless CMS jest, na przykład, WordPress, w którym backend i frontend są integralną częścią. Często określa się takie CMSy monolitami. W tradycyjnym podejściu CMSy, takie jak WordPress, dostarczają narzędzi do tworzenia i zarządzania treścią oraz, w przeciwieństwie do headless, warstwę frontendową. Tworząc stronę w oparciu o WordPressa programista musi dysponować zarówno wiedzą z technologii backendowych jak i frontendowych.

Istnieje jednak możliwość, aby użyć WordPressa jako headless CMSa. W ramach tego poradnika dowiesz się, jak to zrobić budując swój blog, który będziesz rozwijać wyłącznie w technologiach frontendowych. Wszystko to będzie możliwe dzięki WordPress REST API.

Do kogo kierowany jest ten poradnik?

Poradnik kierowany jest do osób, które poszukują backendu dla swoich projektów i mają doświadczenie z technologiami frontendowymi oraz posiadają podstawowe doświadczenie w pracy z frameworkami JavaScript, np. Vue.js, React.js, Svelte. Przydatna może okazać się również wiedza na temat REST API i GraphQL.

Czego potrzebujesz?

• Strony WWW opartej o WordPressa, z którą będziesz się integrować.
• Zainstalowanych wtyczek Advanced Custom Fields i ACF to REST API.
• Zainstalowanego Node.js i terminala (konsoli).
• Edytora kodu. Ja korzystam z WebStorm, ale możesz wybrać dowolny edytor. Jeżeli nie masz własnych preferencji, możesz skorzystać z darmowego Visual Code Studio.

Czego się nauczysz?

Dzięki niniejszemu poradnikowi dowiesz się, czym jest headless CMS oraz JAMstack. Poznasz wady i zalety headless CMS oraz zbudujesz swój pierwszy JAMstackowy blog korzystając z WordPressa jako backendu. W poradniku nie będą poruszane zagadnienia związane z CSS i HTML.

WordPress jako headless CMS

WordPressa możemy zaliczać do headless CMS dopiero od wersji 4.7. Wtedy dodane zostało REST API, które jest niezbędne do stworzenia architektury headless.

WordPress REST API po instalacji WordPressa jest domyślnie włączone. Żeby zobaczyć, co zwraca API, wystarczy otworzyć dowolny endpoint, np. twoja-strona.pl/wp-json/wp/v2/posts. Wyświetlone dane to JSON z wpisami w Twoim WordPressie.

Dodanie do WordPress REST API pozwoliło jego twórcom wykorzystać architekturę headless na potrzeby samego CMSa. W wersji 5.0 edytor WYSIWYG Gutenberg został napisany w React.js i wykorzystuje API. Przykład ten pokazuje, że headless CMSy możemy wykorzystywać nie tylko do budowy stron WWW, ale też korzystać z części danych do rozszerzenia już istniejących projektów.

Zalety headless CMS

Dzięki architekturze oddzielamy w całości PHPowy kod CMSa od warstwy prezentacji umożliwiając, np. skorzystanie z dowolnego frameworka JavaScript do stworzenia strony. WordPress jako backend sprawdzi się też jako źródło danych nie tylko dla strony WWW, ale też, np. dla aplikacji mobilnej czy współdzielenia naszych treści z innymi stronami w formie widgetów. Rozdzielenie backendu i frontendu będzie też miało pozytywny wpływ na bezpieczeństwo naszego projektu oraz jego skalowalność w rozproszonej infrastrukturze.

Wady headless CMS

Niestety headless CMS to nie tylko same pozytywy. Korzystając z REST API dostajesz dane pozbawione kontekstu wizualnego. W przypadku WordPressa utracisz możliwość korzystania z wtyczek typu visual builder czy samego Gutenberga. Generalnie możemy założyć, że wszystkie wtyczki, które działają poza kokpitem WordPressa staną się bezwartościowe. Działać powinny natomiast wszystkie wtyczki rozszerzające możliwości tworzenia i edytowania treści jak na przykład Advanced Custom Fields.

Wykorzystanie JAMstack

JAMstack to idealne dopełnienie headless CMS, dlatego w ramach tego poradnika stworzysz JAMstackowego bloga przy użyciu Gridsome.

JAMstack jest architekturą, która bazuje na JavaScript po stronie klienta, reużywalnym API i wstępnie wyrenderowanym Markupie. Źródłem danych dla JAMstackowych stron mogą być, np. headless CMS, pliki Markdown czy tabele AirTable. Architektura ta pozwala na tworzenie szybszych i bezpieczniejszych stron.

Gridsome to JAMstackowy framework dla Vue.js. Umożliwia szybkie tworzenie statycznie generowanych stron WWW. W poradniku korzystam z Vue.js. Jeżeli React.js jest Ci bliższy, możesz skorzystać z Gatsby. Oba narzędzia działają w zbliżony sposób, różni je tylko framework JavaScript, w którym programujesz. Rozwiązań jest wiele, wspomniane dwa mają dobrą dokumentację i dużą społeczność, co może być pomocne w razie problemów.

Krok 0 – instalacja Gridsome CLI

Przed rozpoczęcie pracy z Gridsome musisz zainstalować Gridsome CLI (ang. command-line interface). Otwórz terminal i wpisz polecenie:

$ npm install --global @gridsome/cli

Po zainstalowaniu CLI sprawdź, czy wszystko przebiegło poprawnie wpisując polecenie:

$ gridsome --version

W terminalu powinna zostać wyświetlona aktualna wersja CLI, np.:

@gridsome/cli v0.3.4

Krok 1 – nowy projekt w Gridsome

Dzięki narzędziom CLI dla Gridsome jesteś w stanie w prosty sposób stworzyć nowy projekt. Otwórz terminal i wprowadź polecenie:

$ gridsome create my-gridsome-site

W efekcie uzyskasz folder my-gridsome-site z gotowym do uruchomienia projektem. Po utworzeniu projektu, możesz uruchomić lokalny serwer Gridsome wpisując w terminalu komendę:

$ gridsome develop

Serwer po uruchomieniu będzie dostępny pod adresem URL localhost:8080. Wprowadź go w przeglądarce, a po zalogowaniu zobaczysz stronę główną swojego bloga.

Struktura projektu

Dzięki poleceniu $ gridsome create utworzony został folder zawierający kompletną strukturę projektu.

Najważniejsze foldery znajdziesz wewnątrz folderu src (ang. source code). Pierwsza rzecz, na którą warto zwrócić uwagę, to pliki README.md w podfolderach. Zawierają one krótki opis odpowiedzialności danego folderu wraz z linkiem do dokumentacji.

Krok 2 – integracja z WordPressem

Utworzony projekt nie posiada obecnie żadnego backendu. Możesz jedynie tworzyć nowe komponenty i budować statyczne podstrony. Gridsome to framework, który umożliwia integrację danych z różnych źródeł w tym WordPress REST API. W celu instalacji integracji z WordPressem otwórz terminal i wprowadź polecenie:

$ npm install @gridsome/source-wordpress

Zainstalowanie wtyczki nie wystarczy. Musisz ją jeszcze skonfigurować. W celu konfiguracji wtyczki source-wordpress, znajdź w folderze głównym plik gridsome.config.js i otwórz go przy użyciu edytora kodu.

W pliku gridsome.config.js odszukaj definicję plugins i dodaj ustawienia source-wordpress:

plugins: [
    {
      use: '@gridsome/source-wordpress',
      options: {
        baseUrl: 'ADRES_URL',
      }
    }
],

W polu baseUrl podaj adres, pod którym dostępny jest Twój WordPress. Na potrzeby poradnika skorzystam z WordPressa dhosting.pl/pomoc/pomoc. Dodatkowe opcje pluginu source-wordpress znajdziesz na tej stronie.

Krok 3 – dodawanie listy wpisów na stronie głównej

Gridsome do obsługi danych z API korzysta z języka zapytań GraphQL. Jeżeli widzisz tę nazwę pierwszy raz, nie przejmuj się. W dalszej części poradnika dowiesz się, czym jest GraphQL.

W celu wyświetlenia listy wpisów na stronie głównej otwórz plik Index.vue, który znajdziesz w folderze src/pages i podmień jego zawartość na tę widoczną poniżej:

<template>
 <div>
   <div v-for="edge in $page.posts.edges" :key="edge.node.id">
     <h2>{{ edge.node.title }}</h2>
     <div v-html="edge.node.excerpt"></div>
   </div>
 </div>
</template>

<page-query>
query {
 posts: allWordPressPost {
   edges {
     node {
       id
       title
       excerpt
     }
   }
 }
}
</page-query>

Warto zwrócić uwagę na tag <page-query>. Wewnątrz tego tagu znajduje się zapytanie GraphQLowe, które pobiera dane zebrane z WordPress REST API. Wewnątrz node definiujesz, które elementy wpisów Cię interesują. W tym przypadku jest to id, tytuł i fragment.

Krok 4 – dodawanie widoku pojedynczego wpisu

Mając dostęp do listy wpisów, możesz zająć się obsługą pojedynczego wpisu. W tym celu otwórz ponownie plik gridsome.config.js i dodaj w nim opcję templates:

templates: {
  WordPressPost: '/:slug'
}

Dla dhosting.pl/pomoc/pomoc będzie to po prostu slug. Jeżeli Twój adres pojedynczego wpisu zawiera więcej pól niż slug, musisz je uwzględnić w ustawieniach, np.:

templates: {
  WordPressPost: '/:year/:slug'
}

Otwórz plik Index.vue, który znajdziesz w folderze src/pages i dodaj do zapytania parametr path:

<page-query>
query {
 posts: allWordPressPost {
   edges {
     node {
       id
       title
       excerpt
       path
     }
   }
 }
}
</page-query>

Wykorzystaj parametr path do przekształcenia nagłówka <h2> w link:

<h2>
 <g-link :to="edge.node.path">{{ edge.node.title }}</g-link>
</h2>

W folderze src/templates utwórz plik WordPressPost.vue. Nazwa musi być zgodna z template utworzonym w pliku gridsome.config.js:

<template>
 <div>
   <h1>{{$page.post.title}}</h1>
   <div v-html="$page.post.content"></div>
 </div>
</template>

<page-query>
query ($id: ID!) {
 post: wordPressPost(id: $id) {
   title
   content
 }
}
</page-query>

W efekcie otrzymasz stronę wpis, np. „Jak założyć bloga? Kompletny przewodnik instalacji WordPressa dla początkujących”.

Krok 5 – integracja z Advanced Custom Fields

Jeżeli masz styczność z WordPressem, to prawdopodobnie znasz wtyczkę Advanced Custom Fields. Umożliwia ona dodawanie dodatkowych pól do stron, wpisów, kategorii, a nawet menu. W przypadku headless ta wtyczka również będzie bardzo przydatna.

Niestety Advanced Custom Fields nie integruje się z WordPress REST API. Możesz to naprawić korzystając z wtyczki ACF to REST API. Po zainstalowaniu wtyczki w WordPressie pola ACF powinny być dostępne w Gridsome.

Dodatkowo, w celu optymalizacji, Gridsome zaleca dodanie filtra w WordPressie, który z endpointów AFC będzie zwracał tylko post_type i id.

add_filter( 'acf/format_value', function ( $value ) {
  if ( $value instanceof WP_Post ) {
    return [
      'post_type' => $value->post_type,
      'id'        => $value->ID,
    ];
  }

  return $value;
}, 100 );

Krok 6 – zapytania w GraphQL

Gridsome integruje się z WordPress REST API, a następnie pozwala programiście obsługiwać pozyskane dane przy użyciu GraphQL. GraphQL to język zapytań, który pozwala w jednym zapytaniu zwrócić wszystkie potrzebne programiście informacje, o czym zapewne przekonały Cię kroki 3 i 4.

Jeżeli masz już doświadczenie z WordPress REST API, to wiesz, że pozyskanie informacji o wpisie, jego kategorii, danych autora i miniaturce, może wymagać kilku zapytań. W przypadku GraphQL wystarczy określić, co chcesz uzyskać i jakie dane Cię interesują, żeby następnie je otrzymać. Tak samo jak ma to miejsce z listą wpisów z kroku 3.

Gridsome wraz z serwerem developerskim uruchamia także narzędzie dla GraphQL ułatwiające tworzenie i testowanie zapytań. Narzędzie dostępne jest pod adresem:
http://localhost:8080/___explore.

Krok 7 – publikacja

Przed opublikowaniem strony musisz zbudować swój projekt. W tym celu w terminalu wpisz polecenie:

$ gridsome build

W efekcie w projekcie powinien pojawić się folder dist zawierający statyczne pliki ze stroną WWW gotową do publikacji.

Zaletą plików statycznych jest możliwość opublikowania ich na dowolnym serwerze oraz skorzystania z takich usług jak, np. GitHub Pages.

Wadą naszego bloga jest to, że z każdym nowym wpisem konieczne jest uruchomienie polecenia build. Można to zrobić ręcznie lub wykorzystać takie narzędzia jak, np. GitHub Actions i wtyczkę WP Webhooks do zautomatyzowania tego procesu.

Podsumowanie

Headless CMS to rozwiązanie, które powinno zainteresować każdego programistę frontendu. Umożliwia zarówno tworzenie zaawansowanych stron internetowych w architekturze JAMstack jak i ponowne użycie danych z CMSa na innych platformach końcowych jak, np. aplikacje mobilne.

Mam nadzieję, że znając wady i zalety Headless CMSa zechcesz wykorzystać go w swoim następnym projekcie. Pamiętaj, że blog zaprezentowany w powyższym poradniku to tylko ułamek możliwości, jakie niesie za sobą architektura headless oraz framework Gridsome.

Autor artykułu: Przemysław Spaczek

Senior Frontend Developer – obecnie tworzy zaawansowane strony WWW i aplikacje w Vue.js. W wybranych projektach nadal z sentymentem sięga po WordPress jako backend, głównie jako headless CMS. Chętnie dzieli się swoją wiedzą w internecie i na meetupach.

• GitHub
• LinkedIn