Creating PHP Controller File

Creating PHP Controller File
Prev	Chapter 2. Creating a Widget	Next

This is the main file required for a widget. In this file we define a new PHP class for the widget, which extends from the Application_Cp_Widget_Module_Abstract class.

Our widget class must be named CpWidget_widget_name_controller. So in our case the class will be called CpWidget_custom_example_controller.

The skeleton code for this class is as follows:

<?php
    class CpWidget_custom_example_controller extends Application_Cp_Widget_Module_Abstract
    {
    }
?>

There are several methods that you must implement in this class so it can be used in the Control Panel:

__toString(). This returns a string that is the title of your widget.
getWidgetSize(). This returns an indication of how much space on the user's screen your widget needs to be used effectively. The Control Panel will aim to give the widget its required amount of space when added to a user's dashboard.
This method can return one of the following constant values: self::SIZE_SMALL, self::SIZE_MEDIUM, or self::SIZE_LARGE.
getCategories. This returns an array, each of which element is a string. The values it returns will appear in the widget browser when the user tries to add a new widget.
getDescription(). This returns a brief description of what the widget is used for. It will appear in the widget browser when a user views the widget.
getDependentModules(). This returns an array, each of which element is the string name of any Recite modules this widget relies on. If the module doesn't exist in Recite or the client the user belongs to doesn't have access to the module, the widget cannot be added and it won't appear in the wiget browser.
indexAction(). This method is executed when the widget is loaded in the Control Panel. Here you can put any logic required for displaying the widget. After this method has been run the corresponding ./templates/index.tpl template will be rendered. You can also optionally define the JavaScript controller file for this action in ./files/js/index.js

Note

In addition to indexAction(), you can also define other actions that can be called from your widget. To keep things simple we'll only use a single action for now.

Here's a more complete example of the controller.php file.

Example 2.1. Sample widget controller file (controller.php)

<?php
    class CpWidget_custom_sample_controller 
        extends Application_Cp_Widget_Module_Abstract
    {
        public function __toString()
        {
            return 'Sample Widget';
        }

        public function getWidgetSize()
        {
            return self::SIZE_SMALL;
        }

        public function getCategories()
        {
            return array('Custom');
        }

        public function getDescription()
        {
            return translate(
                'This widget is used to demonstrate how to create Recite widgets.'
            );
        }

        public function getDependentModules()
        {
            return array('pages');
        }

        public function indexAction()
        {
            // perform custom logic here
            
            // get the view so you can assign data to it 
            // before the index.tpl template is rendered
            
            $view = $this->getView();
            $view->someData = 'Some data!';
        }
    }
?>

At this stage you can now add the widget to the Control Panel. However, until you create a view template nothing useful will display.