APEL core

Wiki: Baza danych

psiwik — Mon, 16 May 2011 10:04:48 GMT

Połączenie do bazy
Klasa ap_db

Wiemy już jak wyświetlić statyczny tekst w naszej aplikacji. Przydałoby się teraz abyśmy mogli wyświetlać treści dynamicznie, aby móc je modyfikować bez ingerencji w kod. Aby otrzymać taką funkcjonalność musimy podłączyć nasz system do bazy danych. Na początek spróbujmy dodać do naszej strony menu w którym możemy włączać i wyłączać z bazy poszczególne zakładki.

Po pierwsze musimy posiadać dostęp do jakiejś bazy danych. Załóżmy że mamy dostęp do bazy danych o następujących parametrach:

serwer: mojserwer.edu.pl
port: 3306
login: moj_login
hasło: moje_haslo123
nazwa bazy: mojapel_baza

Połączenie do bazy

W pliku konfiguracyjnym musimy zarejestrować połączenie do tej bazy. Robimy to w następujący sposób:

....
ap_page::setBase('default','mysql://moj_login:moje_haslo@mojserwer.edu.pl:3306/mojapel_baza/head_');
....

Pierwszy argument metody setBase to nazwa połączenia. Dzięki temu parametrowi możemy w systemie łączyć się do kilku różnych baz. Nazwy połączeń mogą być dowolne, jednak przynajmniej jedno powinno nazywać się default – oznacza to połączenie domyślne. Ostatni fragment head_ oznacza nagłówek wszystkich tabel jakich bedziemy używać we frameworku – umożliwia to łączenie frameworka z innymi aplikacjami php. Nagłówek jest całkowicie pomijany w klasach (nie uwzględniamy go tworząc nazwy pól i kluczy)

Klasa ap_db

Za obsługę baz danych odpowiada klasa ap_db. Na chwilę obecną system nie ma zaimplementowanej obsługi innego typu bazy jak mySql, jednak w przyszłości będzie taką funkcjonalność posiadał. Możemy jednak przyjąć że obiektów tej klasy używa się zawsze tak samo, niezależnie od typu bazy.

Klasa ma zaimplementowane następujące metody:

query('zapytanie sql','nazwa_połączenia');
fetch('nazwa_połączenia');
insert('nazwa_tabeli','tablica_pól','nazwa_połączenia');
update('nazwa_tabeli','nowe_wartości','warunek','nazwa_połączenia');
delete('nazwa_tabeli','warunek','nazwa_połączenia');
begin('nazwa_połączenia');
commit('nazwa_połączenia');
rollback('nazwa_połączenia');

Omówimy teraz poszczególne metody:

query

Metoda kieruje zapytanie do bazy. Standardowo jest używana do tworzenia zapytań SELECT...., możemy jednak jej użyć to wszelkiego typu zapytań. Nazwa_połączenia informuje nas do której bazy odnosi się zapytanie. Gdy parametr ten nie jest podany, zapytanie jest adresowane do bazy zdefiniowanej w połączeniu nazwanym default. Ten warunek odnosi się do wszystkich metod, więc nie będziemy go więcej podawać.

fetch

Po wykonaniu querychcielibyśmy otrzymać jakieś wyniki. Umożliwia nam to funkcja fetch która kolejno zwraca rekordy będące wynikiem zapytania. Jeśli zwrócono już wszystkie rekordy, lub wynik zapytania jest pusty, metoda zwraca null. Wyniki są zwracane w postaci tablicy asocjacyjnej w której kluczem jest nazwa pola tabeli, a wartością zawartość pola w bazie.

insert

Metoda dodaje do tabeli nazwa_tabeli nowy rekord i zwraca jego id(id to PRIMARY KEY). Dane do zapisania, czyli tablica_pól, powinna być w formie tablicy asocjacyjnej gdzie kluczem jest nazwa pola, a wartością dana jaką na tym polu chcemy zapisać.

update

