Umbraco 18 jest innym wydaniem niż 14 czy 16. Nie przebudowuje Backoffice i nie zmienia technologicznych fundamentów CMS-a. Zamiast tego wprowadza jedną dużą funkcję, która rozwiązuje problem znany z wielu rzeczywistych projektów: treści wielokrotnego użytku, która nie jest stroną i nie powinna znajdować się w drzewie Content.

Odpowiedzią są Library i Elements.

Do tego dochodzą zmiany istotne dla projektów headless, między innymi generowanie typowanych schematów OpenAPI dla Delivery API, oraz usprawnienia rozwijane wcześniej w linii Umbraco 17.

Warto jednak pamiętać o jednej rzeczy: Umbraco 18 jest wydaniem STS, podczas gdy Umbraco 17 pozostaje wersją LTS. Wybór najnowszego numeru nie zawsze będzie więc automatycznie najlepszą decyzją.

Library – nowe miejsce na treści wielokrotnego użytku

W wielu projektach Umbraco można znaleźć w drzewie Content folder o nazwie „Global”, „Shared”, „Settings” albo „Reusable content”.

W środku znajdują się elementy takie jak:

• globalne CTA,
• bannery promocyjne,
• dane kontaktowe,
• fragmenty treści wykorzystywane w kilku miejscach,
• informacje wspólne dla wielu podstron.

Technicznie takie rozwiązanie działa, ale ma istotną wadę: wykorzystujemy dokumenty do przechowywania czegoś, co w rzeczywistości nie jest stroną.

Umbraco 18 wprowadza dla takich danych dedykowane miejsce — Library.

Library jest nową sekcją Backoffice przeznaczoną dla treści, które mają istnieć niezależnie od drzewa stron.

Pierwszym typem treści obsługiwanym przez Library są Elements.

Elements – Element Type staje się rzeczywistą treścią

Element Types znamy z Umbraco od dawna. Do tej pory służyły przede wszystkim jako struktura elementów wykorzystywanych przez Block List czy Block Grid.

Umbraco 18 rozszerza ten model.

Element Type może teraz zostać udostępniony w Library. Redaktor może następnie utworzyć na jego podstawie konkretny Element i zarządzać nim niezależnie od dokumentów.

Schemat jest prosty:

Element Type → Library → Element → wykorzystanie w treści

Dzięki temu możemy przykładowo utworzyć Element Type:

Promotion

z właściwościami:

Title
Description
Image
Link

a następnie pozwolić redaktorom tworzyć konkretne promocje w Library.

Co ważne, Element nie posiada własnego URL-a. Nie udaje więc strony tylko dlatego, że potrzebujemy gdzieś przechować jego dane.

Element Picker – wybieramy zamiast kopiować

Drugim ważnym elementem nowego mechanizmu jest Element Picker.

Pozwala on wskazać istniejący Element i wykorzystać go w innym miejscu treści.

To niewielka zmiana w interfejsie, ale duża zmiana w modelowaniu CMS-a.

Wyobraźmy sobie komunikat:

Darmowa dostawa dla zamówień powyżej 300 zł

który występuje na kilkunastu podstronach.

Bez współdzielonego modelu redaktor może skończyć z wieloma kopiami tej samej treści. Zmiana komunikatu oznacza wtedy odnalezienie każdego wystąpienia.

Elements tworzą fundament pod model:

utwórz raz → używaj wielokrotnie → zarządzaj centralnie

W Umbraco 18 należy jednak traktować to jako pierwszy etap tej funkcjonalności. Pełna integracja Elements z Block Editors została zaplanowana na kolejne wydanie.

Elements nie są „uboższymi dokumentami”

Ważną cechą nowego rozwiązania jest to, że Elements są traktowane jak pełnoprawna treść CMS-a.

Otrzymujemy mechanizmy znane z pracy z dokumentami, między innymi:

• publikowanie,
• planowanie publikacji,
• rollback,
• uprawnienia,
• historię i audyt,
• walidację,
• kosz,
• wyszukiwanie,
• śledzenie referencji.

To ważne szczególnie w większych wdrożeniach.

Własny „global content repository” napisany na potrzeby projektu często zaczyna jako kilka prostych rekordów. Z czasem pojawiają się pytania o uprawnienia, historię zmian, publikację czy zależności.

W Umbraco 18 coraz mniej powodów przemawia za budowaniem takiego mechanizmu samodzielnie.

Źródło: Opracowanie własne.

Co zmienia się z perspektywy developera?

Najważniejsza zmiana nie polega na poznaniu kolejnego API.

Zmienia się sposób, w jaki możemy modelować architekturę treści.

Do tej pory często zadawaliśmy pytanie:

„Gdzie w drzewie Content umieścić tę informację?”

W Umbraco 18 warto najpierw zapytać:

„Czy ta informacja w ogóle jest dokumentem?”

Jeżeli obiekt:

• nie ma własnego URL-a,
• nie potrzebuje template’u,
• powinien być współdzielony,
• posiada własny cykl publikacji,
• jest zarządzany przez redaktora,

to Element może być bardziej naturalnym modelem niż dokument.

To pozornie drobna różnica, ale w dużych projektach prowadzi do znacznie czystszej struktury treści.

Delivery API – typowane schematy OpenAPI

Druga istotna technicznie zmiana w Umbraco 18 dotyczy Delivery API.

Umbraco może generować schematy OpenAPI dla poszczególnych typów treści.

Ma to szczególne znaczenie w architekturze headless, gdzie frontend jest oddzielną aplikacją korzystającą z CMS-a przez API.

