Adding a new page is perhaps one of the most common tasks, so I hope this is useful for a lot of people.

Adding a new page is different from adding a static page in that static/ez-pages just add content while using an existing template. Here, we will be adding a new template and, depending on the complexity of the requirements, a new controller and perhaps even view mappings.

Let’s start easy with a simple page. An ‘About Us’ page is probably the classic example, so let’s get to work.

View only

To add a new ‘About Us’ page, we need to create a new content view in the themes view folder. I’ll use the assumed theme name ‘fancy’ for all examples following, so the new file would be:

zenmagick/themes/fancy/content/views/about_us.php


And that’s it! All done, except for putting some useful information into the new file. The URL for the new page is:

index.php?main_page=about_us

For this simple example the page title and crumbtrail are derived from the filename. The rules are that underscores ‘_’ are replaced by a blank and the first character of each word is capitalized.

Crumbtrail: Home > About Us

About controller

A few words about page controller (we are, after all, in a MVC environment). Most pages/views in ZenMagick have their dedicated controller. A controller is a class of type ZMController that is responsible for processing the request.

If no controller is found like in our example, the default controller is used. The default controller does almost nothing, except for setting up the crumbtrail with a link to the homepage and the current view (again, based on the viewname).
View AND Controller

So, let’s say we want to add a view that is needs a more sophisticated crumbtrail or some other request processing. Since we do not want to put that code into the view, we’ll need a new controller.

The name of the controller class is, similar to the view’s filename, based on the main_page value. In our case the classname would be ZMAboutUsController or, since our code is not part of ZenMagick core, AboutUsController. The PHP file can be added to the extra directory of our theme:

zenmagick/themes/fancy/extra/AboutUsController.php

The simples way to create the new file is to copy an existing controller file from ZenMagick and then rename it (do not forget to rename all references inside the file too!).

Since we are not going to add a form to the about us page, we only need to worry about the processGet() method.

So, we could add an element to the crumbtrail, or lookup a featured product to be displayed, or a random message of the day. Your choice.

So, going for the custom crumbtrail the method would look similar to this:

function processGet() {
     global $zm_crumbtrail;
          $zm_crumbtrail->addCrumb('Foo');
          $zm_crumbtrail->addCrumb(zm_title(false));

return $this->findView();
}
This will create the following crumbtrail: Home > Foo > About Us.

The line ‘return $this->findView()‘ is the way for a controller to find the configured view to be displayed. The default (nothing configured) is to use the corresponding view file; ie about_us.php.

A typical example for this sort of setup are the account pages. All account pages add the ‘Account’ element to the crumbtrail to make it look nicer.

So, now we have a view and a controller, so what else can we do?

Conditional views

So, let’s assume we would like to display a different about us page for logged on users. This can be archived by modifying the processGet() method:

function processGet() {
global $zm_request, $zm_crumbtrail;

$zm_crumbtrail->addCrumb(’Foo’);
$zm_crumbtrail->addCrumb(zm_title(false));

if ($zm_request->isRegistered()) {
          return $this->findView(’about_us_registered’);
     }

return $this->findView();
}

So, if the user is registered the controller is looking for a view with a key of ‘about_us_registered‘. Not surprisingly, in the absence of any configuration, the used view would be zenmagick/themes/fancy/content/views/about_us_registered.php.

Symbolic view names

Using the views real filename is perhaps ok for this example, but for larger systems this might not be the case.

The file zenmagick/core/settings/url_mapping.php contains a number of mappings for cases where the view filename does not match the main_page value, or where different views should be used depending on other conditions (for example the user being logged in or not).

A typical mapping looks like this:

$zm_urlMapper->setMapping('shopping_cart', 'empty', 'empty_cart');

The first parameter is the controller name, so here we are looking at a mapping for the shopping cart controller. The second parameter ‘empty‘ is the key used by the controller to find the view (that is, the parameter passed into the findView(..) method). The third parameter is the real view name.

So, if the shopping cart controller executes the the line $this->findView(’empty’), the view returned will use the filename zenmagick/themes/fancy/content/views/empty_cart.php.

It is also possible to create mappings that are valid for all controller by setting the first parameter to null. Examples for that are the login page, the homepage and error pages:

$zm_urlMapper->setMapping(null, 'error', 'error');

This means, that by changing the mapping for the key ‘error’ to:

$zm_urlMapper->setMapping(null, 'error', 'my_error');

all controller trying to display an error page will automatically use the view my_error.php!

Right, this is perhaps enough to getting started. It is worthwhile remembering that mappings can be changed in local.php, so there is no need to modify the core files.