Uaktualnienie rekordu w tabeli. Wartości do zapisania powinny być w tablicy asocjacyjnej, natomiast warunek może być w postaci albo tablicy asocjacyjnej, albo tekstowej.

Przykład:

// oba zapisy są równoważne

$db->update('jakas_tabela',array('poleUpdate'=>'nowa_wartość'),array('klucz'=>'id_klucza'));

$db->update('jakas_tabela',array('poleUpdate'=>'nowa_wartość'),'klucz = id_klucza');

Postać tekstowa warunku umożliwia nam wprowadzanie klauzul postaci a > b, a in (a,b,c) itp.

delete

Usuwa rekordy z bazy spełniające podany warunek. Postać warunku taka jak przy update

begin, commit, rollback

Metody służące do zapewnienia transakcyjności.

Przyjmuje się że bezpośrednie odwołania do bazy przez obiekty klasy ap_db powinny znajdować się wyłącznie w managerach i obiektach (ap_obj), jednak nie jest błędem ich użycie w innych miejscach, zwłaszcza gdy chodzi o optymalizację. Może to jednak skutkować pogorszeniem czytelności programu i późniejszymi problemami przy rozbudowie lub zmianach w aplikacji.

<<< Widok - Pierwsze kroki >>>

Wiki: Homepage

psiwik — Mon, 16 May 2011 09:58:23 GMT

Opis fameworku APEL który kiedyś miałem zrobiony na moodle

Wiki: Kontroler

psiwik — Mon, 16 May 2011 10:02:46 GMT

Parametry kontrolera
$nativeShow
$actions
Metody używane w kontrolerze

Z poprzednich lekcji wiemy już nieco o klasach występujących w APELU, zasadach tworzenia nazw tabel oraz obiektów. Pora przejść do szczegółowych opisów poszczególnych klas. Opis zrobimy na przykładzie naszego systemu mojapel którego szkielet przygotowaliśmy na pierwszej lekcji. Co zrobić aby móc cokolwiek wyświetlić na ekranie? Po pierwsze musimy zdefiniować domyślny kontroler dla naszego systemu. Zwyczajowo nazywany jest ctrl_main, tak więc nie będziemy odbiegać od tej zasady.

Parametry kontrolera

Aby dokładnie omówić działanie kontrolera, musimy zacząć od tego jak działa najważniejszy obiekt sterujący w systemie, czyli obiekt klasy ap_page zdefiniowany w pliku front/index.php. Odpowiada on za całość działania aplikacji, czyli ładowanie odpowiedniego kontrolera, renderowanie strony html, obsługę błędów i ładowania plików. Obiekt ten rozpoznaje który kontroler załadować na podstawie parametru przekazywanego w adresie URL strony, a konkretnie switch, i przekazuje do niego nazwę metody jaką kontroler ma wywołać (parametr action). W konstruktorze obiektu jest zdefiniowana tablica $this->ctrl w której kluczem jest wartość parametru switch a wartością nazwa kontrolera do załadowania. Tabela musi zawierać conajmniej jedną pozycję, i musi to być kontroler przypisany do parametru default. Zostanie on załadowany gdy wywołamy adres strony beż żadnego parametru. Przejdźmy teraz do samego kontrolera. W kontrolerze są zawarte trzy parametry które musimy wypełnić. Są to:

$defaultAction - nazwa metody jaka zostanie wywołana przy załadowaniu strony bez zdefiniowanego parametru action
$nativeShow - nazwa domyślnego widoku jaki wyświetli kontroler
$actions - tablica ze zdefiniowanymi nazwami metod które ma prawo wywołać użytkownik z parametru action
$defaultAction - na tą zmienną przypisujemy jeden z kluczy tablicy $actions. Będzie on nam definiował metodę jaka zostanie wybrana gdy w adresie URL zostanie pominięty lub nie wypełniony parametr action. Pole jest obowiązkowe.

$nativeShow