Wcześniej odpowiedź Delivery API mogła być dla generatora klienta stosunkowo ogólna. Typowane schematy pozwalają dokładniej opisać strukturę zwracanej treści.

Jeżeli mamy typ:

Article

z polami:

title
lead
publicationDate

klient API może dysponować znacznie dokładniejszą informacją o strukturze danych.

Daje to lepszą podstawę do generowania klientów dla TypeScript, C# czy innych języków.

W praktyce oznacza to:

• lepszy autocomplete,
• wcześniejsze wykrywanie błędów,
• mniej ręcznie tworzonych modeli DTO,
• czytelniejszy kontrakt pomiędzy CMS-em a frontendem.

Źródło: Opracowanie własne.

Zmiana z Swashbuckle na Microsoft.AspNetCore.OpenApi

Umbraco 18 zmienia również techniczny fundament generowania dokumentacji OpenAPI.

Swashbuckle jest zastępowany przez Microsoft.AspNetCore.OpenApi.

Dla większości standardowych projektów nie będzie to zmiana widoczna dla użytkownika. Własne rozwiązania ingerujące w generowanie OpenAPI wymagają jednak sprawdzenia podczas aktualizacji.

To dobry przykład charakteru wersji 18: część zmian nie jest widoczna w Backoffice, ale porządkuje techniczne fundamenty platformy i zbliża ją do aktualnego stosu ASP.NET Core.

Umbraco 18 korzysta z fundamentu wersji 17

Nie wszystkie usprawnienia dostępne w Umbraco 18 powstały bezpośrednio w tej wersji.

Umbraco rozwija funkcje również w kolejnych minor releases, dlatego 18 dziedziczy usprawnienia wprowadzone wcześniej w linii 17.x.

Dotyczą one między innymi wydajności, cache’owania, Backoffice i operacyjności aplikacji.

To ważne przy porównywaniu 17 i 18.

Nie należy patrzeć na Umbraco 18 jak na ogromny pakiet funkcji niedostępnych w 17. Wiele usprawnień trafia również do aktualnej wersji LTS.

Najbardziej charakterystyczną nowością wersji 18 pozostają Library i Elements.

Migracja z Umbraco 17 do 18

Technologicznie przejście z Umbraco 17 do 18 jest znacznie mniej radykalne niż historyczne migracje takie jak 13 → 14.

Backoffice, Extension API, Tiptap i podstawowy model platformy są już znane.

Przed aktualizacją warto jednak sprawdzić:

• breaking changes,
• kompatybilność pakietów,
• własne rozszerzenia Backoffice,
• konfigurację OpenAPI,
• integracje korzystające z Delivery API,
• testy automatyczne i pipeline CI/CD.

Jeżeli projekt korzysta z niestandardowej konfiguracji Swaggera lub OpenAPI, temu obszarowi warto poświęcić szczególną uwagę.

Źródło: Opracowanie własne.

Umbraco 17 czy Umbraco 18?

To jedno z ważniejszych pytań dotyczących tej wersji.

Umbraco 17 jest wydaniem LTS. Umbraco 18 jest wydaniem STS.

Dlatego nie rekomendowalibyśmy automatycznej migracji każdego projektu do wersji 18 tylko dlatego, że jest nowsza.

Umbraco 17 będzie naturalnym wyborem, gdy:

• projekt ma działać przez wiele lat,
• priorytetem jest długi okres wsparcia,
• Library i Elements nie są obecnie potrzebne,
• chcemy ograniczyć częstotliwość major upgrades.

Umbraco 18 ma szczególny sens, gdy:

• chcemy wykorzystać Elements już teraz,
• projekt intensywnie korzysta z Delivery API,
• jesteśmy gotowi na krótszy cykl aktualizacji,
• rozwijamy produkt, który będzie regularnie przechodził na kolejne wersje Umbraco.
  

Nasza rekomendacja

Umbraco 18 nie jest wydaniem, które trzeba instalować tylko dlatego, że ma najwyższy numer.

I to akurat dobra wiadomość.

Umbraco 17 pozostaje solidną wersją LTS, a wiele usprawnień platformy jest rozwijanych również właśnie tam.

Umbraco 18 jest ciekawsze z innego powodu: wprowadza nowy element modelu treści, który może zmienić sposób projektowania większych serwisów.

Library i Elements rozwiązują problem, z którym zespoły Umbraco radziły sobie dotychczas na wiele różnych sposobów.

Jeżeli rozpoczynamy nowy projekt, warto już na etapie modelowania treści rozdzielić trzy pojęcia:

Document – strona lub treść routowalna.

Block – fragment kompozycji strony.

Element – niezależna, nieroutowalna treść przeznaczona do ponownego wykorzystania.

Takie rozdzielenie daje znacznie czytelniejszą architekturę i ogranicza liczbę projektowych workaroundów.

Podsumowanie

Umbraco 18 jest stosunkowo niewielkim major release’em, ale wprowadza funkcję o dużym potencjale architektonicznym.

Najważniejsze zmiany to:

• nowa sekcja Library,
• Elements jako pełnoprawna treść poza drzewem dokumentów,
• Element Picker,
• zarządzanie cyklem życia Elements,
• typowane schematy OpenAPI dla Delivery API,
• przejście z Swashbuckle na Microsoft.AspNetCore.OpenApi,
• usprawnienia odziedziczone z linii Umbraco 17.

Najciekawszą zmianą nie jest jednak pojedyncze API czy komponent Backoffice.

Jest nią możliwość powiedzenia wreszcie:

„Ta treść nie jest stroną — i nie musimy udawać, że nią jest.”