HowTo:Add a new page

From ZenMagick Wiki

If you are looking for information about adding define or 'ezpages', please check the HowTo:Add_a_static_page.

Introduction

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.

View only

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

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.

The crumbtrail will look like this: Home > About Us

Controller

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

Adding a custom controller

So, let’s say we want to add a view that 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 we'll drop the ZM prefix, 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()<code> 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() {
   $crumbtrail = ZMCrumbtrail::instance();
   $crumbtrail->addCrumb('Foo');
   $crumbtrail->addCrumb(ZMToolbox::instance()->utils->getTitle(null, false));

   return $this->findView();
}

The line <code>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?

Views

Conditional views

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()<code> method to return a different view based on the users status:

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();
}

$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 empt‘ is the key used by the controller to find the view (that is, the parameter passed into the <code>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.