File: Polish-punFramework.txt

punFramework ver. 0.9 dla punBB 1.3-dev

Autor: Piotr Malinski (riklaunim@gmail.com)
Licencja: GPL
www.php.rk.edu.pl
www.cms.rk.edu.pl

	Wstęp
####################
punFramework jest prostym frameworkiem  bazującym na wzorcu MVC - Model-Widok-Kontroler umożliwiającym łatwe,
przejżyste i proste tworzenie aplikacji dla forum punBB. punFramework nie umożliwia modyfikacji samego forum ale umożliwia
tworzenie nowych komponentów w pełni z nim zintegrowanych (np. modułu news, artykułów czy dowolnych innych)

	Instalacja
####################
- skopiuj mvc.php, debug.php i punFramework do katalogu z punBB 1.3-dev
- nadaj chmod 777 lub 666 na debug.php jeżeli serwer działa pod kontrolą linuksa/unixa
- punFramework WYMAGA PHP5 i nie będzie działać z PHP4!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

	Opis Frameworka
####################
Wszystkie twoje komponenty dostępne są poprzez plik mvc.php. Można zmienić nazwę tego pliku na dowolną.

Kontrolery
---------------------
- Kontrolery to pliki php umieszczone w punFramework/controllers/
- Każdy plik zawiera klasę PHP, która dziedziczy klasę punController
- Nazwa pliku musi być taka sama jak nazwa klasy + .php
- Szkieletowy kontroler to:

class test extends punController
{
public function index()
	{
	return 'witaj świecie';
	}
}

- Każdy moduł np. "newsy" powinny mieć własny kontroler
- Każdy kontroler powinien mieć oddzielne metody dla poszczególnych akcji/widoków (pokaż newsy, dodaj newsa, usuń newsa)
- Metody powinny zwracać (return) dane niż je wyświetlać


Mapowanie URLi
-------------------------
punFramework używa prostego mapowania:

mvc.php?c=NAZWA_KONTROLERA
mvc.php?c=NAZWA_KONTROLERA&m=NAZWA_METODY
mvc.php?c=NAZWA_KONTROLERA&m=NAZWA_METODY&var1=foo1&va2=foo2

- NAZWA_KONTROLERA to nazwa kontrolera
- NAZWA_METODY to nazwa metody kontrolera, którą chcemy wywołać
- Nazwa kontrolera i metody może zawierać TYLKO znaki alfabetu - duże i małe liter. !!!!!!!!!!
- Jeżeli nie podasz nazwy metody wtedy domyślnie zostanie wywołana metoda index()


Dostępne zmienne punBB
------------------------------------------
$this->pun_user - tablica $pun_user z danymi o bierzącym użytkowniku
$this->db - obiekt $db operujący na bazie danych
$this->pun_config - tablica $pun_config zawierająca konfigurację forum
$this->pun_url - tablica $pun_url zawierająca URLe do standardowych elementów forum
$this->lang_common - tablica $lang_common zawierająca pospolite frazy-tłumaczenia
możesz użyć print_r($TABLICA); by zobaczyć zawartość i strukturę danej tablicy

Widoki
---------------------------------------
Widoki to niejako szablony i powinny zawierać kod HTML odpowiedzialny za wygląd danego elementu.
- Widoki zapisujemy jako pliki PHP w punFramework/views/
- By w kontrolerze załadować widok wystarczy:

$wynik = NAZWA_KONTROLERA::load_view('NAZWA_WIDOKU', array());
$wynik = test::load_view('hello', array('user' => 'Jon Doe'));

Gdzie NAZWA_WIDOKU to nazwa pliku widoku bez .php
- Drugi argument to tablica asocjacyjna z danymi jakie mają być przekazane do widoku
- W widoku tablica ta dostępna jest pod zmienną $data
- Powinieneś używać styli/klas CSS punBB :)


Modele
------------------------------------
Modele są podobne do kontrolerów, dziedziczą punRoot a ich zadaniem jest przechowywanie logiki operującej na bazie danych - samych
zapytań z niezbędnym kodem dodatkowym. Używanie Modeli (jak i widoków) jest opcjonalne lecz zaleca się ich stosowanie.
- Szkielet modelu wygląda tak:

class posts extends punRoot
{
public function get_all_posts()
	{
	return posts::query("SELECT * FROM posts");
	}
}

- Model zapisujemy jako punFramework/models/NAZWAKLASY.php
- Każda operacja na bazie danych typu "pokaż newsy" , "usuń newsy" powinna mieć własną metodę
- Możesz użyć $this->db - standardowego obiektu punBB do operowania na bazie danych
- Możesz też używać NAZWAKLASY::query - wrappera, który zwróci tablicę asocjacyjną z wynikami dla zapytań SELECT oraz wykona i zwróci True dla pozostałych
- Wrapper ::query wygeneruje wyjątek w przypadku błędu zapytania (patrz "obsługa błędów")
- By załadować model w kontrolerze wystarczy:

$object = NAZWA_KONTROLERA::load_model('NAZWA_MODELU');


$news = test::load_model('news');
$news->get_latest_news();

- $object w tym przykładzie to obiekt klasy kontrolera gotowy do wykorzystania.


Inne Pomocniki
--------------------------------------
- W kontrolerach możesz użyć:

NAZWA_KONTROLERA::render_template('tytuł', 'treść');

Co zwróci dane wstawione w standardową komórkę punBB:

<div class="pun-block">
	<h2><span>TYTUŁ</span></h2>
	<div class="pun-content">
		TREŚĆ
	</div>
</div>

- Oprócz tego masz dostęp do:

NAZWA_KONTROLERA::is_admin() # zwróci True jeżeli bierzący użytkownik to Admin (ID grupy - 1)
NAZWA_KONTROLERA::is_user() # zwróci True jeżeli bierzący użytkownik jest zwykłym użytkownikiem (ID grupy - 4)
NAZWA_KONTROLERA::check_login() # zwróci True jeżeli bierzący użytkownik jest zalogowany
metody zwrócą False w przypadku nie spełnienia warunku.

Obsługa Błędów
---------------------------------------
- Gdy framework napotka na błąd wygeneruje wyjątek, który zostanie przechwycony przez niego.
- Pełen komunikat błędu zostanie zapisany do debug.php
- Skrypt wyświetli zwykły ekran punBB informujący że coś się nie udało
- By zobaczyć pełen komunikat błędu otwórz w edytorze tekstowym debug.php
- Do obsługi własnych błędów również używaj wyjątków a punFramework obsłuży je tak samo jak własne :)

IF($foo != $bar)
	{
	throw new Exception('$bar jest różne od $foo');
	}

Wykonywanie kodu zostanie przerwane w miejscu wywołania wyjątku, punFramework przejdzie do zapisania komunikatu i wyświetlenia wiadomości użytkownikowi
Zobacz http://www.php.net/exceptions for info about exceptions


"Jesteś Tutaj"
--------------------------------
By zmienić treść obok tej frazy edytuj mvc.php, a dokładniej:

$page_nav = 'punFramework | <a href="index.php">Go to Forum</a>';

Wstawiając własną treść