File: punFramework.txt

punFramework ver. 0.9 for punBB 1.3-dev

Author: Piotr Malinski (riklaunim@gmail.com)
License: GPL

	Introduction
#################
punFramework is a very simple MVC (Model-View-Controller) framework incorporated in punBB forum.
It is designed as a tool allowing to add additional components to the forum like news, articles or other php script.
punFramework can't modify punBB itself, it add extra pages with your code. The MVC design pattern allows you to
create modules in a clean, unified and easy way.

	Instalation
#################
- copy mvc.php, debug.php and punFramework folder to your punBB folder
- chmod 777 or 66 debug.php if you use unix/linux OS (the file needs to be writable)
- punFramework REQUIRES PHP5. It won't work with PHP4

	Usage
#################
All your code (modules) is accessed using mvc.php. You can rename the file to any name you want.

Controllers
------------------------
- Controllers are located in punFramework/controllers/
- Each controller is a PHP class that inherits punController class.
- Filename must be the same as the class name, Class news would be saved as news.php
- A class skeleton would look like this:

class test extends punController
{
public function index()
	{
	return 'hello world';
	}
}

- Each module should have its own controller
- Each controller class method is responsible for a certain page like "show news" "add news", "delete news"
each of those examples should be methods of the controller class.
- Class should return content to display rather than echo it.

URL Router
-------------------------
punFramework uses simple url router:

mvc.php?c=CONTROLLER_NAME
mvc.php?c=CONTROLLER_NAME&m=METHOD_NAME
mvc.php?c=CONTROLLER_NAME&m=METHOD_NAME&var1=foo1&va2=foo2

- CONTROLLER_NAME is the name of the controller (for example "news" will call news controller form punFramework/controllers/news.php).
- METHOD_NAME is a name of a method from the controller.
- controller and method names may only contain alphabet character! small and BIG letters may be used
- If you don't specify a METHOD_NAME framework will try to call "index" method by default.

Available punBB variables
------------------------------------------
The controllers have access to:
$this->pun_user - $pun_user array with user data
$this->db - the $db object for database operations
$this->pun_config - $pun_config array with config data
$this->pun_url - $pun_url array with urls to common places
$this->lang_common - $lang_common array with common translation string.
you can use print_r(The array); to see array content

Views
---------------------------------------
Views should contain all the look and feel of your modules - they are templates. Each view must be saved as a NAME.php file, and it can contain PHP code.
- To load a view in a controller you use:

$return = CONTROLLER_NAME::load_view('VIEW_NAME', array());
$return = test::load_view('hello', array('user' => 'Jon Doe'));

- VIEW_NAME is the view filename without .php.
- views are saved in punFramework/views/
- view is returned, not displayed
- Second argument is optional - an associative array with key => value which will be passed to the view.
- Passed array is available in views under $data variable ($data['key'] will show your data assigned for that key)
- You should use punBB styles as much as possible


Models
------------------------------------
Models are classes similar to Controllers (inherit punRoot) but they should contain only methods that use the database (like add, edit, delete entries).
Use of models (or views) is optional but in the end will make your modules easy to modify and to extend.
- Skeleton of a model would look like this:

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

- You save models in punFramework/models as CLASSNAME.php
- Each database operation should have its own method.
- You can use $this->db - the standard punBB object for database operations
- You can use also a wrapper (available in controllers and models) CLASSNAME::query inherited from punRoot/punController
- ::query("SQL QUERY") wrapper will return an associative array for all SELECT queries and for non-Select it will execute the query and return true.
- The wrapper will raise an exception on any error (see error handling)

- To load model in a controller use:

$object = CLASSNAME::load_model('MODELNAME');

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

- CLASSNAME is the name of the controller class
- MODELNAME is the name of the model class
- $object - under this variable you will have the model class object ready to use


Other Helpers
--------------------------------------
- In controllers you can use:

CLASSNAME::render_template('title', 'content');

Which will return 

<div class="pun-block">
	<h2><span>TITLE</span></h2>
	<div class="pun-content">
		CONTENT
	</div>
</div>

A generic punBB "box"

- You can also quickcheck users state:

CLASSNAME::is_admin() # returns True if current user is Admin (group ID 1), else - False
CLASSNAME::is_user() # returns True if current user is a normal user (group ID 4), else - False
CLASSNAME::check_login() # returns True if current user is logged in

Error handling
---------------------------------------
When a framework encounters an error it will raise an Exception - a nice error handling "thing" which will be caught by the framework
- error page will be displayed and the Exception message will be saved to debug.php (open it in a editor to get the full error log)
- In your controllers you should use Exceptions for error handling, for example:

IF($foo != $bar)
	{
	throw new Exception('$bar doesn\'t match $foo');
	}

The code will stop executing in the place of the exception generation. punFramework will catch it and show the error message etc.
See http://www.php.net/exceptions for info about exceptions


"You Are here"
-------------------------------------
To edit text near those words edit mvc.php, row with:

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

Insert your desired content :)