Tutorial Custom Manager Page

In this tutorial, we'll use Repoman to create a MODX Extra that adds a custom menu page to the MODX manager.

Difficulties

Before we dive in, you should know a bit of the backstory here. There are several troublesome areas in MODX Revolution when it comes to making your own custom manager pages (CMP's). Here are the main stumbling blocks:

• Namespaces
• MODX Actions
• MODX Manager Controllers

I'll discuss these briefly so you can wrap your head around the how and why we do things the way we do.

Namespaces

A MODX "namespace" helps uniquely identify a path where your extra lives, but it also defines where manager controllers live. This is important because we'll soon be creating manager controllers! MODX is hard-coded to expect manager controllers to live in a folder named "controllers/".

MODX Actions (modAction)

MODX actions are what first handle a request made in the MODX manager -- you can think of them as a rudimentary way of defining routes (a la Laravel or CodeIgniter). Actions also what get added to manager menus, so if you're building a CMP, you'll need at least one action defined.

Repoman defines actions as Seed Data, usually defined as files stored inside of model/seeds/. An action file must be named modAction[.identifier].php. Here is an example:

<?php
/**
 * This action defines a controller that handles querying for a resource's children.
 */
return array (
    //'action' => 0, // Omit this so that it will inherit from the related object
    'namespace' => 'lunchbox',
    'controller' => 'index',
    'haslayout' => 0,
    'lang_topics' => 'lunchbox:default',
    'assets' => '',
    'help_url' =>  '',
);
/*EOF*/

Manager Controllers

MODX manager controllers are not thoroughly documented and their architecture is a bit wonky, so here's what you need to know:

The action you create will point to a "primary controller", which is a file that lives your package's root directory. The file is a PHP class. This may be the only controller file that you need, but frequently this file simply hands off to another PHP class inside of your package's "controllers/" directory. The classes in the "controllers/" directory can be accessed by supplying the manager URL with a "&action=" parameter.

You'll see how we use these bits later on, but now you know at least a bit about what to expect inside a MODX manager controller.

---

Javascript:

MODx.action['namespace:controller']

---

JSON Controller

The $scriptProperties array passed to the process() method includes the $_GET and $_POST arrays. You can test this by returning the contents of the array:

public function process(array $scriptProperties = array()) {
    return '<pre>'.print_r($scriptProperties, true).'</pre>';
}