Pusty projekt v 0.9 beta
Praca nad aplikacją sieciową różni się dość znacznie od pracy nad zbiorem stron WWW. Przy przygotowywaniu aplikacji istotne jest to, by można było bez problemu rozwijać ją dostosowując do potrzeb użytkowników. Dlatego istotna jest przejrzystość kodu i dobre zorganizowanie sobie pracy.
Niestety w praktyce wielu programistów zwraca większa uwagę na szybkość działania kodu, co po kilku, kilkunastu poprawkach i rozbudowach nieuchronnie prowadzi do konieczności napisania wszystkiego od początku. Problemem są także błędy spowodowane poprawkami – naprawienie jednej rzeczy – psuje inną.
Moja propozycja polega na podejściu do aplikacji WWW w taki sam sposób jak podchodzimy to tworzenia innych typów aplikacji: obiektowo i w oparciu o nowoczesne i sprawdzone metodologie pracy. Dlatego przewidziano tu proste środowisko przeznaczone do obsługi testów jednostkowych oraz elementy zarządzania baza danych. Baza danych zawiera tabelę zawierającą wersję bazy oraz informację o jej stanie. Informacje te umieszczone są w tabeli Version i wykorzystywane przez strony zarządzające projektem do sprawdzenia czy operacja a bazie jest możliwa. Przyda się także do ewentualnej migracji bazy danych.
Download   Plik do ściągnięcia
Pusty projekt - komplet plików wraz ze strukturą katalogów. Wystarczy rozpakować w katalogu roboczym aplikacji i wypełnić kodem. Pusty projekt zawiera stronę główną która pozwala na zarządzanie aplikacją oraz procesem jej budowy.
Opis   Opis struktury katalogów i plików
./ (katalog główny) – zawiera główne pliki aplikacji – strony. W pustym projekcie – znajdują się pliki
  • conf.php – konfiguracja aplikacji – tu definiujemy wszystkie istotne parametry naszego programu, między innymi parametry połączenia z bazą danych. W podstawowej wersji definiujemy tu tylko dane połączenia bazy do bazy danych. Muszą one odpowiadać używanemu serwerowi oraz aktywnemu użytkownikowi tego serwera.
  • index.php – główna strona aplikacji
  • run-framework.php – prosty ale skuteczny framework. Określa ścieżki do katalogów z plikami graficznymi, klasami (pliki źródłowe w PHP), skryptami w javascripcie, i arkuszami styli. Framework włącza plik z konfiguracją, definiuje wyjście na które będzie wysyłany kod HTML dla przeglądarki oraz definiuje automatyczne ładowanie klas, tak byśmy nie musieli włączać ręcznie plików do każdej ze stron. UWAGA: Pliki muszą mieć takie same nazwy jak klasy w nich zdefiniowane. Wyjątkiem są klasy pozwalające na dostęp do baz danych. Muszą one zawierać w swojej nazwie ‘Database’ w nazwach plików przed 'Database' dołączana jest nazwa typu bazy (zdefiniowana w konfiguracji). Pozwala to na przygotowywanie aplikacji pracującej różnymi serwerami baz danych

