W naszym samouczku "Jak stworzyć stronę internetową za darmo" korzystamy z CMS Joomla oraz posługujemy się frameworkiem Gantry 5. Jednym z głównych celów przyświecających opracowaniu Gantry 5 było umożliwienie osobom niebędącym programistami wykonywania większej ilości zadań bez konieczności otwierania edytora kodu lub bezpośredniej modyfikacji plików.
Gantry 5 jest naprawdę łatwy w użyciu. Posiada funkcję przeciągnij i upuść, która umożliwia drastyczną zmianę układu witryny w ciągu kilku sekund, bez konieczności dotykania klawiatury.
Czym są kontury/zarysy, cząsteczki, atomy?
Krótki przegląd powszechnie używanych terminów związanych z Gantry 5.
| Termin | Opis |
|---|---|
| Zarys | Konfigurowalny styl używany w jednym lub kilku obszarach witryny. Służy jako kontener, w którym ustawiany jest styl, ustawienia i układ strony. Jest to odpowiednik szablonu. W ten sposób Gantry układa różne elementy na stronie. |
| Cząstka | Typowo mały blok danych używany na froncie. Działa bardzo podobnie do widżetu/modułu, ale można go łatwo skonfigurować w Gantry 5 Administrator. |
| Atom | Typ cząsteczki zawierający nierenderowane dane, taki jak niestandardowe skrypty (JS, CSS itp.) lub skrypty analityczne do śledzenia ruchu. |
| Jądro | To jest własny front-end framework Gantry 5. Jest to bardzo prosty i lekki framework CSS/SCSS-only. |
Zatem do prezentacji treści Gantry 5 używa cząstek/particles.
Podstawowa budowa cząstki i sposób jej instalacji w szablonie.
W naszym przykładzie mamy już zainstalowany atom UIKit od Joomlead więc będziemy bazować na UIKit do budowy naszej cząstki. Domyślnie Joomla posiada wbudowany framework Bootstrap ale ja osobiście wolę UIKit. Jeżeli wolisz korzystaj z bootstrapa. Dodatkowo Gantry 5 posiada własny framework (Nucleus) ale jest on dość minimalistyczny. Więc nic nie stoi na przeszkodzie abyś posługująć się tym poradnikiem utworzył cząstkę uniwersalną, która działa bez dodatkowych zależności.
Zaczynamy od utworzenia dwóch plików dla naszej cząstki. Plik nazwa_cząstki.yaml oraz nazwa_cząstki.html.twig Pierwszy odpowiada za kontrolki na zapleczu, czyli miejsce gdzie wpiszemy/ustawimy nasze treści, które następnie zostaną pobrane i wyświetlone na froncie przez plik nazwa_cząstki.html.twig
YAML to przyjazny dla człowieka język serializacji danych dla wszystkich języków programowania
Twig to nowoczesny silnik szablonów dla PHP
yaml
name: Example
description: Displays a Title, Image, and Text on the front end.
type: particle
form:
fields:
enabled:
type: input.checkbox
label: Enabled
description: Globally enable to the particles.
default: true
title:
type: input.text
label: Title
description: Customize the section title text.
image:
type: input.imagepicker
label: Image
description: Select the main image.
description:
type: textarea.textarea
label: Text / HTML
description: Create or modify your description.
css.class:
type: input.text
label: Class
description: CSS class name for the particle.
Ten YAML składa się z dwóch głównych części. Po pierwsze, nagłówek pliku, który ustawia Nazwę , Opis i Typ . Nazwa to to, co pojawia się w administratorze jako tytuł Particle w panelach Particle Defaults i Layout Manager . Type , czyli Particle, informuje Gantry, że ten plik YAML jest używany do tworzenia Particle.
Druga sekcja ustawia formularze/pola, które pojawiają się w administratorze, a także ustawienia domyślne. Te pola pojawiają się w administratorze i są dostępne dla administratorów witryny. Dają im możliwość wykonywania takich czynności, jak ustawianie niestandardowego tekstu, tytułów i ustawień przełączania.
Pierwszy blok pola (enabled) jest wymagane. Informuje Gantry o umieszczeniu przełącznika na zapleczu, który umożliwia włączanie/wyłączanie Particle.
Reszta pól tutaj, title, image,description, css.class udostępniają pola, dzięki którym admini witryn mogą konfigurować Particle bez konieczności ręcznej edycji plików.
Następny plik, który musisz utworzyć, będzie znajdował się w tym samym katalogu co plik YAML. Zaleca się nadanie mu takiej samej nazwy, jaką nadałeś plikowi YAML, ale w formacie name.html.twig. Zakończenie nazwy pliku na html.twig informuje Gantry, że jest to plik Twig, który jest zasadniczo szablonem pliku. Kontroluje sposób renderowania Particles, określa kod HTML i określa sposób używania zmiennych zdefiniowanych w YAML.
twig
{% extends '@nucleus/partials/particle.html.twig' %}
{% block particle %}
<div class="example_particle {{ particle.css.class }}">
<div align="center">
<img src="{{ url(particle.image) }}" alt="image">
<h2>{{ particle.title }}</h2>
<p>{{ particle.description }}</p>
</div>
</div>
{% endblock %}
To jest oczywiście podstawowa struktura cząstki, którą możemy zobaczyć w dokumentacji Gantry 5. Na jej podstawie zbudujemy Hero Banner, podobny do tego który jest widoczny na mojej stronie głównej.
Do edycji potrzebujemy zatem zdjęcie, nagłówek, krótki opis oraz dwa przyciski CTA. Naszą cząstkę będziemy tworzyć bezpośrednio w szablonie Gantry więc jeżeli nie masz jeszcze zainstalowanego szablonu Gantry 5 musisz to wcześniej zrobić. Oraz tak jak wspomniałem na początku musisz mieć atom UIKit od Joomlead. Następnie utwórz dwa wyżej wymienione pliki (nazwa dowolna) np. herobanner.yaml oraz herobanner.html.twig w lokalizacji templates/g5_helium/custom/particles
Oto nasza struktura plików szablonu po instalacji UIKit oraz naszej cząstki
Zawartość pliku herobanner.yaml
name: Hero Banner
description: Wyświetlaj baner z nagłowkiem oraz dwoma CTA.
type: particle
icon: fa-images
configuration:
caching:
type: static
form:
overrideable: false
fields:
enabled:
type: input.checkbox
label: Enabled
description: Globally enable to the particles.
default: true
image:
type: input.imagepicker
label: Obraz
description: Wybierz obraz.
imageAlt:
type: input.text
label: Tekst alternatywny dla obrazka
description: Dodaj text alternatywny dla obrazka.
title:
type: input.text
label: Tytuł
description: Wpisz tytuł/nagłowek.
description:
type: textarea.textarea
label: Krótki opis
description: Wpisz krótki opis pod nagłówkiem.
separatorL:
type: separator.note
class: alert alert-info
content: "Przycisk po lewej stronie"
buttontextL:
type: input.text
label: Tekst na przycisku
description: Etykieta przycisku.
placeholder: Pokaż więcej
buttonlinkL:
type: input.text
label: Link
description: adres odnośnika.
placeholder: http://
button_link_titleL:
type: input.text
label: Tytuł linku
description: Tytuł linku to atrybut, który dostarcza więcej informacji o linku.
button_aria_labelL:
type: input.text
label: Link aria label
description: Dodanie aria-label do linków jest ważne dla zapewnienia dostępności
buttontargetL:
type: select.selectize
label: Target
description: Otwórz odnośnik w tym samym oknie lub w nowej karcie.
placeholder: "Wybierz..."
default: _self
options:
_self: W tej samej karcie
_blank: Nowe okno
separatorR:
type: separator.note
class: alert alert-info
content: "Przycisk po prawej stronie"
buttontextR:
type: input.text
label: Tekst na przycisku
description: Etykieta przycisku.
placeholder: Pokaż więcej
buttonlinkR:
type: input.text
label: Link
description: adres odnośnika.
placeholder: http://
button_link_titleR:
type: input.text
label: Tytuł linku
description: Tytuł linku to atrybut, który dostarcza więcej informacji.
button_aria_labelR:
type: input.text
label: Link aria label
description: Dodanie aria-label do linków jest ważne dla zapewnienia dostępności
buttontargetR:
type: select.selectize
label: Target
description: Otwórz odnośnik w tym samym oknie lub w nowej karcie.
placeholder: "Wybierz..."
default: _self
options:
_self: W tej samej karcie
_blank: Nowe okno
copyright:
type: separator.note
class: alert alert-success
content: 'Cząstka wykonana w ramach nauki'
Mam nadzieję, że nazwy, których użyłem oraz opisy są zrozumiałe i nie wymagają dodatkowego wyjaśnienia. Kluczową rolę w plikach yaml maja wcięcia. Nie można ich dowolnie modyfikować. Nazwy zakończone dwukropkiem (image: imageAlt: itd.) to nasze zmienne, które będziemy używać w pliku twig do wyświetlania treści.
icon: fa-images czyli ikonka, która jest widoczna przy cząstkach jest ikonką z zestawu darmowego fontawensome który jest ładowany domyślnie przez Joomla. Możesz wybrać dowolną ikonkę z tego zestawu.
Efekt na zapleczu
Aktualnie nasza konfiguracja znajduje się na jednej karci. Podzielmy nasze dane na zakładki. W jednej umieścimy baner z tekstem a w drugiej nasze przyciski. Dzięki temu cząstka będzie bardziej czytelna. W tym celu do naszych pół (fields) dodamy karty (tabs). Jest to pole typu containers.tabs
_tabs:
type: container.tabs
fields:
Następnie każdą zakładkę fields zaczynamy od identyfikatora oraz etykiety pamiętając o wcięciach
_tab_content:
label: Etykieta zakładki
fields:
Kod po wprowadzonych zmianach
name: Hero Banner
description: Wyświetlaj baner z nagłowkiem oraz dwoma CTA.
type: particle
icon: fa-images
configuration:
caching:
type: static
form:
overrideable: false
fields:
enabled:
type: input.checkbox
label: Enabled
description: Globally enable to the particles.
default: true
_tabs:
type: container.tabs
fields:
_tab_content:
label: Baner z nagłowkiem
fields:
image:
type: input.imagepicker
label: Obraz
description: Wybierz obraz.
imageAlt:
type: input.text
label: Tekst alternatywny dla obrazka
description: Dodaj text alternatywny dla obrazka.
title:
type: input.text
label: Tytuł
description: Wpisz tytuł/nagłowek.
description:
type: textarea.textarea
label: Krótki opis
description: Wpisz krótki opis pod nagłówkiem.
_tab_buttons:
label: Przyciski CTA
fields:
separatorL:
type: separator.note
class: alert alert-info
content: "Przycisk po lewej stronie"
buttontextL:
type: input.text
label: Tekst na przycisku
description: Etykieta przycisku.
placeholder: Pokaż więcej
buttonlinkL:
type: input.text
label: Link
description: adres odnośnika.
placeholder: http://
button_link_titleL:
type: input.text
label: Tytuł linku
description: Tytuł linku to atrybut, który dostarcza więcej informacji o linku i dokąd prowadzi.
button_aria_labelL:
type: input.text
label: Link aria label
description: Dodanie aria-label do linków jest ważne dla zapewnienia dostępności
buttontargetL:
type: select.selectize
label: Target
description: Otwórz odnośnik w tym samym oknie lub w nowej karcie.
placeholder: "Wybierz..."
default: _self
options:
_self: W tej samej karcie
_blank: Nowe okno
separatorR:
type: separator.note
class: alert alert-info
content: "Przycisk po prawej stronie"
buttontextR:
type: input.text
label: Tekst na przycisku
description: Etykieta przycisku.
placeholder: Pokaż więcej
buttonlinkR:
type: input.text
label: Link
description: adres odnośnika.
placeholder: http://
button_link_titleR:
type: input.text
label: Tytuł linku
description: Tytuł linku to atrybut, który dostarcza więcej informacji o linku i dokąd prowadzi.
button_aria_labelR:
type: input.text
label: Link aria label
description: Dodanie aria-label do linków jest ważne dla zapewnienia dostępności
buttontargetR:
type: select.selectize
label: Target
description: Otwórz odnośnik w tym samym oknie lub w nowej karcie.
placeholder: "Wybierz..."
default: _self
options:
_self: W tej samej karcie
_blank: Nowe okno
copyright:
type: separator.note
class: alert alert-success
content: "Cząstka wykonana w ramach nauki"
Wynik naszej przeróbki to dwie oddzielne zakładki Baner z nagłówkiem i Przyciski CTA
Wprowadźmy jeszcze jedno udogodnienie. Ponieważ nasze przyciski ogólnie są takie same, są to elementy powtarzalne możemy użyć dynamicznego generowania ich na zapleczu. Służy do tego pole typu collection.list
UWAGA!!! Ważne jest to, że każde pole, które chcesz umieścić w fields musi zaczynać się od kropki ( . ) Zamiast więc wywoływać pole buttontext należałoby użyć .buttontext
button_items:
type: collection.list
array: true
label: Przyciski
overrideable: false
description: Utwórz kolejny element do wyświetlenia.
value: name
ajax: true
fields:
i teraz kiedy mamy przyciski tworzone dynamicznie nie potrzebujemy mieć zapisanych dwóch przycisków jak do tej pory ale wystarczy jeden, który będzie wzorem dla kolejnych. Nasz kod jest krótszy i bardziej czytelny.
name: Hero Banner
description: Wyświetlaj baner z nagłowkiem oraz dwoma CTA.
type: particle
icon: fa-images
configuration:
caching:
type: static
form:
overrideable: false
fields:
enabled:
type: input.checkbox
label: Enabled
description: Globally enable to the particles.
default: true
_tabs:
type: container.tabs
fields:
_tab_content:
label: Baner z nagłowkiem
fields:
image:
type: input.imagepicker
label: Obraz
description: Wybierz obraz.
imageAlt:
type: input.text
label: Tekst alternatywny dla obrazka
description: Dodaj text alternatywny dla obrazka.
title:
type: input.text
label: Tytuł
description: Wpisz tytuł/nagłowek.
description:
type: textarea.textarea
label: Krótki opis
description: Wpisz krótki opis pod nagłówkiem.
_tab_buttons:
label: Przyciski CTA
fields:
label: Przyciski CTA
button_items:
type: collection.list
array: true
label: Przyciski
overrideable: false
description: Utwórz kolejny element do wyświetlenia.
value: name
ajax: true
fields:
.buttontext:
type: input.text
label: Tekst na przycisku
description: Etykieta przycisku.
placeholder: Pokaż więcej
.buttonlink:
type: input.text
label: Link
description: adres odnośnika.
placeholder: http://
.button_link_title:
type: input.text
label: Tytuł linku
description: Tytuł linku to atrybut, który dostarcza więcej informacji o linku i dokąd prowadzi.
.button_aria_label:
type: input.text
label: Link aria label
description: Dodanie aria-label do linków jest ważne dla zapewnienia dostępności
.buttontarget:
type: select.selectize
label: Target
description: Otwórz odnośnik w tym samym oknie lub w nowej karcie.
placeholder: "Wybierz..."
default: _self
options:
_self: W tej samej karcie
_blank: Nowe okno
copyright:
type: separator.note
class: alert alert-success
content: "Cząstka wykonana w ramach nauki"
Zmieniłem tryb zaplecza z ciemnego na jasny ponieważ kiedy tworzę ten poradnik ta wersja Gantry 5.5.20 jest jeszcze w fazie testów i nie działa poprawnie. Cześć tekstów jest nieczytelna.
Tak wygląda cząstka po zmianach (dynamiczne dodawanie przycisków CTA)
W tym momencie mamy już widoczną cząstkę w obszarze administracyjnym Gantry ale poza możliwością ustawienia danych nic się nie dzieje. Treści nie są wyświetlane.
Następny krok, który musimy wykonać to uzupełnienie pliku html.twig. Kontroluje on sposób renderowania Particles, poprzez kod HTML i określa sposób używania zmiennych zdefiniowanych w YAML.