Text: {toc} h3. Czym jest framework Najprościej mówiąc framework jest to narzędzie służące do tworzenia aplikacji. Jego użycie sprawia że praca programisty jest łatwiejsza i szybsza, a sama aplikacja posiada mniej błędów. W tym celu powstał również framework dla systemu APEL, jest on jednak na tyle uniwersalny, że można go wykorzystać do budowy dowolnej aplikacji. Z poniższego kursu dowiemy się jak w oparciu o niego zbudować własny system, oraz jak używać mechanizmów w nim zawartych. h3. Struktura plików Używanie frameworku najprościej będzie omówić na przykładzie. Załóżmy że chcemy zbudować własny system którego roboczo nazwiemy mojapel. Od czego należy zacząć? Po pierwsze należy przygotować odpowiednią strukturę plików dla naszego systemu. Tworzymy katalog mojapel w którym będzie znajdował się kod naszego systemu. Teraz musimy stworzyć dwa podkatalogi: w pierwszym będą się znajdować pliki naszego frameworku (zwyczajowo jest on nazywany core) oraz drugi w którym będzie znajdować się kod napisany przez nas (nazwijmy go front). Zazwyczaj plików w katalogu core nie modyfikujemy. Oczywiście jest to możliwe ale może spowodować problemy przy aktualizacji wersji frameworku, więc lepiej tego nie robić Zajmijmy się więc drzewem plików katalogu front. Powinny się w nim znaleźć następujące podkatalogi: * config * out * skin * system Omówimy teraz co powinno się znajdować w każdym z katalogów h3. config Katalog config jest miejscem na pliki konfiguracyjne. Przy tworzeniu oprogramowania prawie zawsze ustawienia deweloperskie różnią się od ustawień produkcyjnych. Zmusza to programistę do utrzymywania różnych wersji pliku konfiguracyjnego, lub ciągłej jego edycji co bywa dosyć uciążliwe i może skutkować wystąpieniem błędów wynikających np. z wyeksportowania na serwer produkcyjny pliku konfiguracyjnego z serwera testowego. W naszym frameworku przewidziano istnienie różnych plików konfiguracyjnych, zmienianych jedynie przy pomocy jednej flagi w systemie (można się nawet pokusić o automatyzację wyboru na podstawie np. IP serwera). Na potrzeby tworzenia aplikacji używamy pliku test.php natomiast po wdrożeniu work.php. **UWAGA! Pliki muszą się nazywać dokładnie tak jak podano powyżej, inaczej nie zostaną one rozpoznane.** h3. out W tym katalogu serwer będzie zapisywał potrzebne mu pliki tymczasowe. Znajdą się w nim pliki cache, logi, możemy też używać go do zapisu innych potrzebnych nam rzeczy. Drzewo katalogów wewnątrz katalogu out powinno wyglądać następująco: * cache ** cache ** compile ** config * log ** exception ** logs p. Podkatalog cache będzie używany przez mechanizm smarty na którym oparte jest generowanie stron naszego frameworka, natomiast w katalogu log znajdą się wszelkiego rodzaju logi generowane przez system. Oprócz wyżej wymienionych możemy oczywiście dodać własne w miarę potrzeb. Trzeba jedynie pamiętać że wszystkie muszą mieć uprawnienia do zapisu przez serwer. h3. skin p. Tutaj będą znajdowały się "skórki" naszego systemu. Możemy ich zdefiniować większą ilość i używać w dowolny sposób, muszą jednak mieć określoną strukturę. Bezpośrednio w katalogu skin powinien znaleźć się katalog którego nazwa jest nazwą naszej "skóry". Domyślnie jest to katalog default. W nim muszą znaleźć się katalogi mail gdzie będą zdefiniowane szablony dla emaili wychodzących z systemu, oraz template gdzie znajdują się szablony html (zapisane w formacie smarty z rozszerzeniem .tpl. Na tym poziomie możemy też zdefiniować pliki css oraz javascript. Co do ich umiejscowienia nie ma określonych wymogów (ścieżkę do nich podajemy w szablonie strony). Tutaj też powinna znaleźć się grafika używana na stronie (zwyczajowo katalog z grafiką nazywamy images) h3. system p. Ten katalog jest z naszego punktu widzenia najważniejszy. W nim będą znajdować się definicje wszystkich używanych przez nas obiektów. Powinny się w nim znaleźć cztery podkatalogi: * ctrl * show * mngr * obj p. Co oznaczają ich nazwy i do czego służą dowiemy się z następnych lekcji. W katalogu tym znajduje się też bardzo ważny plik exception.php. Jest on odpowiedzialny za obsługę wyjątków w naszym systemie. Jeśli nie chcemy tworzyć własnej ich obsługi (a na razie nie chcemy) wystarczy że użyjemy standardowo zdefiniowanej klasy wyjątków. W takim przypadku plik exception.php będzie wyglądał tak: pre.. <? /** * Exceptions */ class system_exception extends ap_exception { } ?> h3. index.php p. Teraz zajmijmy się głównym plikiem naszego systemu, czyli index.php. Na samym początku tworzenia naszej aplikacji powinien wyglądać tak: pre.. <? /** * Main class */ date_default_timezone_set('Europe/Warsaw'); session_start(); require_once('../core/ap/page.php'); /** * klasa odpowiedzialna za wyświetlanie stron serwisu */ class mojapel extends ap_page { /** * inicjalizacja zmiennych systemowych */ protected $skin = 'default'; protected function init() { self::$context = ap_sys::PROFILE_TEST; $this->ctrl = array (); } } try { $page = new mojapel(); $page->display(); } catch (system_exception $xt) { $xt->catchIt(); } ?> p. Zwróćmy uwagę na zmienne $skin i $context. Jak widać modyfikując je możemy zmieniać tryb działania aplikacji (testowy/produkcyjny) jak również wybrać layout. Do przełączenia trybu działania używamy dwóch stałych: pre.. ap_sys::PROFILE_TEST ap_sys::PROFILE_WORK p. W zależności od tego którą przypiszemy, taki typ pliku konfiguracyjnego zostanie włączony do aplikacji. p. Aby zmienić layout naszej strony wystarczy na zmienną $skin przypisać nazwę katalogu w jakim go zdefiniowaliśmy. p. Tak oto dobrnęliśmy do końca przygotowań. Możemy przystąpić do implementacji naszego systemu. p. W praktyce nie musimy pamiętać całej struktury i za każdym razem samemu ją tworzyć. W katalogu core/start/ znajduje się plik start.zip w którym znajduje się spakowana gotowa struktura katalogu użytkownika (u nas front). W naszym przykładzie wystarczyłoby do katalogu front rozpakować ten plik i ewentualnie zmienić prawa dostępu do katalogu out wraz z podkatalogami. → {toc} h3. Czym jest framework Najprościej mówiąc framework jest to narzędzie służące do tworzenia aplikacji. Jego użycie sprawia że praca programisty jest łatwiejsza i szybsza, a sama aplikacja posiada mniej błędów. W tym celu powstał również framework dla systemu APEL, jest on jednak na tyle uniwersalny, że można go wykorzystać do budowy dowolnej aplikacji. Z poniższego kursu dowiemy się jak w oparciu o niego zbudować własny system, oraz jak używać mechanizmów w nim zawartych. h3. Struktura plików Używanie frameworku najprościej będzie omówić na przykładzie. Załóżmy że chcemy zbudować własny system którego roboczo nazwiemy mojapel. Od czego należy zacząć? Po pierwsze należy przygotować odpowiednią strukturę plików dla naszego systemu. Tworzymy katalog mojapel w którym będzie znajdował się kod naszego systemu. Teraz musimy stworzyć dwa podkatalogi: w pierwszym będą się znajdować pliki naszego frameworku (zwyczajowo jest on nazywany core) oraz drugi w którym będzie znajdować się kod napisany przez nas (nazwijmy go front). Zazwyczaj plików w katalogu core nie modyfikujemy. Oczywiście jest to możliwe ale może spowodować problemy przy aktualizacji wersji frameworku, więc lepiej tego nie robić Zajmijmy się więc drzewem plików katalogu front. Powinny się w nim znaleźć następujące podkatalogi: * config * out * skin * system Omówimy teraz co powinno się znajdować w każdym z katalogów h3. config Katalog config jest miejscem na pliki konfiguracyjne. Przy tworzeniu oprogramowania prawie zawsze ustawienia deweloperskie różnią się od ustawień produkcyjnych. Zmusza to programistę do utrzymywania różnych wersji pliku konfiguracyjnego, lub ciągłej jego edycji co bywa dosyć uciążliwe i może skutkować wystąpieniem błędów wynikających np. z wyeksportowania na serwer produkcyjny pliku konfiguracyjnego z serwera testowego. W naszym frameworku przewidziano istnienie różnych plików konfiguracyjnych, zmienianych jedynie przy pomocy jednej flagi w systemie (można się nawet pokusić o automatyzację wyboru na podstawie np. IP serwera). Na potrzeby tworzenia aplikacji używamy pliku test.php natomiast po wdrożeniu work.php. **UWAGA! Pliki muszą się nazywać dokładnie tak jak podano powyżej, inaczej nie zostaną one rozpoznane.** h3. out W tym katalogu serwer będzie zapisywał potrzebne mu pliki tymczasowe. Znajdą się w nim pliki cache, logi, możemy też używać go do zapisu innych potrzebnych nam rzeczy. Drzewo katalogów wewnątrz katalogu out powinno wyglądać następująco: * cache ** cache ** compile ** config * log ** exception ** logs p. Podkatalog cache będzie używany przez mechanizm smarty na którym oparte jest generowanie stron naszego frameworka, natomiast w katalogu log znajdą się wszelkiego rodzaju logi generowane przez system. Oprócz wyżej wymienionych możemy oczywiście dodać własne w miarę potrzeb. Trzeba jedynie pamiętać że wszystkie muszą mieć uprawnienia do zapisu przez serwer. h3. skin p. Tutaj będą znajdowały się "skórki" naszego systemu. Możemy ich zdefiniować większą ilość i używać w dowolny sposób, muszą jednak mieć określoną strukturę. Bezpośrednio w katalogu skin powinien znaleźć się katalog którego nazwa jest nazwą naszej "skóry". Domyślnie jest to katalog default. W nim muszą znaleźć się katalogi mail gdzie będą zdefiniowane szablony dla emaili wychodzących z systemu, oraz template gdzie znajdują się szablony html (zapisane w formacie smarty z rozszerzeniem .tpl. Na tym poziomie możemy też zdefiniować pliki css oraz javascript. Co do ich umiejscowienia nie ma określonych wymogów (ścieżkę do nich podajemy w szablonie strony). Tutaj też powinna znaleźć się grafika używana na stronie (zwyczajowo katalog z grafiką nazywamy images) h3. system p. Ten katalog jest z naszego punktu widzenia najważniejszy. W nim będą znajdować się definicje wszystkich używanych przez nas obiektów. Powinny się w nim znaleźć cztery podkatalogi: * ctrl * show * mngr * obj p. Co oznaczają ich nazwy i do czego służą dowiemy się z następnych lekcji. W katalogu tym znajduje się też bardzo ważny plik exception.php. Jest on odpowiedzialny za obsługę wyjątków w naszym systemie. Jeśli nie chcemy tworzyć własnej ich obsługi (a na razie nie chcemy) wystarczy że użyjemy standardowo zdefiniowanej klasy wyjątków. W takim przypadku plik exception.php będzie wyglądał tak: pre.. <? /** * Exceptions */ class system_exception extends ap_exception { } ?> h3. index.php p. Teraz zajmijmy się głównym plikiem naszego systemu, czyli index.php. Na samym początku tworzenia naszej aplikacji powinien wyglądać tak: pre.. <? /** * Main class */ date_default_timezone_set('Europe/Warsaw'); session_start(); require_once('../core/ap/page.php'); /** * klasa odpowiedzialna za wyświetlanie stron serwisu */ class mojapel extends ap_page { /** * inicjalizacja zmiennych systemowych */ protected $skin = 'default'; protected function init() { self::$context = ap_sys::PROFILE_TEST; $this->ctrl = array (); } } try { $page = new mojapel(); $page->display(); } catch (system_exception $xt) { $xt->catchIt(); } ?> p. Zwróćmy uwagę na zmienne $skin i $context. Jak widać modyfikując je możemy zmieniać tryb działania aplikacji (testowy/produkcyjny) jak również wybrać layout. Do przełączenia trybu działania używamy dwóch stałych: pre.. ap_sys::PROFILE_TEST ap_sys::PROFILE_WORK p. W zależności od tego którą przypiszemy, taki typ pliku konfiguracyjnego zostanie włączony do aplikacji. p. Aby zmienić layout naszej strony wystarczy na zmienną $skin przypisać nazwę katalogu w jakim go zdefiniowaliśmy. p. Tak oto dobrnęliśmy do końca przygotowań. Możemy przystąpić do implementacji naszego systemu. p. W praktyce nie musimy pamiętać całej struktury i za każdym razem samemu ją tworzyć. W katalogu core/start/ znajduje się plik start.zip w którym znajduje się spakowana gotowa struktura katalogu użytkownika (u nas front). W naszym przykładzie wystarczyłoby do katalogu front rozpakować ten plik i ewentualnie zmienić prawa dostępu do katalogu out wraz z podkatalogami. "Obiekty >>>":http://www.xp-dev.com/wiki/67486/Obiekty