Umiesz już budować cząstki. Ostatni krok to zrobienie z nich własnego szablonu Gantry 5, czyli takiego, który instaluje się jedną paczką i nie zależy od niczyjego pakietu rozszerzeń. Pokażę to na przykładzie szablonu PP Clean, którego używaliśmy w całym kursie: powstał dokładnie tą drogą, którą tu opisuję, razem z błędami, na które po drodze wpadłem.
Po co własny szablon, skoro jest darmowy Helium
Powodów jest kilka, ale jeden jest ważniejszy od pozostałych.
Kontrola nad zależnościami. Typowy darmowy szablon Gantry z ciekawymi cząstkami wymaga osobnego pakietu od innego producenta. Dopóki pakiet istnieje i jest darmowy, wszystko działa. Kiedy zniknie, zmieni zasady albo przestanie być aktualizowany, strona rozjeżdża się bez ostrzeżenia, a Ty nie masz do kogo pójść. Pierwsza wersja tego kursu opierała się na szablonie, który zniknął z sieci, więc mówię to z doświadczenia.
Poza tym własny szablon daje trzy praktyczne rzeczy: instalujesz go u klienta jedną paczką zamiast składać z pięciu, aktualizujesz w jednym miejscu, a wygląd jest Twój, nie cudzy z podmienionymi kolorami.
Z czego składa się szablon Gantry 5
Szablon to katalog w templates z kilkunastoma podkatalogami. Warto znać przeznaczenie tych, które będziesz ruszać:
- templateDetails.xml: wizytówka dla Joomli. Nazwa, wersja, autor, lista katalogów do skopiowania przy instalacji.
- gantry/theme.yaml: wizytówka dla Gantry. Nazwa wyświetlana, wersja, lista arkuszy do skompilowania.
- gantry/presets.yaml: gotowe zestawy kolorów.
- blueprints/styles/: definicje pól w zakładce Styles, czyli to, co użytkownik może klikać.
- particles/: cząstki wbudowane w szablon.
- scss/: style, kompilowane przez Gantry przy każdej zmianie ustawień.
- layouts/: gotowe układy sekcji.
- install/: co ma powstać przy instalacji, czyli zarysy i przykładowe menu.
Fork, nie pisanie od zera
Szablonu Gantry nie pisze się od pustego katalogu. Bierze się Helium, czyli szablon referencyjny twórców frameworka, i przerabia na swój. Helium jest na licencji GPL, więc wolno to robić, pod jednym warunkiem, do którego wrócę na końcu.
Skopiuj katalog templates/g5_helium w bezpieczne miejsce poza Joomlą, najlepiej do katalogu, który trzymasz w systemie kontroli wersji. Będzie to Twój szablon.
Czego nie kopiować
- custom/: to lokalna konfiguracja konkretnej instalacji, nie część szablonu.
- fonts/: kroje Helium i tak wymienimy na własne.
- MD5SUMS: plik kontrolny Gantry, w Twojej dystrybucji zbędny.
Przemianowanie i pierwsza pułapka
Trzeba zamienić wszystkie wystąpienia nazwy Helium na własną. Dotyczy to nazw plików i katalogów w scss, plików językowych oraz zawartości kilkudziesięciu plików.
Kuszące jest zrobienie tego jedną masową podmianą tekstu i tak właśnie zrobiłem. Efekt był taki, że instalacja przestała działać, a Joomla pokazywała tylko komunikat „Unable to install extension", bez żadnego wpisu w logach.
Przyczyna: mój szablon nazywa się „PP Clean", z odstępem w środku. Masowa podmiana weszła w nazwę klasy PHP w pliku instalatora i zrobiła z niej nazwę z odstępem, czyli błąd składni.
Reguła na przyszłość: po każdym masowym przemianowaniu szablonu przepuść wszystkie pliki PHP przez sprawdzanie składni. W wierszu poleceń robi to php -l nazwa_pliku.php. Zajmuje sekundę i oszczędza pół godziny szukania po omacku.
Dlatego bezpieczniej podmieniać osobno: najpierw nazwę techniczną, czyli identyfikator bez odstępów, potem dopiero nazwę wyświetlaną.
Wizytówka szablonu
W templateDetails.xml ustaw swoje dane: nazwę, wersję 1.0.0, datę utworzenia, autora, adres i prawa autorskie.
Blok, który trzeba usunąć
Na końcu pliku siedzi sekcja updateservers wskazująca na serwer aktualizacji Gantry. Zostawiona sprawi, że Joomla zacznie proponować „aktualizację" Twojego szablonu plikami Helium. Zgoda na taką aktualizację nadpisuje Twoją pracę.
Usuń tę sekcję w całości. To samo dotyczy wpisu z adresem serwera aktualizacji w pliku theme.yaml.
Lista plików
Sekcja files wymienia katalogi i pliki, które Joomla ma skopiować przy instalacji. Jeśli dodasz nowy katalog, na przykład css z arkuszem frameworka, musisz dopisać go do tej listy. Inaczej instalacja przejdzie bez błędu, a katalogu na serwerze nie będzie.
Krój pisma, czyli miejsce, w którym wykłada się połowa szablonów
Polskie znaki diakrytyczne nie należą do podstawowego zestawu znaków łacińskich. Siedzą w rozszerzeniu, które w serwisach z krojami nazywa się latin-ext. Krój bez tego rozszerzenia wyświetli „Sprz", potem podstawi zastępczy krój na literę „ą" i wróci do swojego na „tanie". W jednym słowie zobaczysz dwa różne pisma.
Dlatego przy doborze kroju sprawdzaj dwie rzeczy: czy ma zestaw latin-ext i jak wygląda w nim napisane po polsku zdanie ze wszystkimi znakami: ą, ć, ę, ł, ń, ó, ś, ź, ż.
Krój lokalnie, nie z zewnętrznego serwera
Typowe rozwiązanie to wczytywanie kroju z serwerów dostawcy przy każdym wejściu na stronę. Dla własnego szablonu lepiej wgrać pliki do katalogu fonts i podać je we własnej regule w arkuszu stylów.
Zyskujesz trzy rzeczy: jedną zależność zewnętrzną mniej, brak żądania do obcego serwera przy każdym wejściu, czyli mniej pracy przy polityce prywatności, oraz szybsze wyświetlenie pierwszego tekstu.
Jeśli używasz kroju zmiennego, jeden plik obsłuży cały zakres grubości. W PP Clean dwa pliki, podstawowy i rozszerzony o polskie znaki, ważą razem 40 kB na grubości od cienkiej do bardzo grubej.
Pułapka kompilatora
Kompilator arkuszy w Gantry potrafi potraktować zapis funkcji CSS jako działanie arytmetyczne i przerwać kompilację. Dotyczy to zapisów, w których obok siebie stoją różne jednostki, na przykład przy płynnym skalowaniu wielkości pisma, oraz zakresów znaków przy definiowaniu kroju.
Ratunek jest prosty: owinąć taką wartość w funkcję unquote, która każe kompilatorowi przepuścić ją bez liczenia.
Framework CSS jako atom, nie jako import w każdej cząstce
Jeśli budujesz na frameworku, na przykład UIkicie, wgraj jego pliki do katalogów css i js szablonu, z przypiętą wersją. Nie z zewnętrznego serwera, z tego samego powodu co krój.
Do wczytania użyj atomu, czyli cząstki, która nic nie rysuje, tylko dokłada coś do strony. Zaletą jest to, że framework wczytuje się raz, niezależnie od tego, ile cząstek stoi na stronie.
Kolejność ma znaczenie
Arkusz frameworka musi wejść przed skompilowanym arkuszem szablonu. Odwrotna kolejność sprawia, że to framework wygrywa z Twoimi regułami i zastanawiasz się, czemu ustawiony kolor nie działa.
Gantry wstawia arkusz szablonu z priorytetem 10, a wyższy priorytet znaczy „wcześniej". Arkusz frameworka daj więc z priorytetem 11. Skrypty mogą zostać na 10 i warto dodać im atrybut defer, żeby nie blokowały wyświetlania strony.
Sprawdzenie zajmuje chwilę: otwórz źródło strony i zobacz, który znacznik arkusza stoi wyżej.
Styl należy do szablonu
Cząstka ma wypuszczać znaczniki i klasy, a wygląd ma stać w arkuszu szablonu. Pisałem o tym przy pliku twig, ale przy budowie całego szablonu ta zasada zaczyna się opłacać naprawdę: zmiana wyglądu karty to jedno miejsce, nie osiem plików cząstek.
Nadaj własnym klasom krótki przedrostek, na przykład trzy litery od nazwy szablonu. Dzięki temu w kodzie od razu widać, co jest Twoje, a co pochodzi z frameworka. Brak takiego rozdzielenia mści się później: w cząstkach, które przerabiałem, znalazłem klasę z przedrostkiem szablonu sprzed dwóch lat, dawno usuniętego z serwisu, do którego kod wciąż się odwoływał.
Kolory z ustawień, nie z kodu
Kolory ustawione w zakładce Styles trafiają do arkusza jako zmienne. Przepisz je raz na zmienne CSS w regule dla całego dokumentu, a potem odwołuj się do nich w cząstkach. Zmiana koloru w panelu zadziała wtedy wszędzie naraz, a cząstka nie musi wiedzieć, skąd ten kolor pochodzi.
Pakowanie szablonu
Joomla instaluje rozszerzenia z archiwum zip, w którym plik templateDetails.xml leży w katalogu głównym.
Nie pakuj przez wbudowane narzędzie PowerShella. Zapisuje ono ścieżki wewnątrz archiwum z odwrotnym ukośnikiem, a instalator Joomli takiego archiwum nie przyjmuje. To błąd trudny do rozpoznania, bo archiwum otwiera się normalnie w każdym programie do rozpakowywania.
Użyj programu pakującego, na przykład 7-Zip, albo napisz krótki skrypt w PHP korzystający z klasy ZipArchive, która zawsze zapisuje ukośnik zwykły. Skrypt ma tę przewagę, że przy okazji pominie katalogi, których w paczce być nie powinno, czyli lokalną konfigurację i skompilowane arkusze.
Sprawdzenie na czystej instalacji
Ostatni krok jest tym, który najczęściej się pomija, a wyłapuje najwięcej: zainstaluj swoją paczkę na świeżej Joomli, na której nie ma nic poza Gantry.
Szukasz odpowiedzi na jedno pytanie: czy szablon działa, kiedy nie ma obok niego niczego, co mogłeś nieświadomie pożyczyć. Jeśli na Twojej instalacji stoi jeszcze inny szablon z własnym frameworkiem, style mogą przychodzić stamtąd, a Ty tego nie zauważysz.
Przy okazji sprawdź listę tego, co strona faktycznie pobiera. Wszystko powinno pochodzić z katalogu Twojego szablonu, z rdzenia Joomli albo z rdzenia Gantry. Każdy adres spoza tych trzech miejsc to zależność, którą albo świadomie akceptujesz, albo usuwasz.
Licencja, czyli warunek z początku artykułu
Helium jest na licencji GPL i fork jest w pełni dozwolony, ale GPL wymaga zachowania informacji o prawach autorskich w plikach źródłowych. Nagłówki z nazwiskiem oryginalnego autora zostają tam, gdzie są, a swoje prawa dopisujesz obok.
W wizytówce szablonu wypada napisać wprost, że powstał na bazie Helium. To nie tylko wymóg formalny, ale też uczciwość wobec kogoś, kto wykonał kawał pracy, dzięki której Twój szablon powstał w kilka godzin zamiast w kilka tygodni.
Co dalej
Masz szablon, który instaluje się jedną paczką, nie zależy od cudzych pakietów i wygląda tak, jak zaprojektowałeś. Od tego momentu każda kolejna strona dla klienta zaczyna się od gotowego fundamentu, a nie od układania klocków od nowa.
Wracając do początku kursu: dokładnie tak powstał szablon, na którym budowaliśmy stronę. Cały spis treści znajdziesz w artykule otwierającym.