Controllers

SuiteCRM follows the MVC (Model-View-Controller) pattern and as such has the concept of controllers. The controller is responsible for making changes to the Model as well as passing control to the view as appropriate. SuiteCRM has the concept of actions which are actions that will be taken by the controller. Let’s take a look at a SuiteCRM URL:

Example 7.1: Example SuiteCRM URL

example.com/index.php?module=Accounts&action=index

In this (rather boring) example we see that the module is Accounts. This will determine which controller to use and then call the index action on that controller.

SuiteCRM will first look for the controller in custom/module/<TheModule>/controller.php. If this is not found then next module/<TheModule>/controller.php will be checked. Finally if neither of these controllers exist then the default controller will be used. The default controller can be found in include/MVC/Controller/SugarController.php.

Customising controllers

Ordinarily the default controller handles the request and delegates to the appropriate views etc. However custom controllers can be used to add or alter functionality. Let’s look at adding a new action.

In the first instance we will have to add our custom controller. This will vary slightly depending on the nature of the module.

Custom module

In this case we can place the file directly into our module. You should create a new file (if it doesn’t exist) at modules/<TheModule>/controller.php. The contents will look similar to:

Example 7.2: Creating a custom controller for a custom module

<?php
if(!defined('sugarEntry') || !sugarEntry) die('Not A Valid Entry Point');
class <TheModule>Controller extends SugarController
{

}

Pre-existing modules

For pre-existing modules you should add the controller to
custom/modules/<TheModule>/controller.php.

The contents of this file will vary depending on whether you wish to extend the existing controller (if it exists) or create your own version completely. It is usually best to extend the existing controller since this will retain important logic. You should note the naming convention here. We name the class
Custom<TheModule>Controller.

Here we don’t extend the existing controller or no such controller exists:

Example 7.3: Creating a custom controller for an existing module

<?php
if(!defined('sugarEntry') || !sugarEntry) die('Not A Valid Entry Point');
class Custom<TheModule>Controller extends SugarController
{

}

Alternatively we extend the existing controller. Note that we are requiring the existing controller:

Example 7.4: Creating a custom controller for an existing module with an existing controller

<?php
if(!defined('sugarEntry') || !sugarEntry) die('Not A Valid Entry Point');

require_once 'modules/<TheModule>/controller.php';

class Custom<TheModule>Controller extends <TheModule>Controller
{

}

Adding the action

Now we can add a new action to our controller. Actions are created as methods on the controller with the name action_<actionName>. For example, to create a new action called ‘echo’ we could create the following method in one of the controllers we have created above. This can then perform whatever logic that is needed. In our example we will log the REQUEST and simply redirect:

Example 7.5: Adding a custom controller action method

public function action_echo(){
  $GLOBALS['log']->debug("Echo called with request: ".print_r($_REQUEST,1));
  SugarApplication::redirect('index.php');
}

Legacy Style

In previous versions of SugarCRM a new action was added by creating a file in either modules/<TheModule>/<actionname>.php or custom/modules/<TheModule>/<actionname>.php. Although this still works it is not recommended.