Screencast #03 - Routing and Controller

Routing and Controller

With the basic structure of an extension set up, a common task is to register your own controllers and add your own menu items to the admin area. For that, we will look at some additional properties that you can add to the module definition in your index.php.

Adding a controller

A controller in Pagekit is just a plain PHP class. Every public method named properly (i.e. someAction()) will be mounted by Pagekit's routing (i.e. /todo/some).

Create a file packages/pagekit/todo/src/Controller/TodoController.php with the following code.

<?php

namespace Pagekit\Todo\Controller;

/**
* @Access(admin=true)
*/
class TodoController
{

    public function indexAction()
    {
      return "Yay.";    
    }

}

To limit the access to the admin area and mount this controller to an admin url, we use the annotation @Access(admin=true). Annotations are keywords which are placed in the comment block above a class or method. Learn more about annotations.

To use this controller, we need to autoload our namespace and mount the controller to a route, Add the following properties to the configuration array in your index.php.

// ...

// array of namespaces to autoload from given folders
'autoload' => [
        'Pagekit\\Example\\' => 'src'
    ],

// array of routes
    'routes' => [

    // identifier to reference the route from your code
        '@todo' => [

            // which path this extension should be mounted to
            'path' => '/todo',

            // which controller to mount
            'controller' => 'Pagekit\\Todo\\Controller\\TodoController'
        ]
    ],  

    // ...

You are now able to access the new controller at the url <pagekit_path>/admin/todo. Note how this URL is generated from four parts:

  1. <pagekit_path> URLs always start from your url
  2. @Access(admin=true) resulted in an admin url /admin
  3. The controller is mounted as /todo
  4. The indexAction is the default route at that url.

If you cannot access your route, clear the cache. Pagekit caches routes for better performance.

Debug toolbar

To see all registered routes during development, it is useful to enable the Debug Toolbar in Pagekit's system settings. The toolbar appears at the bottom of your screen and shows all registered routes, amongst other useful information.

Remember to turn this off for a live website.

Adding a menu item

To add menu items use the menu property in your module definition. Add the following to the index.php.

// ...

'menu' => [
    'example' => [
        'label'  => 'ToDo',
        'icon'  => 'app/system/assets/images/placeholder-icon.svg',
        'url'    => '@todo',
    ]
],
// ...

Refresh the Pagekit backend and you will see a new menu item which links to the @todo route.

Next step: Views and templating

This is the basic workflow of controllers and routing. To render actual view files instead of plain strings, you will only have to change what your Controller actions return. We will look at that in the next screencast. For the curious out there: Read about Views and Templating in the Pagekit documentation.

Here is a short list of all existing screencasts:

Florian
Posted by Florian
{{ message }}

{{ 'Comments are closed.' | trans }}