Kontrolery są odpowiedzialne za składanie stron html “do kupy”, czyli generowanie stron. Ponieważ zawsze coś musi zostać wyświetlone, każdy kontroler posiada widok natywny, który jest wypełniany treścią w zależności od wywołanej metody. Omówmy to na przykłądzie:

Każda strona internetowa musi posiadać przynajmniej taki zestaw tagów:

<html>
	<head>
	</head>
	<body>
	</body>
</html>

W nagłówku powinniśmy jeszcze umieścić informacje o kodowaniu, opis strony (czyli znaczniki meta), tytuł strony, często dodajemy informacje o stylach czy kody javascript. Dodawanie tego za każdym razem do strony jest zwykłą stratą czasu, dlatego też najwygodniej jest niezmienne części strony umieścić w jednym miejscu aby ich za każdym razem nie przepisywać, natomiast modyfikować tylko to co się zmienia. Właśnie widok natywny jest takim kontenerem który jest niezmienny, a do niego doładowywane są obiekty generujące odpowiednie fragmenty strony. Dokładnie opiszemy ten mechanizm nieco później.

$actions

Ta zmienna jest tablicą w której mamy nazwy metod uprawnionych do wywołania przez parametr action. Została ona wprowadzona w celu zabezpieczenia systemu przed próbą ataku polegającą na dopasowywaniu parametrów adresu URL. W tablicy tej kluczem jest wartość parametru action a wartością nazwa wywoływanej metody. Z reguły są one jednakowe.

Metody używane w kontrolerze

Jak już się dowiedzieliśmy wcześniej kontroler odpowiada za interakcję z użytkownikiem, i złożenie wynikowej strony html, zatem musi otrzymać jakieś dane wejściowe, dokonać na nich jakichś operacji i na końcu odpowiednio zbudować stronę do wyświetlenia. Do tych wszystkich czynności służy zestaw predefiniowanych metod:

get('param_name')
set('param_name')
addShow('show_name','position')
addMngr('mngr_name')

Metoda get pobiera wartość parametru param_name. Metoda set ustawia ją. Metoda addMngr tworzy nam nowego managera o nazwie mngr_name i zwraca do niego wskaźnik. Podobnie czyni metoda addShow z tym że dotyczy widoków i posiada parametr position który mówi nam o tym w którym miejscu widoku natywnego mamy dany widok umieścić.

Posiadając już taką wiedzę spróbujmy stworzyć własny kontroler. Tworzymy plik front/system/ctrl/main.php i umieszczamy w nim definicję klasy ctrl_main. Następnie musimy w nim określić domyślną akcję, listę metod uprawnionych oraz nazwę natywnego widoku. Przyjmijmy że domyślny widok będzie nazywał się show_main a domyślna metoda show. W tym momencie nasz kontroler powinien wyglądać mniej więcej tak:

/**
 *  przykładowy kontroler
 */
class ctrl_main extends ap_ctrl implements iface_ctrl {
	protected $defaultAction = 'show';
	protected $nativeShow = 'show_main';
	protected $actions = array (
		'show' => 'show'
	);
	public function show() {
	
	}
}

Jak widać ciało metody show jest jeszcze nie wypełnione, jednak jeszcze za mało umiemy aby móc je wypełnić.

<<< Obiekty - Widok >>>

Wiki: Obiekty

psiwik — Mon, 16 May 2011 10:01:40 GMT

Zasady nazewnictwa
1. Baza danych
2. Klasy
Typy obiektów

Zasady nazewnictwa

Aby w pełni wykorzystać mechanizmy zaimplementowane we frameworku musimy przestrzegać kilku zasad:

Baza danych

Tabele w bazie powinny być nazywane w formacie nazwa_tabeli. Każda z tabel powinna posiadać klucz PRIMARY o nazwie nazwaTabeliId. Jest to bardzo ważne gdyż zachowując taki format obiekty frameworku są w stanie automatycznie rozpoznać klucz główny tabeli i zautomatyzować operacje na bazie. Jeśli nie zachowamy takiego formatu nazewnictwa tabel, operacje odczytu i zapisu do tabeli będziemy musieli definiować sami.

