How to create theme

Poniższy artykuł opisuje budowę systemu motywów (szablonów) wykorzystywanego w eStats od wersji 4.5 (z późniejszymi zmianami), dowiesz się z niego jak stworzyć własny motyw.

Spis treści

^ Wprowadzenie

System motywów używany od wersji 4.5 został napisany właściwie od zera, dzięki czemu usunięte zostały niektóre niedogodności występujące w poprzednich wersjach (głównie "psucie się" motywów, gdy zostanie zmienione oznaczenie końca linii w pliku). Został także wzbogacony o nowe możliwości, o których mowa w dalszej części artykułu.

Przy tworzeniu własnego motywu zaleca się bazowanie na jednym z istniejących, najlepiej na motywie Silver, gdyż na nim bazuje większość dołączonych do zestawu.

Motywy przechowywane są w folderze share/themes/, instalacja i de instalacja polega na dodaniu lub usunięciu całego folderu motywu.

^ Budowa

^ Element główny

Jest to plik theme.tpl, zawierający główny szkielet strony.

Każdy motyw musi posiadać własny, unikalny plik główny, gdyż zawiera on informacje o autorze, link do strony domowej, licencję oraz nazwę motywu (wszystko w formie komentarza). Zawiera także deklarację typu dokumentu (DTD). Obecnie oficjalnie wspierane są dokumenty HTML oraz XHTML, lecz przy niewielkim nakładzie pracy powinno być możliwe wykorzystanie języków opartych o XML.

W przeciwieństwie do pozostałych plików motywu, zawierających bloki, jest traktowany odmiennie. Jako element główny jest pobierany w całości, a następnie są w nim umieszczane wszystkie elementy poczynając od treści strony.

^ Bloki

Używane są specjalne znaczniki obejmujące elementy, które mają być traktowane jako bloki, np: 

1
2
3
4
5
6
7
8

[start:chart-bars-container]<td{class} id="{id}">
<div>
{bars}</div>
{desc}</td>
[/end]

[start:chart-bar]<div style="height:{height}px;margin-top:{margin}px;" class="{class}" title="{title}"></div>
[/end]

Każdy znacznik wygląda w następujący sposób: 

1
2
3

[start:identyfikator]
kod bloku
[/end]

Identyfikatory nie mogą się powtarzać, gdyż w niektórych wypadkach kod reprezentowany przez dane ID może zostać nadpisany innym, co może zniszczyć układ wygenerowanego kodu.

Używanie znaczników pozwala na wykorzystanie "pustego" miejsca pomiędzy nimi na umieszczenie komentarzy bez użycia specjalnych znaczników, np. 

1
2
3
4
5
6
7
8
9

[start:ID1]

[/end]

Komentarz dla bloków

[start:ID2]

[/end]

^ Umieszczanie elementów w motywie

Aby umieścić w elemencie motywu tekst lub inny element ("zmienne motywu"), należy użyć znaczników {} (nawias klamrowy). Możemy umieszczać wszystkie elementy zawarte w tablicy $Theme. Są to zwykle niewielkie elementy zawierające np. listy wyboru, ścieżki dostępu, identyfikatory lub niewielkie, czasem powtarzające się bloki kodu.

Przykład: 

1
2

<script type="text/javascript" src="{datapath}themes/{theme}/theme.js"></script>
<script type="text/javascript" src="{datapath}lib/functions.js"></script>

Specjalnym elementem wstawianym w ten sposób jest treść strony, o identyfikatorze page.

Jeżeli użyty zostanie ciąg nie występujący w tablicy, to nie zostanie on zastąpiony i będzie wyświetlany tak jakby był zwykłym tekstem.

^ Przełączniki

Dodatkowym wsparciem zwiększającym możliwości i ułatwiającym pracę jest obsługa "przełączników", komentarzy warunkowych decydujących o tym czy dany element ma być wyświetlany, czy nie. Umiejscowione są w tablicy $ThemeSwitch.

Część z nich jest dostępna globalnie, na każdej podstronie, część jest definiowana na potrzeby konkretnych podstron (np. przy wyświetlaniu danych z użyciem biblioteki group).

