• Artykuł

            

Umbraco CMS - Tworzenie makr XSLT

Udostępnij na: Facebook

Autor: Wojciech Poniatowski

Opublikowano: 2011-10-19

Umbraco ma bardzo duże możliwości dzięki łatwemu rozszerzaniu witryny. To czego nie może osiągnąć przeciętny użytkownik panelu administratora, możliwe jest dla programisty. Makra pozwalają na tworzenie niestandardowej funkcjonalności. W Umbraco można tworzyć makra XSLT oraz makra .NET. Ponadto funkcjonalność witryny może być rozszerzana za pomocą gotowych pakietów.

Artykuł ten jest częścią cyklu artykułów o Umbraco CMS. Dowiesz się z niego:

  • czym są makra XSLT,
  • jak tworzyć marka XSLT,
  • jakie są możliwości makr XSLT,
  • jak wstawiać makro XSLT do szablonu strony.

Wstęp

XSLT (ang. XSLT – Extensible Stylesheet Language Transformations) to w wolnym tłumaczeniu Przekształcenia Rozszerzalnego Języka Arkuszy Stylów. To oparty na XML-u język przekształceń dokumentów XML. W sktócie jest to mieszanka kodu XML, HTML i odwołań do API Umbraco. Za pomocą makr można np. utworzyć menu nawigacyjne do wybranych podstron, pobrać i wyświetlić najnowsze aktualności, wyświetlić elementy sekcji Media.

Tworzenie makra XSLT

Pierwszy sposób dodawania makra XSLT to dodanie nowego pliku w programie WebMatrix. Plik z rozszerzeniem *.xslt należy umieścić w katalogu /xslt (Rys.1.).

Rys. 1. Dodawanie makra XSLT w WebMatrix.

Ale lepszym sposobem jest dodanie nowego makra z poziomu panelu administratora Umbraco. Aby to zrobić, należy przejść do sekcji Developer i dodać nowy element do XSLT Files (Rys. 2.).

Rys. 2. Dodawanie makra XSLT w panelu administratora Umbraco.

Dodanie makra w panelu administratora ma tę zaletę, że automatycznie plik jest wypełniony klikoma elementami. W przypadku WebMatrix, będzie to pusty plik, lub jeśli wybraliśmy jako typ plik XML, będzie on zawierać 1 znacznik XML.

Uruchomienie makra XSLT

Efektem makra XSLT jest wygenerowany kod HTML. Aby uruchomić lub przetestować wyniki makra, należy umieścić specjalny element do szablonu w miejscu, w którym chcemy, aby wygenerowany kod HTML był wyświetlany.

Wystarczy przejść do sekcji Settings, wybrać odpowiedni szablon, ustawić kursor w miejscu, gdzie chcemy umieścić makro, a następnie z paska narzędzi wybrać nazwę makra z listy rozwijanej (Rys. 3.).

Rys. 3. Wstawianie makra do szablonu strony.

Do szablonu zostanie wstawiony kod kontrolki Umbraco, która uruchomi makro (Rys. 4.).

Rys. 4. Kontrolka Umbraco do obsługi makr XSLT.

Na końcu należy uruchomić przeglądarkę i sprawdzić efekt makra.

Elementy makra

Makro XSLT składa się z kilku części. Na początku jest deklaracja XML (ponieważ XSLT jest oparty o strukturę dokumentów XML). Ta część jest zazwyczaj stała i Umbraco samo ją wprowadza. W większości przypadków nie będziesz musił jej zmieniać (Rys.5.).

Rys. 5. Elementy makra XSLT: deklaracja XML.

Następnie znajduje się deklaracja parametrów. Jest to miejsce styku makra i strony, na której makro jest wyświetlane. Domyślnie utworzony jest parametr currentPage, który zawiera wszystkie informacje o stronie (Rys.6.).

Rys. 6. Elementy makra XSLT: parametr currentPage.