Klasy

Nazwa każdej klasy powinna być w formacie moja_nazwa_klasy, a jej definicja powinna znajdować się w katalogu system/moja/nazwa/klasy.php. W przypadku gdy nie zachowamy takiego formatu będziemy musieli jawnie używać instrukcji include bądź require.

Typy obiektów

Do tworzenia aplikacji w oparciu o framework APEL używa się czterech typów obiektów. Są to:

kontrolery (dziedziczą po ap_ctrl)
widoki (dziedziczą po ap_show)
managery (dziedziczą po ap_mngr)
obiekty (dziedziczą po ap_obj)

Dodatkowo zostały zaimplementowane klasy tzw. systemowe służące np. do obsługi przekazywanych przez serwer zmiennych lub mechanizmu cache (ap_var oraz ap_cache). Ich omówieniem zajmiemy się później, teraz zajmijmy się typami obiektów opisanymi powyżej.

Kontrolery (obiekty klasy ap_ctrl)

Obiekty tego typu odpowiadają za interakcję z użytkownikiem. Odbierają parametry i dokonują operacji na obiektach. Są również odpowiedzialne za umieszczanie widoków na stronie. Kontrolery implementujemy w katalogu system/ctrl. Tworząc nową aplikację powinniśmy na początku zdefiniować kontroler domyślny, czyli taki który będzie się uruchamiał przy wejściu na stronę główną naszego serwisu. Zwyczajowo nazywa się go ctrl_main i jego definicję umieszcza się w pliku system/ctrl/main.php.

Widoki (obiekty klasy ap_show)

Widoki generują nam fragmenty strony html. Każdy kontroler ma swój widok domyślny, nie ma jednak wymogu aby dla każdego z nich był inny. W szczególności wszystkie kontrolery mogą mieć ten sam widok domyślny i będzie to najczęściej spotykana sytuacja. Widoki można w sobie zagnieżdżać (dokładnie ten proces omówimy w dalszej części kursu). Do każdego widoku jest przypisany szablon smarty z którego generuje on kod HTML. Implementujemy je w katalogu system/show.

Managery (obiekty klasy ap_mngr)

Managery są obiektami odwołującymi się już bezpośrednio do bazy danych, jednakże służą raczej do operacji grupowych na tabelach. Przy użyciu managerów możemy filtrować i wyszukiwać dane z bazy. Każdy manager ma przypisany do siebie obiekt klasy ap_obj który zawiera informację o tabeli w bazie danych, dlatego też praktykuje się nazywanie managerów tak aby jednoznacznie kojarzyły się z obiektami i odpowiadającymi im tabelami. Trzymanie się tej zasady bardzo ułatwia zrozumienie kodu i może ograniczyć ewentualne błędy (od razu możemy skojarzyć jakiej tabeli i jakiego obiektu dotyczy manager na podstawie tylko jego nazwy). Managery implementuje się w katalogu system/mngr

Obiekty (obiekty klasy ap_obj)

Najprościej mówiąc pojedynczy obiekt tej klasy odpowiada pojedynczemu rekordowi w tabeli bazy danych. Obiekty tej klasy mają zaimplementowane automatyczne dodawanie oraz aktualizację informacji w bazie. Dobrą praktyką jest nazywanie obiektu podobnie jak nazywa się tabela w bazie do której się on odnosi, czyli tabeli o nazwie moja_tabela powinien odpowiedać obiekt obj_moja_tabela.

Klasy systemowe

Część operacji taka jak komunikacja z bazą danych, z cache czy też wysyłanie e-maili została zaimplementowana w tzw. klasach systemowych. Ich używanie nie jest wymagane, jednakże stanowią one spójną całość z resztą frameworku i ich użycie jest bardzo zalecane. Są to klasy ap_bd, ap_cache czy ap_mail