Lista globalnych przełączników:

  • loggedin - użytkownik jest zalogowany;
  • user - użytkownik posiada poziom 1;
  • admin - użytkownik jest administratorem;
  • adminpage - strona należy do panelu administracyjnego;
  • loginpage - strona jest stroną logowania;
  • loadpage - strona może być wyświetlona;
  • antyflood - zbyt częste odświeżanie strony;
  • selectform - istnieje możliwość wyboru motywu i / lub języka;
  • critical - wystąpił błąd krytyczny;
  • announcements - dostępne są informacje do wyświetlenia;

Ponadto każdy przełącznik można zanegować: 

1
2

<!--start:id1-->Tekst widoczny, gdy przełącznik ma wartość logiczną prawda<!--end:id1-->
<!--start:!id2-->Tekst widoczny, gdy przełącznik ma wartość logiczną fałsz<!--end:!id2-->

Dzięki swojej budowie, gdy przełącznik nie zostanie zdefiniowany w kodzie, to nie będzie to widoczne dla użytkownika.

^ Plik konfiguracyjny

Plik theme.ini zawiera domyślną konfigurację motywu oraz informacje o nim. Plik ten posiada formę typowego pliku INI, ze wszystkimi zaletami i wadami tego formatu.

Opis opcji pliku konfiguracyjnego:

  • Information - informacje o motywie;
    • Name - nazwa motywu (najlepiej taka sama jak jego folderu);
    • Author - autor;
    • URL - adres strony autora;
    • Licence - licencja;
    • Time - czas modyfikacji (uniksowy znacznik czasu);
  • Options - opcje motywu;
    • Header - wysyłany nagłówek HTTP (ciąg tekstowy);
    • GroupRowValueLength - maksymalna długość ciągu tekstowego w wierszu grupy - Ogólne, Techniczne i Geolokalizacja (liczba);
    • SingleGroupRowValueLength - jak wyżej, dla widoku pojedynczej grupy (liczba);
    • DetailedRowValueLength - maksymalna długość ciągu tekstowego w Szczegółowych (liczba);
    • DetailsRowValueLength - maksymalna długość ciągu tekstowego w Szczegółach wizyty (liczba);
    • Type - typ dokumentu (xhtml / html);
    • Icons - czy mają być używane ikony (1 / 0);
    • PieChartColors - lista kolorów używanych do generowania wykresu kołowego (wartości kolorów, szesnastkowo, RGB, oddzielone znakiem |:
    • początek zakresu wypełnienia|koniec zakresu wypełnienia|początkowe tło|tekst);
    • TimeChartColors - lista kolorów używanych do generowania wykresów w Czasowych (wartości kolorów, szesnastkowo, RGB, oddzielone znakiem |:
    • odsłony|unikalne|powroty);
    • SimpleCharts - generuj uproszczone wykresy - przydatne dla motywów dla przeglądarek tekstowych i bez obsługi CSS (1 / 0);

Przykładowy plik konfiguracyjny (motyw Silver): 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

[Information]
Name = "Silver"
Author = "Emdek"
URL = "http://estats.emdek.cba.pl"
Licence = "GPL"
Time = "1203187559"
[Options]
Header = "Content-type: text/html; charset=utf-8"
GroupRowValueLength = 20
SingleGroupRowValueLength = 40
DetailedRowValueLength = 20
DetailsRowValueLength = 20
Type = "xhtml"
Icons = 1
PieChartColors = "AAAAAA|FAFAFA|FFFFFF|02356F"
TimeChartColors = "CCCCCC|BBBBBB|AAAAAA"
SimpleCharts = 0

^ Dodatkowe pliki

Motyw składa się ponadto (opcjonalnie) z plików CSS oraz JS (zalecana nazwa theme.*). Dodatkowo istnieje możliwość dołączenia pliku PHP (theme.php), aby dodatkowo obrobić istniejące elementy lub dodać nowe (dołączany jest na samym końcu, tuż przed parsowaniem).

Może zawierać także grafiki (w folderze images/) oraz zestaw ikon (icons/), jeśli opcja konfiguracyjna na to zezwala.

Dodatkowo każdy motyw może posiadać własny anty piksel, zaleca się aby każdy posiadał własny, najlepiej o nazwie tej samej co motyw (ale pisanej małymi literami). Motywy dołączone do skryptu umieszczają swoje anty piksele w zestawie Default.

^ Budowa przykładowego motywu (Silver)

