Controllers

Creating a Controller

The controller is a critical element within the Model View Controller architectural pattern (MVC) . Controllers are the “glue” that ties together the Model and View. The Controller essentially is responsible for deciding which action to carry out, retrieving the necessary information from the Model and telling the view to render this information in an understandable format to the user. Controllers may be thought of as the “organiser” or “task manager” of the group - inherit in their function of dictating actions/tasks of the Model and View.

Here’s an illustrated example of a simplistic controller within the Red Framework.

<?php
	class HomeController extends Controller {

	}
?>

That is it - The bare essentials to create a basic controller within the Red Framework. There's two distinct ways of creating the controller file. Either the content above can be placed within a file, in the app/controllers folder - or alternatively the Red Command Line Interpreter can be utilized. The following could be executed to create the controller outlined above.

php Red.php make controller HomeController

A basic controller file will then be created in the app/controllers folder based on your chosen name.

Actions

"Actions" are like operations that can occur within the controller. These segment the controller up into areas of functionality, based on the URL the user visits. URLs within the Red Framework are structured as such: /{project_path}/{controller}/{action}/{parameter}. So if we wanted to carry out an action when the user's visits the URL: /{project_path/home/test/. The Following illustrates how to define the explicit action - the assumption being made that the proper routing has been configured for the controller - consult the routing documentation for information on configuring URL routes.

Here’s an illustrated example of a action within a Controller

<?php
	class HomeController extends Controller {
           public function get_test() {
              return "Hello World";
           }

	}
?>

Controllers within the Red Framework are REST "by default". This means that actions can be tied to specific HTTP verbs, the above example illustrates a request to the URL: /{project_path/home/test/ for making a GET request. The utilization of REST based Controllers, enables separate requests to be made to a Controller based on the action carried out in the View. For instance we could have one action to render the initial View to the user(GET) and another which will process submitting of a form (POST). Furthermore the production of REST consumable Web Services is effortless. Below demonstrates a range of different actions configurable within a controller.

<?php
	class HomeController extends Controller {

		public function any_test() {
			/* I will be carried regardless of the HTTP method */
		}

		public function get_index() {
			/* will be carried out if no action is provided in the URL */
		}

		public function get_test() {
			/* I will be carried out when the request is a GET request */
		}
		public function post_test() {
			/*  I will be carried out when the request is a POST request. */
		}
	}
?>

Action Parameters

Actions can also have parameters, these are the Red Framework's version of a traditional "querystring". They are provided in the same way - parameters are added to a function. Below demonstrates a typical action within the Red Framework, with additional parameters.

<?php
class ProductController extends Controller {

	public function any_edit($id = -1) {
		/* i'm a action with a parameter */
	}
}

?>

This action would then be invoked when a url of the type: /product/edit/{id} was visited. Note the addition of a default parameter - allowing the passing of a default value. If the action is visited without specifying a value for the parameter (/product/edit/{id}), {id} would become "-1". This provides vastly easier error handling for action parameters.

Rendering Views

A common operation of the controller is to decide the appropriate data - normally from the Model - to pass to the view in preparation of rendering the content to the browser. Views specified in the folder app/views are automatically "hooked up" to the relevant action. In order for the Red Framework to find the intended view, the view most be present within the app/views folder - in the format /{controller}/{action}.html. This function can however be overridden, if necessary. Below outlines specifying a custom view for a controller.

<?php
class ProductController extends Controller {

	public function any_test($id = -1) {
		$this->SetView('product::editscreen');
	}
}
?>

The view must be expressed in the format above, this will instruct the controller to render the view available in: /app/views/product/editscreen.html.

#Content Types

<?php
	class ProductController extends Controller {


		public function any_add($id = -1) {
			$this->SetView('product::editscreen');

			/* I have passed information to the view, 
			by return my data from the action*/

			return array(
				'foo' => 'bar'
			);
		}

		public function any_html() {

			/* since I have specified html to return from the action, 
			this will instead be rendered not my view */

			return "<h1>View overide</h1>";
		}
		public function any_json() {

			/* Since i'm returning JSON this is likely a AJAX request and 
			as such my view will not be rendered, instead the JSON content will be outputted */

			return json_encode(array(
				'data' => 'hello ajax world',
			));

		}

		public function any_object() {
			/* any object returned from the action is automatically 
                        converted to json and outputted - View will not be rendered. */

			$object = new stdClass();
			$object->foo = 'bar';

			return $object;
		}

		public function any_custom() {
			/* this shows an example of a custom content-type(pdf) with data, 
			note again the view is not rendered */

			$this->request->SetContentType('application/x-pdf');
			$this->request->SetContent(file_get_contents('./test.pdf'));
		}
	}
  
?>