classes – zawiera pliki które stanowią o istocie aplikacji – to tutaj znajdują się wszystkie klasy tworzące aplikację. Pierwotnie jest tu tylko kilka klas tworzących szkielet aplikacji. Większość z nich to tylko przykładowe pliki które powinny być nadpisane lub poprawione przez programistę tworzącego aplikację.

  • Control.php – jest klasą bazową dla „kontrolek” – elementów edycyjnych.. Zawiera tylko konstruktor i dwa pola publiczne.
    • __construct – przyjmuje jako parametry nazwę elementu edycyjnego oraz jego wartość domyślną – która będzie ustawiona jeśli przetwarzana strona nie zawiera danych o takiej nazwie. Jeśli w kolekcji $_POST lub $_GET znajduje się taki element, wartość zostanie ustawiona na wartość która był przesłana. Dodatkowo używana jest zmienna globalna $_FAKE która może być stosowana w testach, by zasymulować dane wysyłane ze strony przeglądarki.
    • $name – nazwa elementu kontrolnego
    • $value – wartość
    Klasa może być użyta bezpośrednio w responderach, gdy nie potrzebujemy tworzyć kodu elementu edycyjnego wyświetlanego po stronie klienta
  • MySQLDatabaseAccess.php – klasa zapewniająca dostęp do bazy danych poprzez serwer MySQL.
    • __construct – konstruktor obiektu nie wymaga podawania żadnych parametrów. Wszystkie są odczytywane z bieżącej konfiguracji. Łączy się z bazą danych.
    • query – pozwala na wysłanie zapytania do bazy danych. Jako parametr przekazywany jest string zawierający zapytanie w języku SQL. Wynikiem jest obiekt klasy DatabaseRecordset pozwalający na odczyt danych.
    • queryValue – podobnie jak metoda query, jednak to wynikiem działania jest pierwsze pole z pierwszego rekordu ze wyniku zapytania. Jeśli zapytania zwróci pusty zbiór rekordów – zwracana jest wartość domyślna przekazywana jako drugi parametr
  • MySQLDatabaseRecordset.php – interfejs do rekordsetu zwracanego przez zapytania do bazy danych. Może być wzorcem dla całego zbioru źródeł danych – zawiera najbardziej podstawowy interfejs iteratora.
    • __construct – konstruktor klasy. Przyjmuje jako parametr to co może zwrócić funkcja mysql_query. Może to być zasób pozwalający na iterowaie się po rekordsecie lub cokolwiek innego (w takim wypadku zakłada się, że wynik zapytania jest pusty.
    • eof – zwraca informacje czy są dostępne dane do odczytu.
    • get – zwraca pojedynczy rekord w postaci tablicy pól. Przechodzi do następnego rekordu
  • PageFooter.php – klasa generująca stopkę dokumentu – element dodawany na końcu każdej strony należącej do aplikacji. Obiekt tej klasy tworzony jest przez PageFrame w czasie tworzenia kodu strony. I zachowuje się podobnie jak panel. Zawiera dwie metody które powinny być zaimplementowane przez programistę
    • render – metoda wywoływana przez PageFrame w momencie tworzenia zawartości strony. Jako parametr przyjmuje wyjście na którym wypisujemy kod HTML dla przeglądarki.
    • accept – metoda która przyjmuje jako parametr obiekt klasy PageFrame. Jest wywoływana w momencie dodawania stopki do strony. W tej metodzie panel może zdecydować jakie inne elementy strony należy dodać – skrypty, style itp.
  • PageHeader.php – o klasa generująca nagłówek dokumentu – element dodawany na początku każdej strony należącej do aplikacji. Obiekt tej klasy tworzony jest przez PageFrame w czasie tworzenia kodu strony. I zachowuje się podobnie jak panel. Zawiera dwie metody które powinny być zaimplementowane przez programistę
    • render – metoda wywoływana przez PageFrame w momencie tworzenia zawartości strony. Jako parametr przyjmuje wyjście na którym wypisujemy kod HTML dla przeglądarki.
    • accept – metoda która przyjmuje jako parametr obiekt klasy PageFrame. Jest wywoływana w momencie dodawania nagłówku do strony. W tej metodzie panel może zdecydować jakie inne elementy strony należy dodać – skrypty, style itp.
  • PageFrame.php – Klasa implementująca całość strony. Powinna być używana do generowania każdej strony aplikacji. Jako przykład zastosowania – warto wzorować się na plikach index.html z dołączonego z archiwum. Na stronę musi być włożony panel implementujący potrzebna funkcjonalność. PageFrame definiuje pełna ramkę strony wraz z pojedynczym formularzem.
    • __construct – konstruktor klasy. Tworzy obiekt konstruując także nagłówek i stopkę strony. Ustawia elementy strony na puste.
    • setPanel – ustawia panel który będzie wyświetlany na stronie. Panel powinien być oddzielnie utworzony – metoda przyjmuje referencję do obiektu. W czase dodawania panelu – wywoływana jest na panelu metoda akcept w której panel może wołać pozostałe metody obiektu PageFrame.
    • render – metoda generująca zawartość strony na przekazanym jako parametr wyjściu.
    Pozostałe metody powinny być wołane przez panel w kontekście metody akcept.
    • setTitle - ustawia tytuł strony (widoczny w pasku tytułowym przeglądarki.
    • setResponder - ustawia adres strony będącej responderem na dane wysyłane z formularze utworzonego na bieżącej stronie.
    • addStyle - dodaje arkusz styli do strony. Należy podać tylko nazwę pliku wraz z rozszerzeniem, ale bez ścieżki. Plik będzie włączony z katalogu css.
    • addScript - dodaje plik ze skryptami w języku JavaScript do strony. Należy podać tylko nazwę pliku wraz z rozszerzeniem, ale bez ścieżki. Plik będzie włączony z katalogu js.
    • addPageFinishCall - pozwala na dodanie kodu w języku JavaScript, który będzie wywołany po załadowaniu strony (gdy wszystkie elementy będą już przygotowane).
    • addExitCode - pozwala na dodanie kodu w języku JavaScript, który będzie wywołany w momencie opuszczania strony. Zaplanowany został do zapamiętywania ustawień użytkownika w plikach cookie jeśli powinna zrobić to przeglądarka a nie serwer (można zapisać stan wyboru, rozwinięcia elementów, ostatnio edytowany element itp.).
    • addSubmitCode - pozwala na dodanie kodu w języku JavaScript, który będzie wywołany w momencie wywołania komendy SubmitCall() która powinna zastąpić wywołanie submit() dla formularza.
    • addHidden - przyjmuje swa parametry – nazwę oraz wartość która będzie umieszczona w ukrytym elemencie formularza. Przydatna rzecz gdy chcemy przekazywać dane do wykorzystania przez skrypty po stronie przeglądarki, lub by przygotować miejsce na dane które będą wysyłane przez stronę do serwera.
  • Responder.php – Responder jest klasą bazową dla stron które otrzymują dane (na przykład z formularzy), przetwarzają dane i przekazują sterowanie do innej strony. Respondery nie mają widoku, choć mogą zawierać jakiś kod realizowany po stronie przeglądarki. Ta klasa nie powinna być używana w innym kontekście niż jako klasa bazowa, w której całość funkcjonalności jest zaimplementowana w konstruktorze. Do konstruktora klasy Responder przekazujemy adres strony do której będzie przekazane sterowanie gdy działanie respondera się zakończy. Jedyną użyteczna metodą jest tu
    • addPageFinishCall która przyjmuje jako parametr kod w języku JavaScript który będzie wykonany po stronie przeglądarki. Jak na razie nie ma tu możliwości włączania zewnętrznych plików Javascript a jedynie prostych poleceń.
  • MainPanel.php – przykładowy panel aplikacji. Można się na nim wzorować pisząc własne panele które mogą być umieszczone na stronie aplikacji. Panel powinien zawierać wszystko to co na stronie jest bieżącą informacją. Panel powinien zawierać dwie metody:
    • render – metoda wywoływana przez PageFrame w momencie tworzenia zawartości strony. Jako parametr przyjmuje wyjście na którym wypisujemy kod HTML dla przeglądarki.
    • accept – metoda która przyjmuje jako parametr obiekt klasy PageFrame. Jest wywoływana w momencie dodawania panelu do strony. W tej metodzie panel może zdecydować jakie inne elementy strony należy dodać – skrypty, style itp.

css – katalog z arkuszami styli. Tu powinny byś umieszczone wszystkie pliki zawierające definicje styli.

  • style.css – zawiera podstawowe style używane przez strony zarządzające aplikacją. Zmiana tych styli lub ich usunięcie wpłynie na wygląd strony _ide oraz stron testowych

js – katalog na skrypty zawierające funkcje uruchamiane po stronie przeglądarki. W pustym projekcie zawiera wyłącznie przykładowy plik

  • empty.js – przykładowy plik – nie zawiera żadnych funkcji. W gotowej aplikacj powinien być usunięty.

graph – katalog na pliki graficzne związane z aplikacją. Tu powinny się znaleźć wszelkiego rodzaju ikonki oraz obrazki które są integralną częścią aplikacji. W pustej aplikacji zawiera tylko kilka podstawowych okonek które mogą być usunięte.

_dba – katalog zawierający pliki pozwalające na zarządzanie bazą danych aplikacji. Nie ma tu typowej strony a jedynie 'responder' uruchamiany z głównej strony _ide, a pozwalający na tworzenie, usuwanie bazy danych stowarzyszonej z aplikacją a określone w pliku config.php w głównym katalogu aplikacji. Ten katalog powinien być usunięty w wersji użytkowej.

  • index.php – strona główna – tylko składa kilka obiektów w gotową stronę respondera – może być przykładem jak budować respondery.
  • dba-framework.php –podobnie jak run-framework z głównej stronie aplikacji – definiuje ścieżki, sposób ładowania klas oraz wyjście do przeglądarki. W odróżnieniu do run-framework.php pozwala także na włączanie klas z katalogu _dba (nazwa klasy musi się zaczynać na „Dba”
  • DbaAdminResponder.php – Głowna klasa respondera. To tutaj sprawdzane jest polecenie jakie wysłano z głównej strony _ide i przekazywane jest do odpowiednich obiektów zarządzających baza danych. Warto zauważyć, że w odróżnieniu od obiektów stanowiących elementy strony w których główna funkcjonalność umieszcza się w metodzie render – w responderach główne zadanie spoczywa na konstruktorze obiektu.
  • DbaMySQLDatabaseCheck.php – klasa pozwalająca na sprawdzenie stanu bazy danych – jej metody pozwalają na sprawdzenie wersji bazy danych, jednoliterowego kodu stanu (Empty, Test, Production) oraz nazwy bazy danych – wszystkie te informacje pobierane są z tabeli Version bieżącej bazy danych aplikacji.
  • DbaMySQLDatabaseCreator.php – Klasa tworząca bazę danych. Tu programista powinien umieścić tu kod tworzące tabele w bazie danych. Przewidziane są tu dwa miejsca które programista powinien wypełnić. Tabele tworzymy korzystając z metody createTable która przyjmuje jako parametry – nazwę tabeli oraz tablicę asocjacyjną w której klucze elementów są nazwami pól, a wartości – nazwami typów tych pól. Nazwy typów definiujemy oddzielnie – w tablicy asocjacyjnej fieldTypes, gdzie nazwy typów pól są tłumaczone na określenia typów zrozumiałe dla serwera SQL. W ten sposób możemy określać typy przez określenie ich logicznej roli a nie reprezentacji w typach związanych z konkretna realizacją serwera baz danych.
  • DbaMySQLDatabaseDataCreator.php – Klasa tworząca dane w bazie. Zawiera dwie metody które powinny być wypełnione przez programistę. Jedna służy do przygotowania danych testowych, druga – do przygotowania danych które są niezbędne do rozpoczęcia pracy z nową aplikacją. Dane testowe powinny być tak przygotowane by pozwalały na sprawdzenie i zademonstrowanie całej funkcjonalności programu. Dane tworzymy przy użyciu metody insertData obiekty dbcreator. Metoda przyjmuje dwa parametry – określenie tabeli i pól zapisane w postaci tekstu w formacie „nazwa_tabeli (lista pól oddzielonych przecinkami)” oraz tablicy zawierającej wartości jakie powinny się znaleźć w nowym rekordzie. Metoda zwraca identyfikator nowo utworzonego rekordu.

_ide – katalog zawierający pliki "środowiska" – stronę pozwalająca w prosty sposób zarządzać aplikacją. Ten katalog powinien być usunięty w wersji użytkowej.

  • index.php – strona główna – tylko składa kilka obiektów w gotową stronę.
  • ide-framework.php – podobnie jak run-framework z głównej stronie aplikacji – definiuje ścieżki, sposób ładowania klas oraz wyjście do przeglądarki. W odróżnieniu do run-framework.php pozwala także na włączanie klas z katalogu _dba (nazwa klasy musi się zaczynać na „Dba”
  • IdeMainPanel.php – definiuje główny panel _ide. Całość funkcjonalności umieszczono w metodzie "render" która tworzy całość strony. Metoda akcept niczego nie robi. Pozostałe metody pomagają w uroszczeniu kodu.

_spikes – katalog na wprawki. Tu umieszczamy strony będące próbkami i eksperymentami. Wszystkie te pliki mogą być otwierane z głównej strony _ide. Ich opis należy umieścić wewnątrz komentarza /** **/ - cały taki opis pojawi się na stronie _ide. Ten katalog powinien być usunięty w wersji użytkowej.

  • example_spike.php – przykładowa strona

_tests – katalog na pliki zawierające testy. Pliki muszą mieć nazwy zaczynające się na „test_”. Pliki są przetwarzane w kolejności alfabetycznej. Wszystkie takie pliki są włączane do strony testowej a następnie uruchamiane są wszystkie funkcje których nazwa zaczyna się na „test_”. Funkcje te muszą przyjmować jako parametr obiekt klasy Tester, w którym możemy wołać metodę ‘test’. Metoda ta przyjmuje trzy parametry – tekst który jest wyświetlany w raporcie oraz dwie wartości które są traktowane jak wartość wzorcowa oraz wartość obliczona. Jeśli są identyczne – zakłada się, że test przeszedł. Jeśli są różne – test nie przeszedł a informacja o tym znajdzie się w raporcie. Katalog zawiera dwa przykładowe pliki które powinny być usunięte, a na ich miejsce powinny być przygotowane testy przygotowanej funkcjonalności. Ten katalog powinien być usunięty w wersji użytkowej.

  • conf.php – konfiguracja aplikacji na potrzeby testów – tu definiujemy wszystkie istotne parametry naszego programu, między innymi parametry połączenia z bazą danych. W testach powinniśmy korzystać z innej bazy danych niż w normalnie pracującej aplikacji, ponieważ w trakcie testów dane są zazwyczaj modyfikowane
  • tst-framework.php – podobnie jak run-framework z głównej stronie aplikacji – definiuje ścieżki, sposób ładowania klas oraz wyjście do przeglądarki. W odróżnieniu do run-framework.php pozwala także na włączanie klas z katalogu _test (nazwa klasy musi się zaczynać na „Tst”) oraz z katalogu _dba. Zawiera także definicję wyjścia testowego które może być użyte by sprawdzić czy elementy tworzą taką zawartość strony jak to załorzył programista
  • index.php – strona główna – tylko składa kilka obiektów w gotową stronę testową.
  • TstMainPanel.php – Głowna część zawierająca całą funkcjonalność w metodzie ‘render’
  • test_001_example.php – przykładowy plik z funkcją testową
  • test_002_example.php – przykładowy plik z funkcją testową