Asystent szablonów

Razem z wersją 1.1 Maktury udostępniliśmy nowe narzędzie - Asystenta Szablonów. Jego zadaniem jest pomoc w tworzeniu własnych szablonów dla wystawianych faktur i rachunków. Do stworzenia własnego szablonu od zera wymagana jest wiedza z zakresu CSS, HTML i rozumienie zasad pisania programów. Modyfikacja istniejącego szablonu powinna natomiast być możliwa dla każdej osoby obdarzonej zdolnością logicznego myślenia.

Jak wygląda praca z Asystentem Szablonów?

W tym krótkim filmiku Zbigniew opowiada o tym jak korzystać z asystenta, aby zbudować własny szablon:

Anatomia szablonu

Wyobraźmy sobie, że oglądamy dokument z Maktury z dużej odległości. O ile wszystko jest OK z naszym wzrokiem, to nie dostrzegamy szczegółów, lecz widzimy plamy, w które się one zlewają. To co widzimy to 'architektura dokumentu', czyli układ poszczególnych informacji. Może on wyglądać np. tak: Tworząc własny szablon dokumentu, możemy zastosować podobne podejście od ogółu do szczegółu. Po zaplanowaniu, jakie informacje będą wyświetlane w poszczególnych częściach strony, czas na wytłumaczenie Makturze, gdzie ma wstawić NIP sprzedawcy, a gdzie podpis odbierającego dokument. Służą do tego specjalne nazwy (tzw. zmienne), które przy generowaniu dokumentu zostaną zastąpione wartościami, tworząc gotową fakturę VAT, rachunek itd.

Język skryptowy

Przystępując do projektowania własnego szablonu, niezbędna jest wiedza zarówno z zakresu HTML+CSS, jak i odrobina znajomości programowania dla WWW. Zastanawiasz się, czy podołasz? Spójrz na kawałek kodu poniżej. Jeżeli dostajesz palpitacji serca, być może stworzenie własnego szablony przekracza Twoje aktualne umiejętności... Jeżeli domyślasz się, co i jak, prawdopodobnie własny szablon do Maktury masz w zasięgu klawiatury.

	  1. Tak wypisujemy wartość zmiennej o nazwie documentID: {{ documentID }}

	  2. Tak realizujemy instrukcję warunkową:
	  {{ if greenTemplate }}
	     aha, więc szablon ma być oszczędny
	  {{ else }}
	     nie oszczędzamy sił i środków, aby zaprezentować nasz dokument w pełnej krasie
	  {{ endif }}

	  3. Tak przechodzimy po danych w tablicy
	  {{ foreach item items }}
	    tu item zawiera aktualne dane z tablicy
	  {{ endforeach }}
	

Szczegóły języka

Język skryptowy na którym oparty jest silnik renderujący dokumenty w Makturze, korzysta z biblioteki MiscMerge. Szczegółowe informacje dotyczące meandrów MiscMerge'a można znaleźć w oryginalnej dokumentacji. Tu skupimy się tylko na kilku wybranych, ale wystarczających do zbudowania własnego szablonu, funkcjach.

Blok kodu

Jeżeli nie jest Ci obce PHP, JSP, ERB czy cokolwiek innego co działa po stronie serwera WWW, znasz też zapewne koncepcję odróżniania fragmentu kodu od treści szablonów. W przypadku Maktury jako kod traktowane jest wszytko pomiedzy podwójnymi nawiasami klamrowymi - {{ i }}. Jednocześnie nie ma rozróżnienia między blokiem kodu a wypisaniem zawartości do szablonów.

Instrukcja warunkowa

Jak widać w punkcie numer 2 w przykładzie powyżej, instrukcja warunkowa wygląda następująco

	  {{ if warunek }}
	    ...
	  {{ else }}
	    ...
	  {{ endif }}
	

Pętla przeglądająca zawartość tablicy

Jeżeli informacje przekazywane do szablony są zawarte w tablicy, a my tworząc szablon potrzebujemy dobrać się do poszczególnych elementów w niej zawartych, robimy to za pomocą konstrukcji:

	  {{ foreach zmienna_lokalna_dla_pętli zmienna_reprezentująca_tablicę }}
	    ... operujemy na zmiennej lokalnej używając jej do wyświetlenia szczegółów
	  {{ endforeach }}
	

Obiekty i ich atrybuty

Niektóre dane przekazywane do szablonu mają bardziej złożoną naturę niż prosta liczba czy ciąg znaków - są obiektem. Dla potrzeb tworzenia szablonów wystarczy zapamiętać, że obiekt to taki zbiornik zawierający dane - atrybuty. Do atrybutów sięgamy, posługując się nazwą obiektu, a po kropce nazwą atrybutu.
Przykładowo, jako obiekt są przekazywane dane nabywcy, obiekt jest dostępny w szablonie pod zmienną purchaser, ale nip nabywcy to już atrybut. Aby się do niego dostać posługujemy się kombinacją purchaser.nip. Podobnie postępujemy, gdy interesuje nas np. adres wystawiającego: seller.address czy wartość netto pozycji na fakturze: item.netPrice.

Zmienne szablonów

Każda faktura zawiera całkiem pokaźną liczbę informacji, a co za tym idzie liczba zmiennych z którymi mamy do czynienia projektując szablon jest całkiem spora. Aby ułatwić odnalezienie tego co potrzebne, podzielmy zmienne na grupy.