Controllers
Overview
The controller is responsible for responding to user actions. In the case of a web application, a user action is (generally) a page request. The controller will determine what request is being made by the user and respond appropriately by triggering the model to manipulate the data appropriately and passing the model into the view. The controller does not display the data in the model, it only triggers methods in the model which modify the data, and then pass the model into the view which displays the data.
Site Controller
<?php namespace Components\Hello\Site\Controllers; use Hubzero\Component\SiteController; class One extends SiteController { public function displayTask() { // Pass the view any data it may need $this->view->greeting = 'Hello, World!'; // Set any errors foreach ($this->getErrors() as $error) { $view->setError($error); } // Output the HTML $this->view->display(); } }
The first, and most important part to note is that we're extending Hubzero\Component\SiteController
which brings several tools and some auto-setup for us.
Note: Hubzero\Component\SiteController
extends Hubzero\Base\Object
, so all its methods and properties are available.
In the execute()
method, the list of available tasks is built from only methods that are 1) public and 2) end in "Task". When calling a task, the "Task" suffix should be left off. For example:
// This route Route::url('index.php?option=com_example&task=other'); // Refers to .... public function otherTask() { ... } ....
If no task is supplied, the controller will default to a task of "display". The default task can be set in the controller:
class One extends SiteController { public function execute() { // Set the default task $this->registerTask('__default', 'mydefault'); // Set the method to execute for other tasks // The following can be called by task=delete and will execute the removeTask method $this->registerTask('delete', 'remove'); // (task, method name); parent::execute(); } ... }
Each controller extending Hubzero\Component\SiteController
will have the following properties available:
_option
- String, component name (e.g., com_example)_controller
- String, controller nameview
- Object (View)config
- Object (Registry), component config
<?php class One extends SiteController { public function displayTask() { $this->view->userName = User::get('name'); $this->view->display(); } }
Auto-generation of views
The Hubzero\Component\SiteController
automatically instantiates a new Hubzero\Component\View
object for each task and assigns the component ($option
) and controller ($controller
) names as properties for use in your view. Controller names map to view directory and task names directly map to view names.
/{component} /site /views /one (controller name) /tmpl /display.php /remove.php
Example usage within a view:
<p>This is component <?php echo $this->option; ?> using controller: <?php echo $this->controller; ?></p>
Changing view layout
As mentioned above, the view object is auto-generated with the same layout as the current $task
. There are times, however, when you may want to use a different layout or are executing a task after directing through from a previous task (example: saveTask encountering an error and falling through to the editTask to display the edit form with error message). The layout can easily be switched with the setLayout
method.
/{component} /views /one (controller name) /tmpl /display.php /world.php
class One extends SiteController { public function displayTask() { // Set the layout to 'world.php' $this->view->setLayout('world'); // Output the HTML $this->view->display(); } }
Any assigned data or vars to the view will not be effected.
Admin Controller
Administrator component controls are built and function the same as the Front-end (site) controllers with one key difference: they extends Hubzero\Component\AdminController
.
<?php class One extends AdminController { ... }
The primary difference between SiteController
and AdminController
is the pre-defining of a few tasks commonly used in administrator components.
API Controller
API controllers extend Hubzero\Component\ApiController
. Functionally, API controllers are very similar to site and admin controllers in that defining executable tasks is done by creating public methods with a "Task" suffix. They differ, however, in two key ways:
1) Controllers follow a naming convention unique to the API. [TODO: fill in]
2) The API has no concept of views and thus no View object to render data. Instead, data is sent back to the application via the send
method which, in turn, prepares the response before delivering to the user.
<?php namespace Components\Example\Api\Controllers; use Hubzero\Component\ApiController; class Greetings extend ApiController { public function listTask() { $model = new Archive(); $data = $model->all(); $this->send($data); } }