<<< Opis frameworku - Kontroler >>>

Wiki: Opis frameworku

psiwik — Mon, 16 May 2011 10:00:16 GMT

Czym jest framework
Struktura plików
config
out
skin
system
index.php

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.

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

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.

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

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.

skin

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)

system

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

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:

<?
/**
 * Exceptions
 */
class system_exception extends ap_exception {

}
?>

index.php

Teraz zajmijmy się głównym plikiem naszego systemu, czyli index.php. Na samym początku tworzenia naszej aplikacji powinien wyglądać tak:

<?
/**
 * 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();
}

?>

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:

ap_sys::PROFILE_TEST 
ap_sys::PROFILE_WORK

W zależności od tego którą przypiszemy, taki typ pliku konfiguracyjnego zostanie włączony do aplikacji.

Aby zmienić layout naszej strony wystarczy na zmienną $skin przypisać nazwę katalogu w jakim go zdefiniowaliśmy.

Tak oto dobrnęliśmy do końca przygotowań. Możemy przystąpić do implementacji naszego systemu.

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 >>>

Wiki: Pierwsze kroki

psiwik — Mon, 16 May 2011 10:05:28 GMT

Znamy już metodę podłączenia się do bazy, jak również zasady nazewnictwa tabel i obiektów. Możemy więc przystąpić do tworzenia managerów i ob(j)ektów. Ponieważ managery są bardziej skomplikowane i wykorzystują obiekty (obj) ich omówienie zostawimy na później. Teraz przystąpimy do utworzenia przykładowego obiektu.

Na poprzedniej lekcji zdefiniowaliśmy połączenie do bazy, więc nie musimy się już tym martwić. Załóżmy że chcemy stworzyć i obsługiwać tabelę w której będą się znajdować pozycje menu naszej strony. Nazwijmy ją mojapel_menu. Powinna mieć ona 4 pola:

mojapelMenuId - (klucz, PRIMARY KEY)
itemActive – flaga informująca o tym czy dana pozycja menu jest aktywna
menuName – tekst wyświetlany na danej pozycji menu
menuLink – link do którego przenosi nas dana pozycja menu

Gdy stworzyliśmy tabelę tworzymy obiekt jej odpowiadający. Nazwiemy go obj_mojapel_menu. Będzie zaimplementowany w katalogu system/obj/mojapel/menu.php. Do prawidłowego działania potrzebuje zdefiniowanego parametru $tableName który informuje do jakiej tabeli jest on przypisany. Dodatkowo musimy zdefiniować funkcję validate() która jest odpowiedzialna za sprawdzenie błędów przed zapisem rekordu do bazy. Ostatnią rzeczą są wpisane definicje pól z bazy. Klasa może wyglądać następująco:

class obj_mojapel_menu extends ap_obj implements iface_obj {
	protected $tableName = 'mojapel_menu';

	protected $fields = array (
		'mojapelMenuId',
		'itemActive',
		'menuName',
		'menuLink,
	);
	protected function validate() {
		if (empty($this->menuName)) {
			throw new system_exception('Nie wypełniono nazwy menu');
		}
	}
}

Klasa jest już gotowa do użytku. Przy użyciu obiektów tej klasy możemy standardowo pobierać pojedyncze rekordy z bazy, jak też zapisywać w nich zmiany. Obiekty same rozpoznają czy zapis jest modyfikacją, czy dodaniem nowego rekordu.

Ustawienie jednego z pól w obiekcie wykonuje się funkcją setNazwaPola. Przykładowo w naszym obiekcie będzie to np.setItemActive. Po dokonaniu zmian musimy wywołać metodę save, która zapisze zmiany do bazy. Ostatnią ciekawą funkcjonalnością obiektów jest wczytanie wszystkich pól danego rekordu z bazy. Realizuje to metoda getDetails();

<<< Baza danych

Wiki: Widok

psiwik — Mon, 16 May 2011 10:03:48 GMT

Parametry widoku i klasy abstrakcyjne
Metody używane w widoku
Zagnieżdżanie widoków

Na poprzedniej lekcji, przy omawianiu kontrolerów wspomnieliśmy o widokach, a w szczególności o widoku natywnym kontrolera. Na dzisiejszej lekcji przybliżymy sobie dokładniej pojęcie widoku, jego działanie i sposób definiowania. Jak już wiemy, framework APEL generuje strony html w oparciu o mechanizm szablonów smarty. Nie będziemy go tutaj opisywać - dokładny opis tego mechanizmu możemy znaleźć na stronie http://www.smarty.net/. Definicje szablonów (co też już omawialiśmy) znajdują się w katalogu front/skin/default/templates/. Co więc trzeba do napisania własnego widoku?

Parametry widoku i klasy abstrakcyjne

Do poprawnego zdefiniowania widoku potrzebny jest nam tylko jeden parametr. Nazywa się on $template i jest to nazwa szablonu smarty który dany widok będzie generował. Jeśli szablon nie jest zdefiniowany bezpośrednio w katalogu templates tylko po drodze są jakieś podkatalogi, musimy podać do niego ścieżkę. Przy nazwie szablonu pomijamy rozszerzenie pliku (.tpl).

Potrzebna jest nam jeszcze definicja funkcji init(). W niej umieszczamy kod potrzebny do przygotowania danego fragmentu strony. Nie będzie błędem pozostawienie tej metody pustej, i powierzenie przygotowania kontrolerowi, ale może to prowadzić do nadmiernej rozbudowy kontrolera, jak również konieczności wielokrotnego powtarzania kodu, zwłaszcza gdy widoku używamy więcej niż raz. Najprościej ten problem wyjaśnić na przykładzie:

Załóżmy że widok zawiera element <select> w postaci listy rozwijanej. Wybrany element jest przekazywany przez parametr selectedOption i selectedOption2. Możemy więc zostawić metodę init() w widoku pustą i wszystko przerzucić do kontrolera, wtedy kod kontrolera i widoku będzie wyglądał tak: (przyjmujemy że widok będzie użyty w dwóch metodach kontrolera: show_1() i show_2()

/**
  * kontroler
  */
	....
  public function show() {
	$options = array (
		'1' => 'jeden',
		'2' => 'dwa',
		'3' => 'trzy'
	);
	$show = $this->addShow('show_main');
	$opt = $this->get('selectedOption');
	$show->assign('options',$options);
	$show->assign('selectedOptions',$opt);
  }
	.....
  public function show_2() {
	$options = array (
		'1' => 'jeden',
		'2' => 'dwa',
		'3' => 'trzy'
	);
	$show = $this->addShow('show_main');
	$opt = $this->get('selectedOption2');
	$show->assign('options',$options);
	$show->assign('selectedOptions',$opt);
  }
	.........	 /**
  * widok
  */	
  public function init() {
  }

