Documentation

Working with Addons/Modules/Views

Creating an addon class

The cornerstone of any toKernel framework application are the addon classes that you develop.

Each addon resides in its own directory tree and has several components some of which are mandatory. To illustrate this part of the tutorial, let's assume we are developing the 'articles' addon.

The Addon class

Each addon has exactly one addon class, usually instanciated once. This can be seen as the controller part of the well-known MVC paradigm.

This class must reside in the addon/lib directory (either at the framework or application level) and must have a name of the form addon_name.addon.php, for example articles.addon.php
The first few lines of the addon class must follow the following model:

/* Restrict direct access to this file */ defined('TK_EXEC') or die('Restricted area.'); class articles_addon extends addon { public function __construct($params, $config) { parent::__construct($params, $config); } }

Of course, in your own code, you should replace the name "articles_addon" by your own class name.

The class must always have the '_addon' suffix.

Defining our addon classes as an extension of the general addon object brings the benefits of OOP, namely the inheritance of methods and attributes from the parent object which is provided by the framework.

This inheritance mechanism can be further exploited by extending an existing addon class.

For example, if we want to extend our articles object, we can create an articles_ext_addon as follows:

/* Restrict direct access to this file */ defined('TK_EXEC') or die('Restricted area.'); class articles_ext_addon extends articles_addon { public function __construct($params, $config) { parent::__construct($params, $config); } }

This is mainly useful if the articles addon is defined at the framework level and we need to add a few specific attributes and methods or change the behavior of a method.

In this case, the articles_ext object will be created in the /application/addons/articles/lib/articles.addon.php file while the parent articles oject will be contained in the /framework/addons/articles/lib/articles.addon.php file.

Creating addon actions

The addon we created in the previous step would not be very useful without enriching it with attributes and methods. Adding attributes is done following the standard PHP object rules, with the usual scope properties.

There are however some special rules to obey for methods.

We can declare a method in four different ways, depending on whether we want the method to be callable from outside the application or not. In the former case, the method is said to be an "action". Furthermore, toKernel distinguishes three different type of actions:

CLI callable actions, AJAX callable actions and HTTP callable actions.

Let's start with the HTTP callable actions. In this case, the addon and action names are specified in the URL passed by the browser.
For example, we could have an URL like:

http://www.example.com/articles/show_article/id/78/display/full

where the 'articles' is the addon name and 'show_article' is the action. The remaining part of the URL are the action parameters (see the url lib and running in HTTP mode for further explanation of the parameters)

In this case, the framework will retrieve the addon and action name (i.e. articles and show_article) and, after some standard processing, will ultimately execute the corresponding method in the addon class.

For HTTP actions, the name of the method must be the name of the action prefixed by 'action_'. So, in our example, the action_show_article in the articles class will be executed.
For example:

public function action_show_article($params = array()) { $article_id = $params['id']; $display_type = $params['display']; }

The $params array contains the URL parameters. Alternatively, you may also access the parameters via the url lib params() method as follows:

$article_id = $this->lib->url->params('id'); $display_type = $this->lib->url->params('display_type');

See url library

The AJAX callable actions are somewhat different from the previous case.

First, the method name must be prefixed by 'action_ax_'.

So, it is not possible in toKernel to have the same method accessible both via HTTP and via AJAX, which increases the overall application security.

Another point of attention is the way parameters are passed to the server. If you are using a Javascript framework such as jQuery on the client side, chances are that you would be tempted to pass parameters via a query string and let the framework handle the AJAX call.

Unfortunately, this will result in strange behavior since the default call method is likely to be GET and the usual PHP query string cannot be parsed by toKernel. In order to avoid these problems, we recommend you use the POST method with your AJAX calls. In this case, toKernel will not receive a query string to parse but you can get POST values using $this->lib->filter->post('my_value'); using 'filter' library.
An AJAX callable action could be:

public function action_ax_show_article($params = array()) { // Get value, from GET request: http://www.example.com/articles/show_article/id/55 $id = $params['id']; // or - $id = $this->lib->url->params('id'); // Get value, from POST request: http://www.example.com/articles/show_article/ $id = $this->lib->filter->post('id'); }

See also: filter class library

The CLI callable methods have their name prefixed by 'cli_'.

Otherwise, the method is almost identical to what you would write for an HTTP action.

This type of action is called from the command line using a command like:

php /index.php --addon articles --action show_article --id 78 --display full

The corresponding method would look like:

public function cli_show_article($params = array()) { // Some functionality as explained above. }

The parameter array $params behave just like in the HTTP case, but if you want to retrieve the parameters manually, you must use the cli lib instead as follows:

$article_id = $this->lib->cli->params('id'); $display_type = $this->lib->cli->params('display_type');

See also: CLI class library

Finally, an addon class may have methods that are not callable actions. These methods cannot be used directly from outside the application and are not designed to interface with the outer world.
For example:

public function show_article($param1, $param2) { /* ... */ }

can't be accessed directly using any of the three previous methods.

Notice that the method name doesn't have any prefix.

Regular PHP scoping rules apply, so since this method is public, it is accessible from other parts of the application using a reference to the addon instance.
For example:

$this->lib->addons->articles->show_article($param1, $param2);

If the method is restricted or private, this statement is invalid but the method can still be called from another method of the addon using:

$this->show_article($param1, $param2);