./ (katalog główny) – zawiera główne pliki
aplikacji – strony. W pustym projekcie – znajdują się pliki
- 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.
conf – konfiguracja
aplikacji – tu definiujemy wszystkie
istotne parametry naszego programu, między innymi parametry połączenia
- DatabaseConfiguration.php –
Definiujemy tu tylko dane połączenia bazy do bazy danych. Muszą one
odpowiadać używanemu serwerowi oraz aktywnemu użytkownikowi tego serwera.
Ponadto można tu określić czy baza danych jest współdzielona z innymi
aplikacjami oraz określić identyfikator kontekstu – liczbę która jest
używana przy dostępie do danych – bu odróżnić dane konkretnej aplikacji
lub kontekstu użycia aplikacji.
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” lub zawierać „_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.
Metody przyjmują jako parametr nazwę modułu. Każdy moduł może być w
innej wersji (moduły powinny być tak zaprogramowane by można je było
stosować zamiennie)
- databaseName – zwraca status
danych zadanego modułu w postaci tekstu
- databaseVersion – zwraca
wersje modułu w postaci tekstu
- databaseStatus – zwraca
status zadanego modułu w postaci jednoliterowego kodu
(Empty, Test, Production)
- listDbModules –
zwraca rekordset zawierający listę wszystkich zainstalowanych modułów
- DbaMySQLDatabaseCreator.php – Klasa
tworząca bazę danych oraz w miarę potrzeb – na wypełniającą bazę
danymi testowymi lub początkowymi.
- __construct – Konstruktor skanuje
katalog _dba w poszukiwaniu plików definiujących elementy bazy danych
dla poszczególnych modułów (pliki zawierające klasy o nazwie
XXXXX_DbaYYYYYDatabaseCreator; gdzie XXXXX jest dowolna nazwą
a YYYYY – nazwą typu serwera (zdefiniowaną w pliku konfiguracyjnym).
Plik powinien zawierać klasę o nazwie XXXXX_DbaDatabaseCreator
(zgodnie z konwencją nazw – typ serwera jest dodawany automatycznie
do wszystkich nazw klas zawierających ‘Database’).
- createTable – Tworzy tabelę w
bazie danych. Pierwszym parametrem jest nazwa tablicy, drugim –
tablica asocjacyjna w której kluczami są nazwy pól a wartościami –
typy. Typy trzeba wcześniej zdefiniować w tablicy asocjacyjnej w
której klucze są nazwami typów używanymi w definicji tablic a
wartościami – typy używane przez serwer bazy danych. W klasie
DbaDatabaseCreator są zdefiniowane typy potrzebne do skonstruowania
tablicy Version, w której przechowywane są dane dotyczące wersji
zainstalowanych modułów. W czasie tworzenia tabeli nie trzeba
tworzyć pola identyfikatora rekordu, który jest dodawany zawsze
(pole ma tają nazwę jak tabela + „Id” i jest typu integer autonumber).
Metoda zwraca string zawierający definicję tabeli, która może być
użyta podczas dodawania danych metodą insertData.
- insertData – Pozwala na wstawienie
danych do tabeli. Metoda przyjmuje dwa parametry: pierwszym jest
określenie tabeli do której wstawiane są dane, drugim – tablica
zawierająca wartości. Definicja tabeli składa się z nazwy tabeli
oraz listy (zapisanej w nawiasach) nazw pól których dotyczą dane.
Drugi parametr to po prostu tablica zawierająca wartości które
mają być dodane do tabeli. Nawet jeśli dodajemy wartość pojedynczego
pola – musimy je umieścić w tablicy.
- query – Metoda pozwalająca na
bezpośredni dostęp do bazy danych – w zasadzie nie powinno być
to potrzebne, ale czasem trzeba.
- updateDatabaseState – Pozwala na
korektę danych w tabeli zawierającej wersje poszczególnych modułów.
Jako parametry przekazujemy kod stanu, jego opis oraz nazwę modułu
którego dane są modyfikowane. Moduł musi być wcześniej zainstalowany.
Funkcja może być wołana w czasie tworzenia danych, ale nie musi –
statusy są zapisywane przez funkcje tworzące dane.
- createDatabase – Tworzy bazę danych.
Zakłada tabele przeznaczoną do pamiętania wersji modułów i woła dla
wszystkich znalezionych przez konstruktor metod tworzących strukturę
danych dla poszczególnych modułów. Dla każdego modułu zakłada także
odpowiedni wpis w tablicy Version.
- removeDatabase – Usuwa bazę
danych. Woła po kolei metodę usuwające tabele z wszystkich modułów
oraz usuwa wpisy z tabeli Version. Baza jest usuwana tylko jeśli
w pliku konfiguracyjnym jest określona jako własna. Jeśli nie –
usuwane są tylko dane i struktury danych modułów tej konkretnej aplikacji.
- fillWithInitData – Wypełnia bazę
danymi początkowymi przygotowując bazę do pracy. Woła metodę
fillWithInitData każdego z modułów aktualizując wpisy w tabeli
‘Version’.Aktualizaje są wykonane tylko dla modułów które nie są
zainicjowane (status E).
- fillWithTestData – Wypełnia bazę
danymi testowymi które powinny służyć to sprawdzenia całej
dostępnej funkcjonalności. Wiła metodę fillWithTestData każdego
z modułów aktualizując wpisy w tabeli ‘Version’.Aktualizaje są
wykonane tylko dla modułów które nie są zainicjowane (status E).
W czasie tworzenia bazy ładowane są klasy o nazwach
XXXXX_DbaDatabaseConstructor i wołane są metody w niej zdefiniowane.
Przykładowy plik tworzący dane dla modułu w bazie danych znajduje
się w pliku Example_DbaMySQLDatabaseConstructor.
- Framework_DbaMySQLDatabaseCreator.php –
Klasa tworząca bazę danych oraz w miarę potrzeb – na wypełniającą bazę
danymi testowymi lub początkowymi. Metody tej klasy są dostępne w
modułach tworzących bazę. Obiekt konstruujący bazę jest przekazywany
do wszystkich metod klasy XXXXX_DbaDatabaseConstructor.
Gotowe moduły powinny wzorować się na tej klasie.
- $moduleName – Nazwa modułu – będzie
używana w tabeli Version do oznaczania modułu.
- $moduleVersion – Wersja
modułu – będzie umieszczona w tabeli Vesrion – będzie oznaczać
wersję modułu po jego instalacji.
- $fieldTypes – Definicja typów pól
do użycia w tym konkretnym module. W poszczególnych modułach
możemy definiować takie same nazwy typów przypisując im różne nazwy.
Typów zdefiniowanych w DbaDatabaseCreator nie trzeba definiować – jest
do nich dostęp.
- createTables – Tworzy tabele dla
danego modułu. Nie trzeba zapisywać wersji i stanu modułu – wystarczy
dodawać tabele. Do metody przekazywane jest parametr – referencja do
obiektu DbaDatabaseCreator – którego metody można tu wołać.
- deleteTables – Usuwa tabele założone
przez createTables. Podobnie jak w przypadku poprzedniej metody –
nie są potrzebne żadne dodatkowe operacje.
- fillWithInitData – Wypełnia tabele
danymi testowymi. Wypełniać powinniśmy tylko te tabele dotyczące
danego modułu.
- fillWithTestData – Wypełnia tabele
danymi początkowymi. Wypełniać powinniśmy tylko te tabele dotyczące
danego modułu.
Plik powinien być usunięty w gotowym projekcie
i zastąpiony typowym dla aplikacji.
_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 a umieszczone tu pliki
w gotowym projekcie poinny być wymienione na właściwe dla tego projektu.
- 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.
- DatabaseConfiguration.php – Konfiguracja
bazy danych dla celów testowych. Wszystkie inne pliki konfiguracyjne są
ładowane z katalogu ../conf ale konfiguracja bazy danych określana jest
oddzielnie dla środowiska testowego.
- 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_construction_of_page.php –
Testy klas PageHeader, PageFooter, PageFrame i MainPanel sprawdzające
czy generowany kod HTML jest zgodny z założeniami.
- test_002_responder.php –
Sprawdzenie czy Respondek tworzy właściwy kod
- test_003_control.php –
Sprawdzenie czy obiekt klasy Control czyta dane z wejścia
- test_004_database_connection.php –
Sprawdzenie poprawności połączenia z bazą danych. Plik powinien
być usunięty w gotowym projekcie i zastąpiony typowym dla aplikacji
– sprawdzającym strukturę danych oraz jej wypełnienie danymi testowymi.
|