Creating a custom controller

Prev | Next

These directions cover 1) creating a new controller and 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 lets the Yii framework find the controller example and the correct file it references.

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.

Extending/Overriding an existing controller

The instructions are largely the same except that you must extend an existing controller and include the original in your controller file

First, create your custom controller file in /custom/controllers using the naming convention MyController.php for both the filename and the classname inside. Here is the file for MySearchController.php which we will extend the default SearchController

<?php

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

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

    }
}

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

Next, we map the controller in custom/config/main.php

In /config/main.php locate lines 79-83 and uncomment the lines, and update them to read

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

This lets the Yii framework find the custom controller and overrides the /search URL to point to it.

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 previous functions 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, useful for adding functionality without really overriding what Web Store already does. 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 actual Web Store function after performing a custom action. (This is important so that future updates on a particular controller aren't lost if you're only interested in supplementing the function.)

###Prev | Next