Documentation
Working with Addons/Modules/Views
Usage of addons
We have seen how to set up the different components of an addon class and how these were called either from outside or internally.
Much remains to be said about the various methods each of these component objects inherit from their parent class provided by the framework.
In this page we will assume we are working with a web application that is set up as follows:
the web root directory path is /var/www/
the toKernel framework is located at /var/www/framework/
the application instance is located at /var/www/application/ and is reachable using the url http://www.example.com
We also assume we have developed an addon called articles
Addon class (controller)
Each addon object that we develop inherits from the addon object provided by the framework. This parent class is found at framework/kernel/addon.class.php
Let's examine each of this object methods and see how we can use them.
string app_path()
Returns the path of the addon.
Example:
$this_addon_path = $this->app_path();
will return "/var/www/application/addons/articles/" when called from anywhere in the articles addon.
The path of other addons can be obtained by calling the app_path method of that other addon instance. A reference to this instance is provided by the addons class library (See detailed discussion...)
For example:
$users_addon_path = $this->lib->addons->users->app_path();
will return "/var/www/application/addons/users/" when called from any addon of this application.
string app_url()
Returns an url with the full path to reach the addon root directory.
Example:
$this_addon_app_url = $this->app_url();
will return "http://www.example.com/application/addons/articles/"
This method is useful if you need to reach some files specific to the addon which you have added to the addon directory structure.
For example, let's assume you have a special Javascript set of functions that you want to use in the pages generated by your addon and that you have stored them in a file located in .../articles/js
You can then get the script's url with:
$this_addon_js_file_url = $this->app_url() . 'js/my_addon_functions.js
string config(string $item [, string $section])
Returns the configuration value for key $item
Assuming we have a config.ini file like:
....
picture=pine_tree.jpg
....
[Format]
orientation=landscape
....
We can access the value of these parameters using:
$pic=$this->config('picture');
$orientation=$this->config('orientation', 'Format');
Accessing values from other addons config.ini file is possible by using the reference to these other addons provided by the addons class library.
For example:
$this->lib->addons->users->config('quota', 'Options');
will return the value of the parameter 'quota' in the section 'Options' in the config.ini file of the 'users' addon.
See: ini class library for more information about ini file management.
string id()
Returns the addon id i.e. its name
Example:
$id = $this->id();
will return 'articles'
string language(string $item [, string value1 ][, string $valueN])
Returns the language translation value for key $item.
Example:
$message = $this-language('hello');
$welcome_message = $this-language('hello', 'John', 'Smith');
See Language management.
object load_module(string $id_module [, array $params = array()][, bool $clone = false)
Loads the addon's module and returns a reference to this instance.
$id_module is the name of the module
$params is an array of parameters that is passed to the object constructor
$clone is a boolean that indicates whether a new instance of the object should be created or not.
By default, modules are assumed to obey the singleton paradigm, meaning only one instance of the object can ever exist. If the $clone parameter is set to true, the object is cloned if an instance already exists and the reference to the new object is returned.
If the paramter is set to false (or omitted) the object will be instanciated is it doesn't exist yet and a reference to this newly created or already existing object is returned.
Example:
$pa = array('id' => 55, 'offset' => 2);
$backend = $this->load_module('backend', $pa, true);
Since the third argument is true, a new instance of the 'backend' module will be created and the method will return this new object.
The module class defines a magic __get method which will make the developer's life easier by allowing modules to be loaded automatically.
For example:
$backend = $this->backend;
This syntax is equivalent to
$backend = $this->load_module('backend');
meaning the 'backend' module will be instanciated if needed and the singleton object will be assigned to $backend.
string load_template([string $template])
Loads the template file with name $template and returns its content.
If the template name is omitted, the name of the addon's action is used instead.
$buffer = $this->load_template('show_article');
object load_view(string $file [, array $params = array()])
Loads the view file and returns a view object instance initialized with the view file.
Example:
$view = $this->load_view('show_article');
$view->subject = $article_subject;
echo $view->run();
In this code fragment, the first line creates a new view object which has the .../articles/views/show_article.view.php file attached. The second line "magically" sets the view object 'subject' attribute to some value and the third line will render the view file contents and output it.
The default path used by the load_view() method is .../articles/views/ but you can create subdirectories of your liking if you want. In this case, you have to pass the (relative) path to the view file as the first argument in the method call.
Example:
$view = $this->load_view('backend/show_controls');
If this case, the view will be read from .../application/addons/articles/views/backend/show_controls.view.php or .../framework/addons/articles/views/backend/show_controls.view.php
The load_view() method accepts a second argument which allows the use of a simplified syntax to display variables in the view.
This second argument is an array and the keys of this array can be used in the body of the view as {.key}
When such a syntax is found while rendering the view, the whole group will be replaced byt hte value of the corresponding key in the parameter array.
For example, if we have:
$array = array('name' => 'John', $surname => 'Smith');
$view = this->load_view('show_name', $array);
and the view file is:
<p>Hello {.name} {.surname}</p>
The view's run() method will produce:
<p>Hello John Smith</p>
Alternatively, you can "magically" set view attributes values in the addon or module and then use these values in a more classical way like:
<p><?php echo $this->subject; ?></p>
or:
<p><?=$this->subject;?></p>
as universally allowed in PHP 5.4
bool loaded_from_app_path()
Returns true if the addon was loaded at the application level and return false if it was loaded at the framework level.
bool module_exists(string $id_module [, bool $custom_only = false])
If the second argument is true, returns true if the module exists in the addons module subdirectory at the application level.
If the second argument is false or omitted, returns true if the module exits in the addons module subdirectory either at the application or framework level.
Returns false in the other cases.
string path()
Returns the path from which the addon was loaded.
If the addon was loaded from the application level, the "/var/www/application/addons/articles/" string will be returned.
If the addon was loaded from the framework level, the "/var/www/framework/addons/articles/" string will be returned.
string tk_path()
Returns the path of the addon in the framework directory.
Please note this method doesn't check for the addon presence in the framework directory and the result will be the same whether the addon exists or not in that directory.
Example:
$path = $this->tk_path();
will return "/var/www/framework/addons/articles/"
string url()
Returns the url with the full path from which the addon was loaded.
If the addon was loaded from the application level, the "http://www.example.com/application/addons/articles/" string will be returned.
If the addon was loaded from the framework level, the "http://www.example.com/framework/addons/articles/" string will be returned.
string tk_url()
Returns the url with the full path of the addon in the framework directory.
Please note this method doesn't check for the addon presence in the framework directory and the result will be the same whether the addon exists or not in that directory.
Example:
$url = $this->tk_url();
will return "http://www.example.com/framework/addons/articles/"