Creating a custom controller

Prev | Next

These directions cover:

1. Creating a new controller,
2. Overriding an existing controller.

To start using custom configuration, copy custom/config/_main.php to custom/config/main.php. The new configuration file custom/config/main.php can be used to add or adjust Web Store configuration, including the controller mapping (details below).

Creating a new controller

Create a custom controller file in custom/controllers using the naming convention ExampleController.php for both the filename and the class name inside the file. Here is the file for ExampleController.php:

<?php

class ExampleController extends Controller
{
    public function actionIndex()
    {
        echo "this is the default index function";
    }

    public function actionTest()
    {
        echo "This is the test function";
    }
}

This file is saved as custom/controllers/ExampleController.php.

Next, we need to tell Yii to use this controller. We do this by setting the controllerMap property in custom/config/main.php. Find the the following section:

'controllerMap' => array(
	'product' => array(
		'class' => 'custom.controllers.MyProductController',
	),
),

And modify it to use ExampleController:

'controllerMap' => array(
	'example' => array(
		'class' => 'custom.controllers.ExampleController',
	),
),

This tells the Yii framework to use custom/controllers/ExampleController.php for routes matching example.

To test our function, we can use URLs such as

http://www.example.com/example (this runs the actionIndex function)
http://www.example.com/example/test (this runs the actionTest function)

Views with custom controllers

View files normally are loaded from the corresponding controller name. For example, if you have ExampleController then Yii expects the view files to exist in themes/(yourtheme)/views/example

If you already have a custom theme you are creating, this is the simplest way to do this. You can use the command

$this->render('index');

Which will expect index.php to exist as themes/(yourtheme)/views/example/index.php.

However, you may have situations where you wish to keep your custom view files separate in the custom folder, for example you are using a stock theme on our hosting system which is not accessible and you don't wish to make a copy just for a custom view file. In this case, you can create your view file elsewhere and reference it with a modified render() command.

For example if you create a directory custom/views/example and place index.php in this folder, then your ExampleController can use

$this->render('custom.views.example.index');

This is simply using Yii's feature to use a view layer file in a folder other than the one normally belonging to the controller name.

Overriding an existing controller

Create your custom controller file in custom/controllers using the naming convention MyController.php for both the filename and the classname inside. For example, here is the file for MySearchController.php which extends the default SearchController.

<?php

Yii::import("application.controllers.SearchController");

class MySearchController extends SearchController
{
    public function actionCustom()
    {
        echo "this is a custom controller";

    }
}

Note how we import the original (case sensitive) and then extend it through a new name, in this case MySearchController

Next, we tell Yii to use our new controller by modifying custom/config/main.php

In custom/config/main.php find the following section:

'controllerMap' => array(
	'product' => array(
		'class' => 'custom.controllers.MyProductController',
	),
),

And modify it so that search routes use MySearchController:

'controllerMap' => array(
	'search' => array(
		'class' => 'custom.controllers.MySearchController',
	),
),

This tells the Yii framework to use our new custom controller for all search URLs.

To test our function, we can use URLs such as:

http://www.example.com/search/custom (this runs the actionCustom function)
http://www.example.com/search (this runs the actionIndex function in the ORIGINAL file)

In this way, any existing routes in SearchController are untouched.

If you wish to override one of the actions, such as actionBrowse(), you would simply define that function in your controller and it would take precedence over the original. If you need to reference the original, you can use parent:: within your function. For Example:

public function actionBrowse()
{
    // Custom functionality here.
}

would completely override the Browse function /search/browse

However:

public function actionBrowse()
{
    Yii::log(
        'Running a custom browse',
        'error',
        'application.'.__CLASS__.".".__FUNCTION__
    );

    parent::actionBrowse();
}

would run the original Web Store function after performing a custom action.

###Prev | Next