Actions  

Following standard MVC conventions, actions are the meat of !TheBugGenie's controllers. This is where most of the processing code for your given action will occur, and at the end usually a template is displayed. Actions are called automatically by !TheBugGenie's routing system, based on route definitions in the route configuration or custom routing rules defined by modules.

Structure of an controller  

An action method lives in the module's controller class, in the classes/actions.class.php file. This file contains a class extending TBGAction, providing all the necessary functionality to handle basic controller tasks relative to the module being invoked.

Actions  

Whenever a request is made, !TheBugGenie will route this request to the matching controller, and invoke the matching action for this route.

Action methods  

As described in the routing documentation all action methods are named runActionName (for examples, see the routing documentation). An action method is invoked automatically by the routing and action subsystem, and only one parameter is passed to it, namely the Request object which caused the execution of this action (read more about request objects in the requests documentation.

All actions are expected to either render their own basic output (used mostly with ajax requests and json responses) or return nothing, allowing the template file to be loaded and parsed. Therefore, an action will usually return nothing (null). In the opposite situation, where the action returns something (or outputs something), the corresponding template will not be loaded or parsed, and the output returned or displayed will be handed to the response object and passed to the user.

Action templates  

If the action method does not have any output returned or echoed, the template for the corresponding action + format will be invoked. All actions are supposed to have a corresponding template named <lowercaseactionname>.<format>.php (the lowercase action name does not include the "run" prefix used for the action method name). As such, an action method called runIndex requires the following template:

 templates/index.html.php

For other formats, you can switch the <format> part of the template file name to any other supported format, such as f.ex. json:

 templates/index.json.php

If the response format is set to json before the template is loaded, this will make !TheBugGenie use the json template instead. For more information about manipulating responses, see the response documentation.

Executing pre- and post actions  

For a controller, you can specify a preExecute() that will be invoked for all actions in that controller. If a preExecute() method exists in a controller, this method will be called for all requests and internal redirects before the actual action is called. Similar to the pre-action, you can create a postExecute() function in your controller for common steps that needs to be taken after any action has been run. The preExecute() method is passed the $request object as well as the name of the function (action) that is being called.

Note: The pre- and post-actions are not used to connect or disconnect from databases, or similar - the framework handles this. However, a good example can be found in the project module, where the preExecute() function is used to set the project context whenever a project route is detected.

Common controller actions  

The !TBGAction class which all controllers must extend implements methods and functionality covering many basic scenarios. These include rendering text, json and custom output, retrieving template/component output, http forwarding to different urls, internal redirects to a different action and some common http response shortcuts.

Forwarding  

You will often have to forward the request to a new url, such as after having manipulated a post request. Several methods are available:

• TBGAction::forward($url, $code = 200) - unconditionally forwards a request to a given url. Accepts an http status code for custom status code forwarding.
• TBGAction::forward403($message = null) - forwards the user to !TheBugGenie's custom "access denied" page. A message can be passed to provide the user with further information. This message will be shown formatted as an error on the "access denied" page.
• TBGAction::forward403unless($condition, $message = null) and TBGAction::forward403if($condition, $message = null) - same as above, but can be used for simple one-line conditional forwarding.

After invoking any of these methods will, your action will not continue to execute.

class sampleActions extends TBGAction
{
    public function runSample(TBGRequest $request)
    {
        $this->forward('http://www.google.com');
    }
}

Redirects  

You can redirect to a different action if desired, using the TBGAction::redirect($action) method. You are only allowed to redirect to actions in the same module. The redirected action will then be invoked as if it was not redirected, together with the request object, just as if it was invoked directly.

class sampleActions extends TBGAction
{
    public function runSampleRedirect(TBGRequest $request)
    {
        $this->redirect('sample2');
    }

    public function runSample2(TBGRequest $request)
    {
        echo 'i am here';
    }
}

404 responses  

If you want to return a 404 response, you can use the TBGAction::return404() method. You need to return directly with the return value for this method for a proper 404 response to be issued. If you want to present a message to the user with the 404 error, you can pass this to the TBGAction::return404() method.

class sampleActions extends TBGAction
{
    public function runSampleNotFound(TBGRequest $request)
    {
        return $this->return404('could not find this');
    }
}

Note: be aware that some web servers / web browsers will intercept 404 messages and rewrite them or display a replacement message or webpage.

Rendering templates or components  

Sometimes, the single thing you want to do in the action is to render the output of a template or a component. If you don't want to create a separate template file just for including a component or template - or if you have some condition-based decision-making as to which template or component is going to be rendered - you can use the TBGAction::renderTemplate($template, $parameters = array()) or TBGAction::renderComponent($component, $parameters = array()) functions. You need to return with the output value from these calls for this functionality to function properly.

class sampleActions extends TBGAction
{
    public function runSampleTemplate(TBGRequest $request)
    {
        return $this->renderTemplate('main/userdropdown', array('user_id' => 1);
    }

    public function runSampleTemplate2(TBGRequest $request)
    {
        return $this->renderComponent('main/teamdropdown', array('user_id' => 1);
    }
}

Note: You cannot render regular templates this way. To do this, you need to redirect to the action with the templates. For more information about how templates and components works in general, see the templates documentation.

If you want to perform some processing, replacements or similar for the output generated by a template or component, you can retrieve that output in a variable (instead of it being outputted) using the TBGAction::getTemplateHTML($template, $parameters = array()) or TBGAction::getComponentHTML($component, $parameters = array()) functions.

class sampleActions extends TBGAction
{
    public function runSampleTemplate(TBGRequest $request)
    {
        return str_replace('%username%', 'elvis', $this->getTemplateHTML('main/userdropdown', array('user_id' => 1));
    }

    public function runSampleTemplate2(TBGRequest $request)
    {
        return str_replace('%team%', 'team america', $this->getComponentHTML('main/userdropdown', array('user_id' => 1));
    }
}

For all the template and component functions, template and/or component names can be prefixed with '<modulename>\', allowing you to load a template or component located in another module. Again, for more examples and information, see the templates documentation.