Pobranie frameworka
Pobierz środowisko tutaj i rozpakuj w docelowym folderze aplikacji na serwerze www. Przykład: Jeśli rozwijasz aplikację lokalnie w oparciu o środowisko XAMPP, to rozpakuj środowisko w folderze htdocs środowiska. W pakiecie znajduje się folder amelia, który zawiera framework oraz opartą na nim prostą aplikację Hello World. Jeśli wszystko zostało poprawnie rozpakowane to po uruchomieniu serwera Apache środowiska aplikacja powinna działać pod adresem http://localhost/amelia/.
Zmiana nazwy folderu aplikacji
Kolejnym krokiem jest modyfikacja folderu amelia na inną, odpowiadającą nowo tworzonej aplikacji (np mojaaplikacja). Aby wszystko działało poprawnie należy odpowiednio ustalić konfigurację w pliku config.php. Po zmianie folderu z amelia na mojaaplikacja należy zmienić pozycję $conf->app_root w następujący sposób:
$conf->app_root = '/mojaaplikacja/public'.
W szczegółowym opisie konfiguracji możesz zobaczyć przykładowy plik oraz dowiedzieć się więcej na temat konfiguracji aplikacji w docelowej domenie (na serwerze zdalnym).
Po zmianie folderu oraz wpisu w konfiguracji opisującego lokalizację, aplikacja będzie dostępna pod nowym adresem http://localhost/mojaaplikacja/.
Tworzenie aplikacji
Rozwijanie aplikacji internetowej powinno rozpocząć się od projektu. Przynajmniej prostego. Jeśli jest to aplikacja bazodanowa, a najczęściej tak jest, to należy również wcześniej zaprojektować bazę danych, która będzie repozytorium informacji przechowywanych w projektowanym systemie.
Niniejsza instrukcja pokazuje ogólny proces tworzenia systemu i na tym etapie pomija kwestie bazy danych.
Dodawanie akcji do routingu i jej obsługa
Sterowanie w aplikacji internetowej opartej na Amelii odbywa się poprzez obiekt routera, który na podstawie adresu URL kieruje żądanie przeglądarki do określonej metody kontrolera. Zatem proces dodawania obsługi akcji można rozbić na trzy proste kroki:
- dodanie akcji do routera
- stworzenie klasy kontrolera
- stworzenie metody akcji w kontrolerze
Przykład
Załóżmy, że chcemy dodać akcję o nazwie nowa, która po wywołaniu ma spowodować jakieś konkretne działanie po stronie naszej aplikacji i wygenerować jakiś widok html. Zatem URL, który tę akcję wywoła w naszym przypadku aplikacji lokalnej na serwerze Apache, będzie wyglądał następująco: http://localhost/mojaaplikacja/public/nowa, w którym część początkowa wskazuje na publiczny folder odwołań do naszego systemu internetowego (http://localhost/mojaaplikacja/public/), a ostatni element wskazuje na akcję nowa.
1. Dodanie akcji do routera
Pierwszy krok polega na umieszczeniu wpisu w skrypcie routing.php o następującej treści:
Utils::addRoute('nowa', 'NowyKontroler');
cały skrypt routing.php po zmianie będzie wtedy wyglądał mniej więcej tak:
<?php
use core\App;
use core\Utils;
App::getRouter()->setDefaultRoute('hello'); #default action
//App::getRouter()->setLoginRoute('login'); #action to forward if no permissions
Utils::addRoute('hello', 'HelloCtrl');
Utils::addRoute('nowa', 'NowyKontroler');
Cały skrypt definiuje zatem już dwie akcje - domyślna hello oraz właśnie dodana akcja nowa. Zwróćmy uwagę, iż akcja hello jest również zdefiniowana jako akcja domyślna, czyli taka, która ma się wyświetlić domyślnie gdy nazwa akcji nie zostanie podana w URL, lub podana akcja nie będzie istnieć. Oczywiście możemy ją zmienić na dowolną inną istniejącą akcję.
2. Stworzenie klasy kontrolera
Routing dla akcji nowa jest już zdefiniowany. Odtąd przy próbie jej wywołania (http://localhost/mojaaplikacja/public/nowa) router spróbuje utworzyć obiekt kontrolera NowyKontroler oraz wywołać jego odpowiednią metodę. Teraz jeszcze się tak nie stanie. Gdyby spróbować wywołać akcję wpisując w przeglądarce url http://localhost/mojaaplikacja/public/nowa, otrzymalibyśmy błąd informujący, iż nie istnieje klasa NowyKontroler w przestrzeni nazw app\controllers.
Zatem należy utworzyć plik NowyKontroler.class.php (lub NowyKontroler.php) w podfolderze app/controllers oraz zdefiniować w nim nową klasę:
<?php
namespace app\controllers;
class NowyKontroler {
}
3. Stworzenie metody akcji
Sama klasa nie rozwiązuje jeszcze problemu, ponieważ router w powyższej klasie będzie szukał metody akcji do wywołania. Gdyby w tym momencie spróbować wywołać akcję nowa w przeglądarce za pomocą wcześniej podanego URL, to otrzymalibyśmy błąd informujący o braku metody akcji w klasie NowyKontroler.
Domyślnie metoda akcji ma przedrostek action_ oraz dalsza część jej nazwy odpowiada nazwie akcji. Zatem w przypadku akcji nowa metoda akcji kontrolera przyjmie nazwę action_nowa. Zbierając wszystko w całość, zawartość pliku NowyKontroler.class.php będzie następująca:
<?php
namespace app\controllers;
class NowyKontroler {
public function action_nowa() {
}
}
Teraz wywołanie akcji w przeglądarce zakończy się bez błędu. Metoda zostanie wywołana, jednak niczego nie wykonuje, stąd przeglądarka pokaże pustą stronę.
Tym samym zakończyliśmy trzy kroki: stworzenia wpisu w routingu, stworzenia klasy kontrolera oraz odpowiedniej metody akcji. Dalsze etapy związane są z wprowadzaniem kodu w metodzie akcji.
Obsługa akcji
Metoda akcji uruchamiana jest w odpowiedzi na żądanie przeglądarki, które kierowane jest do odpowiedniego kontrolera i metody poprzez router. Zatem proces tworzenia aplikacji to dodawanie kolejnych kontrolerów/metod i ich odpowiednie oprogramowanie. Dalsza część tego krótkiego wprowadzenia pokaże jakie narzędzia są dostępne w amelii aby w prosty sposób wygenerować widok (odpowiedź) dla przeglądarki.
Najprostszym sposobem wygenerowania odpowiedzi może być użycie instrukcji echo. Pozwoli to sprawdzić, czy rzeczywiście nasza metoda akcji działa. Zatem niech metoda akcji przyjmie następującą postać:
public function action_nowa() {
echo "Nowa akcja wywołana !";
}
Teraz, przy próbie wpisania w przeglądarce URLa http://localhost/mojaaplikacja/public/nowa, w oknie powinna ukazać się treść Nowa akcja wywołana !
Oczywiście stoi to w sprzeczności z zasadą, iż kontroler nie powinien generować widoku. Amelia na te potrzeby posiada zintegrowaną bibliotekę Smarty. Stąd spróbujmy pokazać jak wygenerować widok w oparciu o tę bibliotekę.
Generowanie widoku
Aby wygenerować widok HTML wykorzystując szablon Smarty wystarczy użyć głównej klasy Amelii, czyli core\App. Poniżej przedstawiono całość kodu kontrolera, gdzie można zauważyć frazę use wskazującą interpreterowi lokalizację klasy App (domyślnie, bez podania całej nazwy klasy z podprzestrzeniami nazw, interpreter zakłada że użyta klasa należy do tej samej przestrzeni jak ta w której kod się znajduje - w tym wypadku app\controllers):
<?php
namespace app\controllers;
use core\App;
class NowyKontroler {
public function action_nowa() {
App::getSmarty()->display("nowy_widok.tpl");
}
}
Naturalnie, należy jeszcze utworzyć wskazany plik widoku nowy_widok.tpl. W Amelii wszystkie pliki widoków są wyszukiwane automatycznie w podfolderze app/views oraz app/views/templates - dedykowanym dla szablonów ogólnych, po których szczegółowe mogą dziedziczyć (aby dowiedzieć się więcej o dziedziczeniu szablonów zobacz dokumentację Smarty). Zatem nasz plik nowy_widok.tpl zapiszemy w app/views, a jego postać niech będzie następująca:
<!DOCTYPE HTML>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="pl" lang="pl">
<head>
<meta charset="utf-8"/>
<title>Nowa akcja | Amelia framework</title>
</head>
<body>
Widok wygenerowany w odpowiedzi na nową akcję !
</body>
</html>
Teraz wywołanie nowej akcji w przeglądarce (http://localhost/mojaaplikacja/public/nowa) spowoduje wywołanie powyższego widoku.
Narzędzia dostępne w kontrolerze
Metody akcji do ułatwienia realizacji swoich zadań (pobieranie parametrów, wykorzystanie bazy danych, wykorzystanie sesji ...) mogą wykorzystywać pozostałe pomocnicze klasy Amelii. Więcej na ich temat zapisano tutaj. Szczególnie pomocny będzie również opis klasy walidatora, która w prosty sposób pozwala pobrać, zweryfikować i przetworzyć parametry pochodzące z różnych źródeł.
Narzędzia dostępne w widokach Smarty (pliki .tpl)
Przy tworzeniu widoków w oparciu o Smarty zapewne bardzo pomocna będzie oficjalna dokumentacja tego silnika (Amelia wykorzystuje wersję 3 tej biblioteki). Szczególnie w przypadkach bardziej złożonych (łatwiej wyszukać rozwiązania interesujących zagadnień związanych ze Smarty poprzez Google, w większości przypadków poprowadzi do odpowiedniej sekcji na tej stronie).
Poza standardową funkcjonalnością silnika w widokach Smarty, środowisko Amelia dodaje kilka pomocnych obiektów i funkcji. Pierwszym jest obiekt konfiguracji, który jest dostępny w widokach poprzez zmienną obiektową $conf (dokładny opis obiektu konfiguracji i jego pól umieszczono tutaj). Kolejnym jest obiekt komunikatów $msgs. Poniższy przykład pokazuje przykładowy widok - niech będzie to wcześniej opisany nowy_widok.tpl - który wykorzystuje wspomniane obiekty do generowania linków oraz wyświetlenia listy komunikatów:
<!DOCTYPE HTML>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="pl" lang="pl">
<head>
<meta charset="utf-8"/>
<title>Nowa akcja | Amelia framework</title>
</head>
<body>
<h3>Generowanie adresów (z użyciem obiektu konfiguracji)</h3>
Link bezwzględny do strony akcji hello: <a href="{$conf->action_url}hello"> link </a>
<br/>
Link względny do strony akcji hello: <a href="{$conf->action_root}hello"> link </a>
<br/>
<h3>Adresy można również generować w Amelii za pomocą dedykowanych funkcji url oraz rel_url:</h3>
Link bezwzględny do strony akcji hello: <a href="{url action='hello'}"> link </a>
<br/>
Link względny do strony akcji hello: <a href="{rel_url action='hello'}"> link </a>
<br/>
Wyświetlenie listy komunikatów:
{if $msgs->isInfo()}
<ul>
{foreach $msgs->getMessages() as $msg}
<li>{$msg->text}</li>
{/foreach}
</ul>
{/if}
</body>
</html>
Przykład w kontrolerze HelloCtrl oraz hello.tpl aplikacji startowej (po pobraniu Amelii) pokazuje jak przekazywać zmienne do widoku oraz jak generować komunikaty i je wyświetlać.
W widoku można również używać narzędzi Amelii dostępnych w jej klasach. Przykładowo, aby sprawdzić czy użytkownik jest w danej roli - w celu wyświetlenia/ukrycia części widoku - można napisać (w pliku .tpl):
...
{if \core\RoleUtils::inRole('admin')}
... //coś co ma się wyświetlić dla roli admin
{/if}
...