Development - Application Components


General

Components represent the extensive add-ons. They typically add completely new or different functionality and extends the overall framework possibilities. ApPHP Framework built upon components which are objects written to a specification. Using component mainly involves accessing its properties and raising/handling its own events. Each component extends the CComponent base class and may use views similary to controllers.

Rendering in Components - passing data to the View

Application components come to replace using of global functions and co-called "include" files with HTML/PHP code. Now you may create a component class, that uncludes a static methods - this will allow you to avoid using if include files with a lot of global functions. Also, you may create a component that's incorporates some spesific logical functionality of your web application, including retrieving infromation from database.

For output purposes you may use two general ways: return the HTML that is generating by method of component class (write it directly in code) or use views presentation similary to controllers work.

Here the example of direct returning of generated code:
$output = '<ul><li>Link 1</li><li>Link 2</li>...</ul>';
return $output;
In this case you have to use following syntax, where method renderContent() accepts a name of the view file, placed in a views directory protected/views/components/:
// Hint: don't try to work with A::app()->view->render(), it's reserved for controllers use only
A::app()->view->renderContent('leftmenu');
Remember!
1. Some systems may be case sensitive, so make sure that argument of renderContent() is exactly same with the file name it reffers. 2. This method renderContent() works only on application level, it doesn't work on modules level.


Configuraion File

For each application you have to define a list of components the will be loaded for your application, where all important parameters are define. For example:
<?php
// Application components
'components' => array(
    'blogMenu' => array('enable'=>true, 'class'=>'BlogMenu'),
    'blogHelper' => array('enable'=>true, 'class'=>'BlogHelper'),        
),
For each application you may define a Bootstrap component, that will be loaded by the framework automatically to provide possibility to run procedure before any other code. For example, you may use Bootstrap component to set the "timezone" ot local date settings, etc.

Directory Structure

Below you may see a common structure of the component directory:

Code Examples

Phisically application controller represents a class that extends CComponent class. If you don't use this class for storing static methods only, it's recommended to define class constructor and init() methods like in example below:
<?php
class BlogMenu extends CComponent
{    
    /**
     * Class constructor
     * @return void
     */
    public function __construct()
    {
        parent::__construct();
    }

    /**
     * Returns the static model of the specified AR class
     */
    public static function init()
    {
        return parent::init(__CLASS__);    
    }
    
    // Other class code here
}    
This is an example of component class that represents a library of static methods.
<?php
class BlogHelper extends CComponent
{
    public static function strTruncate($string, $maxLength)
    {
        $string = substr($string, 0, $maxLength);
        $string = substr($string, 0, strrpos($string, ' '));
        return $string;
    }
    
    // Other class code here
}