Execution of The API Class

An API in Agile Toolkit splits the whole execution of the application into 2 parts. In the first part, the API initializes the objects, coupling them with proper models. The second part is the execution: the API will cause objects to query the database, iterate through results, produce and render output.

Agile Toolkit objects never output anything directly. Instead, they insert their output into their parent's template. The API sends the combined output to the user's browser through "echo".

Initialization

Depending on which API you use, it will initialize several sub-components which call Controllers. When you extend an API class, you should re-define the init() function and add initialization in there - things like connecting to the database, adding controllers, etc.

ApiFrontend will automatically initialize Logger() which makes error logging more bearable.

Layouts

A Layout is a region in the shared template (shared.html), which is parsed by the API class. If the region is defined, then a corresponding layout function is called.

The first and most significant layout element is "Content". Content will determine which page is requested and proceed with all the logic of page initialization. However if "Content" is not present in the API template, the page will not be initialized.

You can add additional layout elements. For example, calling addLayout('Menu') inside api->init() will instruct API to call layout_Menu() method if tag <?Menu?> is found when parsing the template.

This approach can be used to initialize various things such as sidebars, toolbars and widgets, if they exist inside the API template. You can manipulate different templates from inside the defaultTemplate() function of your API.

Initializing Auth and checking Auth

While you can also execute auth->check() inside init(), we recommend performing auth-check inside an initLayout() function:

    function init(){
        
parent::init();
        
$this->add('BasicAuth')->allow('john','secret');
    }
    function 
initLayout(){
        
$this->auth->check();
        
parent::initLayout();

        
// Replace "login" link region with logout/user info
        
if($this->auth->isLoggedIn()){
            
$this->add('View',null,'UserMenu','view/usermenu/loggedin')
                ->
set($this->auth->get()));
        }
    }

Did you notice that the call to auth->check() is done before calling parent::initLayout()? That's because we do not want any pages to be initialized before authentication is done.

Form Submission

Form submission is normally handled after all other views are initialized. When form is submitted, the rendering phase is skipped also. Submission occurs only if a form with a proper ID has been found.

Rendering

Agile Toolkit provides support for partial rendering of views based on 3 criteria: cut_page - outputs only page's content, cut_object - outputs content of a certain object and cut_region - outputs content of a certain region. This is explained in more depth later

Interrupting initialization phase

It is possible to interrupt execution of the init() phase. This might be necessary if you wish to avoid any more objects being added to some view. To terminate execution of init:

// from inside View

// if product is not selected:

if(!$product){
    
$this->add('ProductSelector');
    throw 
$this->exception('Stop showing page until product is selected','StopInit');
        
// throws Exception_StopInit
}

This approach should be used only if calling "return" is not sufficient - that is: from either a view which has been placed inside page, or if your page extends another, common abstract page.