Jak widzimy cały kod musieliśmy powtórzyć dwukrotnie. Teraz to co jest niezmienne przerzućmy do widoku. Wtedy kod będzie wyglądał tak:

/**
  * kontroler
  */
	....
  public function show() {
	$show = $this->addShow('show_main');
	$opt = $this->get('selectedOption');
	$show->assign('selectedOptions',$opt);
  }
	.....
  public function show_2() {
	$show = $this->addShow('show_main');
	$opt = $this->get('selectedOption2');
	$show->assign('selectedOptions',$opt);
  }
	.........	 /**
  * widok
  */	
  public function init() {
	$options = array (
		'1' => 'jeden',
		'2' => 'dwa',
		'3' => 'trzy'
	);
	$this->assign('options',$options);
  }

Jak widać można zaoszczędzić sobie sporo pisania.

Metody używane w widoku

Predefiniowane metody używane w widoku to:

assign(param_name,param_value)
addMngr('mngr_name')
addShow('show_name','position')
initPosition('position')

assign jest to tak naprawdę metoda z mechanizmu smarty, nie wymaga więc opisu; addMngr i addShow działają identycznie jak w przypadku kontrolera, natomiast metoda initPosition jest odpowiedzialna za inicjalizację pozycji position. O co chodzi z tą inicjalizacją dowiemy się za chwilę.