Na końcu znajduje się szablon, który będzie wyświetlać końcowy kod HTML (Rys. 7.).

Rys. 7. Elementy makra XSLT: szablon.

Właściwości currentPage

Obiekt currentPage posiada kilka ciekawych właściwości, które są przydatne podczas tworzenia makr. Rys. 8. przedstawia listę właściwości, z przykładem użycia makra.

Rys. 8. Właściwości parametru „currentPage”.

Rys. 9. przedstawia wartości currentPage dla strony głównej o nazwie Travel, zawarte w przeglądarce internetowej.

Rys. 9. Właściwości „currentPage”, wyświetlone w przeglądarce.

Te wartości to tak naprawdę dane, które znajdują się w specjalnych plikach XML, które są tworzone dla każdej strony, utworzonej w Umbraco.

Selektor

Gdy wiemy już, jakie dane możemy znaleźć w obiektcie currentPage, możemy spróbować je wyświetlić. Jedną z podstawowych instrukcji jest value-of. Przykładem użycia może być przykład zaprezentowany powyżej, w którym odwoływaliśmy się do poszczególnych składowych obiektu currentPage. Użycie value-of powoduje pobranie obiektu o podanej nazwie. Jeśli chcemy z tego obiektu pobrać składową, należy po ukośniku podać jej nazwę (Rys. 10.).

Rys. 10. Selector „value-of”.

Pętle

XPATH umożliwia także tworzenie pętli for each i iterowanie po wyniku wyrażenia, które zostanie wprowadzenie w nagłównku pętli. Poniżej przykład pętli, która wyświetla nazwy podstron (Rys. 11.).

Rys. 11. Pętla „for each”.

Nazwy stron zostaną wyświetlone jedna za drugą, ponieważ ciało pętli for each nie zawiera żadnych dodatkowych znaczników, które by formatowały wynik (Rys. 12.).

Rys. 12. Nazwy podstron wyświetlone za pomocą makra i pętli „for each”.

Jak widać na Rys. 12., oryginalne menu nawigacyjne pokazuje odnośnik do strony głównej oraz trzech podstron. Makro również wyświetliło nazwy podstron.

Za pomocą tych dwóch prostych poleceń można już budować niestandardowe menu nawigacyjne.

Instrukcje warunkowe

Jeśli chcemy, aby nasz kod był generowany warunkowo, możemy użyć instrucji if. W tym celu wybrany blok kodu należy objąć znacznikiem <xsl:if test=[wyrażenie] > [kod] </xsl:if>.

Uwaga
Aby wyrażenie było prawdziwe, musi zwracać wartość 1.

Rys. 13. przedstawia kilka przykładów instrukcji if wraz z wynikami logicznymi.

Rys. 13. Instrukcja warunkowa „if”.

Uruchomienie makra spowodowałoby wyświetlenie słowa prawda 3 razy na stronie.

Umbraco.Library

W makrach XSLT można wywoływać bardziej zaawansowane elementy Umbraco. W tym celu zostało udostępnione Umbraco.Library, które dostarcza API, dzięki któremu możliwe jest np.:

  • sprawdzanie uprawnień,
  • sprawdzanie, czy dana strona jest opublikowana,
  • formatowane adresów URL,
  • pobieranie informacji o zalogowanym użytkowniku (użytkowniku witryny – Member, a nie użytkowniku Panelu Administratora – User),
  • oraz wiele innych.

Pełną dokumentację, listę metod wraz z przykładami, można znaleźć na stronach Umbraco pod adresem: http://our.umbraco.org/wiki/reference/umbracolibrary.

Dodatkowe źródła

Podsumowanie

W tym artykule poznałeś pierwszy rodzaj makr w Umbraco czyli makra XSLT. Dowiedziałeś się, czym one są, jak je tworzyć oraz jakie są ich możliwości i wady.

W kolejnym artykule dowiesz się, jak tworzyć makra .NET.