Mapping Links with Controllers

Preface

This tutorial will explain how to utilize the "Controllers" portion of Emergence's Model-View-Controller pattern.

MVC is a way of organizing code into three distinct partitions. These three partitions are data storage (Model), templates (View), and code logic (Controller).

The controllers job is to map URLs to PHP code and views. We can visually test our mappings with modern web browsers. The advantage that Emergence provides is a a tree like pattern for designing the mappings within PHP code. This allows for an unparalleled ability to move code up and down tree levels without modifying the code.

For the sake of simplicity we'll take a look at some built in controllers that are specifically designed for Emergence models.

A Simple Controller

We can start by making a simple controller in the site-root folder of your site. Let's call it example.php.

/site-root/example.php

Visiting Example in Firefox

We can execute this simple controller by visiting http://yourwebsite.com/example with our browser or a linux command line utility like wget.

Information on URL Mappings

http://yoursite.com/example.php
http://yoursite.com/example
http://yoursite.com/example/blah/blah

All of these will go to the same /site-root/example.php file that we created above.

So at this point you could simply write some code in your controller.

If you make a folder with the same name as an existing php file in site-root the folder will take priority over the php file.

Building a Controller the Emergence Way Manually

Emergence has a built in class for routing URLs called RequestHandler. You can make your own RequestHandler class that extends it to make a proper Emergence controller. To do this let's make a new file in php-classes called ExampleRequestHandler.class.php.

Step 1 - /php-classes/ExampleRequestHandler.class.php

The two functions shiftPath and peekPath are used for navigation through a URL path. This lets us make a mapping with simple tree-like patterns using PHP syntax.

For example if the URL path was /example/hello/world the path would be resolved into an array. Since the file that is running is example.php it skips the first part so the first time we run shiftPath() it will return 'hello' and the second time it will return 'world'. You can of course use peekPath() instead of shiftPath() to probe the path before actually using it. An example of this is on line 9 in the above code snippet.

peekPath() and shiftPath()

RequestHandler::shiftPath() - Will give you the current next path but move the index up. Each time you run this function it will return the next path until it returns false.
RequestHandler::peekPath() - Will give you the current next path. Running at the end will return false.

Both of these functions are members of the RequestHandler class. If you are extending the RequestHandler class then they are also members of your new class. To access them in your new class use the PHP keyword static.

Step 2 - /site-root/example.php

We are now done mapping the path example to the PHP class ExampleRequestHandler by executing the method handleRequest.

The next section will show you how to map URLs for models by using premade RequestHandler classes. RESTful URL mappings for models come with Emergence so you don't have to do it yourself.

Intro to RecordsRequestHandler

RecordsRequestHandler is an Emergence class that provides an automated Create, Read, Update, and Delete system for Models built with the ActiveRecord class.

To use it you will need to make a new class that extends RecordsRequestHandler. For this example we'll use the model made in the Working with Models guide. The only configuration variable we need to provide is the name of the model's class. In this case it's Example.

Step 1 - /php-classes/ExamplesRequestHandler.class.php

Once we have the request handler class ready we can wire up our end point in site-root.

Step 2 - /site-root/examples.php

Now we have the method handleRequest in ExamplesRequestHandler doing the job of a controller. Since we are extending RecordsRequestHandler the real code is in RecordsRequestHandler::handleRequest and may be referenced at it's doc page.

RecordsRequestHandler URL Mapping

Templates
/{php file in site-root}/ - Tries to load the value of $recordClass::$pluralNoun as a .tpl file in html-templates. Passes $recordClass::getAll() as $data.
/{php file in site-root}/{Model.ID or Model.Handle} - Tries to load the value of $recordClass::$singularNoun as a .tpl file in html-templates. Passes $recordClass::getByID() or $recordClass::getByHandle() as $data.