Zagnieżdżanie widoków

Jak już wiemy, kontroler ma za zadanie poskładać z widoków kompletną stronę html. Polega to na tym, że “zbiera” od różnych widoków fragmenty wygenerowanego kodu i umieszcza w swym widoku natywnym. Aby mógł to zrobić w szablonie widoku natywnego musimy określić pozycje na których będą się znajdować te fragmenty kodu. Nie są one niczym innym jak zmiennymi smarty. Dodając do widoku, bądź kontrolera kolejny widok musimy określić jego pozycję. W przypadku gdy tego nie zrobimy system automatycznie przypisuje mu pozycję “main”. Gdy będziemy chcieli na jednej pozycji dodać kilka widoków, będą one “sklejone” w kolejności dodawania. Może się zdarzyć że mamy zdefiniowaną w szablonie pozycję, ale żaden widok nie zostanie jej przypisany. Nie jest to dużym problemem dla PHP, ale z uwagi na bardzo rygorystyczną kontrolę błędów we frameworku, otrzymamy wyjątek. Aby się on nie pokazał należy użyć wspomnianej wcześniej metody initPosition. Spowoduje ona zainicjowanie pozycji na pustą wartość i dzięki temu nie otrzymamy komunikatu o błędzie. Ponieważ kolejne widoki można dodawać bezpośrednio w innym widoku, można je w sobie zagnieżdżać praktycznie do dowolnej głębokości.

Ponieważ wiemy już jak tworzyć widoki możemy rozwinąć naszą testową aplikację. Poprzednio stanęliśmy na definicji kontrolera. Teraz zdefiniujmy jego widok natywny. W kontrolerze zapisaliśmy, że nazywa się on show_main. Tworzymy więc plik front/system/show/main.php i wypełniamy go treścią. Od razu zakładamy że szablon będzie znajdował się w pliku front/skin/default/templates/main.tpl

/**
 * widok natywny dla kontrolera ctrl_main
 */
class show_main extends ap_show implements iface_show {

	protected $template = 'main';

	public function init() {

	}
}

Pozostało nam wypełnić szablon main.tpl. Zróbmy to np. w taki sposób:

<html>
<head>
<title>
Moja pierwsza strona APEL
</title>
</head>
<body>
{$main}
</body>
</html>

Jak widać zdefiniowaliśmy jedną pozycję o nazwie main. Szablon nie wymaga żadnych dodatkowych danych więc funkcję init() możemy pozostawić pustą.

W tym momencie umiemy już definiować kontrolery i widoki, co jest wystarczającą wiedzą do stworzenia strony powitalnej naszego systemu. Co trzeba więc zrobić?

po pierwsze: stworzyć widok z tekstem strony powitalnej
po drugie: dodać ten widok w kontrolerze

A więc do dzieła: zaczynamy od widoku:

/**
 * widok z tekstem strony powitalnej
 */
class show_welcome extends ap_show implements iface_show {

	protected $template = 'welcome';

	public function init() {

	}
}

Zapisujemy go w pliku front/system/show/welcome.php

Teraz tworzymy plik front/skin/default/templates/welcome.tpl i zapisujemy w nim tekst powitania. W naszym wypadku wystarczy

Witam w mojej pierwszej aplikacji napisanej przy użyciu frameworka APEL

Teraz dodajemy widok w kontrolerze ctrl_main. Robimy to w ten sposób

....
public function show() {
	$show = $this->addShow('show_welcome','main');
}

Jeśli niczego nie zepsuliśmy po wejściu na stronę główną naszego serwisu powinna ukazać się nam nasza strona powitalna.

<<< Kontroler - Baza danych >>>