Menus in Transport Packages

In my previous articles we looked at how to edit specific files, Resources and Elements from the MODX Manager’s Main Menu). In this one, we’ll see how to put custom menu entries into a MODX Transport Package.

As I mentioned in the previous articles, Revo 3 uses the terms “Main Menu” or “Main Navigation” in forms and trees. In Revo 2, the terms are “Top Menu” or “Top Navigation”. I’ll use the Revo 3 terms in these articles because they’re more generic, so be sure to translate them for Revo 2, if that’s your platform, as you follow the directions below.

The transport.menus.php File

The menu items themselves normally go in a file called transport.menus.php, in the _build/data/ directory. Here’s an example from the SiteCheck Extra:

<?php
$menus[1] = $modx->newObject('modMenu');
$menus[1]->fromArray( array (
  'text' => 'SiteCheck',
  'parent' => 'components',
  'action' => 'index',
  'description' => 'sitecheck_menu_desc',
  'icon' => '',
  'menuindex' => 3,
  'params' => '',
  'handler' => '',
  'permissions' => '',
  'namespace' => 'sitecheck',
  'id' => 1,
), '', true, true);

/* Add more menu items (if any) here, by duplicating
   the section above, changing the index number ([1]),
   and other fields as necessary. */

return $menus;

Obviously, you’ll need to modify several of these to match your package.

Note that in the unlikely case that the parent field is the Manager’s Main Menu, you’ll need to set that field to either “Top Navigation” (for Revo 2), or “Main Navigation” for Revo 3. If your Extra will be installed in both versions, you’ll need to do that in a resolver (after checking the MODX version with $modx->getVersionData()['version'] >= 3). It can’t be done in the build script.

The “text” field is the string you want to display on the menu item’s button. This is the “Lexicon Key” field you see when creating or editing a menu item in the MODX Manager. You can create an entry for it in the default.inc.php Lexicon file if you’d like it translated, otherwise it will appear as is.

Similarly, the “description” field can also be translated with a Lexicon entry in that same file.

This menu item goes under the “Extras” Main Menu item, so the “Parent” field is “components”, which is what’s in the “Key” field of the “Extras” Main Menu item.

The “Namespace” is “sitecheck”, which is a lowercase version of the package name.

The “enuindex” field determines where the entry appears on the Extras menu. If you use 0, it may appear above the “Installer” entry, which most people prefer to have at the Main for easy access to Package Manager.

The “action” field is “index” for this item. For this menu item the action is “index” and the namespace is “sitecheck”. Since the “namespace” is not “core”, MODX will look in the core/components/sitecheck/controllers. directory for a file called index.class.php.

The file doesn’t have to be named index (though that’s the name for most controllers). For example, the CustomSearch controller is named home.class.php. If you have CustomSearch installed, you can look at the menu item for it and see that the namespace is “customsearch” and the “action” is “home”. FormIt also uses home.class.php and “home” as the action.

For menu items in the core namespace, MODX looks in the manager/controllers/default/{action} directory for an index.class.php file.

Adding the Menu to the Package

Here is a slightly modified version of the menu section of the build.transport.php file for SiteCheck. It assumes that you have created the package and vehicle earlier in the file:

/* At the top of the file */

$root = dirname(dirname(__FILE__)) . '/';
$sources = array(
    'root' => $root,
    'build' => $root . '_build/',
    'data' => $root . '_build/data/',
    /* many more entries here for other
       directories */
);

/* Instantiate PackageBuilder and create package here */

/* Transport Menus */
/* load menu */
$modx->log(modX::LOG_LEVEL_INFO,
    $modx->lexicon('mc_packaging_menu'));

$menus = include $sources['data'] . 'transport.menus.php';

/* Loop through all menu entries in the file */
foreach ($menus as $menu) {
    if (empty($menu)) {
        $modx->log(modX::LOG_LEVEL_ERROR,
            $modx->lexicon('mc_could_not_package_menu'));
    } else {
        $vehicle = $builder->createVehicle($menu, array(
           xPDOTransport::PRESERVE_KEYS => false,
           xPDOTransport::UPDATE_OBJECT => true,
           xPDOTransport::UNIQUE_KEY => 'text',
           xPDOTransport::RELATED_OBJECTS => false,
        ));
        $builder->putVehicle($vehicle);
        unset($vehicle, $menu);
    }
}
$modx->log(modX::LOG_LEVEL_INFO, '    ' .
    $modx->lexicon('mc_packaged')
        . ' ' . count($menus) . ' ' .
        $modx->lexicon('mc_menu_items'));

You can use the settings above for any menu item. It’s unlikely that you’d ever need to modify it.

If you look at older build files that transport menus, you’ll see a more complex section that adds an “action” related object to the menu attributes. This is no longer necessary, since actions are now deprecated in MODX Revolution. In fact, if your DB still has a modx_actions table, it’s probably empty.

In the old days, when a menu item was selected, MODX had to look in the modx_actions table to get the namespace and controller based on the action (a number held in the id field) of the modx_actions table. Now, those values are all in the modMenu object itself, and the action is a text field like resource/update.

MODX can now go directly from the menu item to the controller or processor (or occasionally JavaScript code) it needs to execute to carry out the menu command. This makes things much simpler for developers, and speeds up the MODX Manager.

---

Bob Ray is the author of the MODX: The Official Guide and dozens of MODX Extras including QuickEmail, NewsPublisher, SiteCheck, GoRevo, Personalize, EZfaq, MyComponent and many more. His website is Bob’s Guides. It not only includes a plethora of MODX tutorials but there are some really great bread recipes there, as well.