Posiadanie wszystkich plików nie jest wymagane, część jest nieobowiązkowa, a część (wymagane pliki zawierające bloki) zostanie automatycznie pobrana z share/themes/common/ w przypadku braku.

Na poniższym diagramie można zobaczyć budowę przykładowego katalogu motywu:

  • Silver/ [wymagany - główny katalog motywu, nazwa taka jak motywu]
    • icons/ [opcjonalny - alternatywy dla wspólnych ikon z folderu share/icons/misc/]
    • images/ [opcjonalny - katalog obrazków motywu]
      • body.png
      • chart.png
      • content.png
      • error.png
      • footer.png
      • gototop_active.png
      • gototop.png
      • html.png
      • info.png
      • menu_active.png
      • menu.png
      • success.png
      • thb.png
      • th.png
      • warning.png
    • common.tpl [dodatkowy - plik bloków motywu]
    • detailed.tpl [dodatkowy - plik bloków motywu]
    • details.tpl [dodatkowy - plik bloków motywu]
    • general.tpl [dodatkowy - plik bloków motywu]
    • geoip.tpl [dodatkowy - plik bloków motywu]
    • group.tpl [dodatkowy - plik bloków motywu]
    • login.tpl [dodatkowy - plik bloków motywu]
    • technical.tpl [dodatkowy - plik bloków motywu]
    • theme.css [plik CSS motywu]
    • theme.ini [wymagany - plik konfiguracyjny]
    • theme.js [plik funkcji JS]
    • theme.php [dodatkowy - plik PHP motywu]
    • theme.tpl [wymagany - główny plik szablonu motywu]
    • time.tpl [dodatkowy - plik bloków motywu]

Motyw Silver nie korzysta z pliku PHP oraz nie posiada własnych plików bloków.

^ Działanie

System motywów działa poprzez wykonywanie kolejnych czynności na dostępnych danych, od kolejności tych kroków zależy zakres możliwości twórcy motywów.

Po ustaleniu motywu, który ma być użyty, następuje wczytanie jego konfiguracji, dane są pobierane z pliku theme.ini wybranego motywu.

"Kolejnym" krokiem jest utworzenie przełączników. Przełączniki mogą być utworzone w dowolnym momencie działania skryptu, ale "wykonywane" są dopiero po umieszczeniu wszystkich elementów na swoich miejscach.

Skrypt definiuje wiele zmiennych motywu, część jest zależna od wybranej strony. Niektóre elementy motywu są obrabiane przy użyciu własnych funkcji, np. elementy menu, a dopiero później dołączane do tablicy zmiennych.

Wczytywany jest plik common.tpl zawierający kilka elementów wspólnych dla wszystkich lub przynajmniej kilku podstron, np. elementy menu, czy układ bloku opcji administratora.

Dla podstron statystyk (ale nie dla panelu administracyjnego) jest wczytywany plik, którego nazwa odpowiada jej ID, a następnie pobierany jest z niego blok o danym ID i ustawiany jako element page.

Przed wysłaniem do przeglądarki wygenerowanego motywu wysyłany jest jeszcze nagłówek HTTP zdefiniowany w pliku konfiguracyjnym.

Wszystkie elementy są na końcu dołączane do głównego pliku motywu, w takiej kolejności:

  • element page;
  • zmienne motywu (znaczniki {}), trzykrotnie;
  • wykonanie przełączników;
  • dołączenie czasu generowania strony oraz opcjonalnie wyjścia debuggera;

Do motywu dołączane są pliki CSS - wspólny, a dopiero później własny motywu (z możliwością nadpisania domyślnych wartości w razie potrzeby).

^ Zakończenie

Jeśli nie odstraszył Cię ten opis i zrobiłeś jakiś motyw, to skontaktuj się ze mną (najlepiej za pośrednictwem odpowiedniego działu forum) i pokaż wynik swojej pracy, być może zostanie dołączony do bazy Pobieralni, lub do samego pakietu ze skryptem, a może nawet stać się nowym domyślnym motywem ;-). Jeśli masz jakieś dodatkowe pytania, to nie wstydź się ich zadawania ;-).
Powodzenia!

^ Patrz także

Ostatnia modyfikacja: 2008-02-16 23:19:25 CET

Falling in love is not at all the most stupid thing that people do — but gravitation cannot be held responsible for it.

Albert Einstein