How to make a MODX extra using MyComponent Part 1

Getting started building your own 'extras' for MODX

I started out using MODX Evolution. To write a module for the back end was easy: Go to the modules tab, click 'New Module' and start coding. And building your own snippets of reusable code was a matter of placing your code in the snippets folder and including it in a 'snippet'. Fast and simple.

But there was no organised, systematic way of sharing code between people and installs. Enter MODX Revolution, this added the Package Manager to make finding, sharing, uploading, installing and updating extras a lot easier. Also with MODX Revolution came php PDO abstraction to make code portable across implementations of MODX that use different databases. Also access to the database was now done through 'connectors' and 'processors' for added security. And on top of all this, ExtJS was made available to use in the backend manager.

With these changes came more power but also more complexity. Learning to code extras for MODX now required a bit more effort.

First steps

To understand how everything fits together the best way to start is to do the Developing an Extra in MODX Revolution tutorials. This is a comprehensive 3 part tutorial and it covers a lot of ground. Don't expect to do it in an a couple of hours, it is worth dedicating some serious study time to. You also need to follow it very carefully because if you miss a step it can be difficult to track down where you went wrong, at least at first, before you fully understand what you are doing. But it does work and it will teach you everything you need to know to develop an extra and build a custom manager page (CMP).

I did it twice, and took a lot of notes to get to grips with it .

One of the things that can throw you is the sheer number of files involved, and their structure and how they relate to each other. Getting to know the file structure and what goes where is a major part of the learning process.

MyComponent

After doing the 'Doodles' tutorial, you will realise that there are a lot of files involved in making an extra, especially if it includes a custom database table and custom manager pages. And you will think to yourself 'I have to create all those files in the right place just to get started!'. This is where Bob Ray's MyComponent comes in.

One of the major advantages of using MyComponent is that it allows you to quickly create all the files you need to start, in the right folders, and then when you have developed your extra it will build the transport package for you.

Again you need to spend a bit of time with MyComponent before you get the hang of it. The MyComponent pages describe in full how to use it but I found it useful to draw a diagram to be able to visualise the process.

It looks complicated but try it out. Keep starting new projects, make small changes, and see what happens. Delete and repeat.

How to get your stub extra and CMP fully working in the development environment

These are the notes I made while learning how to use MyComponent.

To change the author details duplicate the chunk example.config.php and call it myexample.config.php, update it with your details, MyComponent will then use this chunk for your projects.

System settings

Your new component isn't in the same directory as it will be when it is installed by the Package Manager. So we need to set the system settings (if your project is called example) as example.core_path and example.assets_url. In my environment this was respectively:

c:\xampp\htdocs\modx-2.2.8\assets\mycomponents\example\core\components\example\

and

/modx-2.2.8/assets/mycomponents/example/assets/components/example/

One GOTCHA! that has had me scratching my head on more than one occasion is pasting a blank space after my paths in the system settings, whatch out for that.

Namespace

To get the CMP to work you need to hardcode the Namespace to your development files, in my case this was:

Core Path

c:\xampp\htdocs\modx-2.2.8\assets\mycomponents\example\core\components\example\

Assets Path

/modx-2.2.8/assets/mycomponents/example/assets/components/example/

Connector.php

Additionally the connector connector.php is used by the javascript call from the CMP. Because it is being called in this way it needs to instantiate a MODX object to function properly. To be able to do that it needs the config file config.core.php. The config file is in a different place, relatively to your extra folder, depending on if you are in the development environment or the installed-from-package-manager environment. So I added this code to connector.php so that it would work in either environment.

$configFile = dirname(dirname(dirname(dirname(__FILE__)))) . '/config.core.php';
$devConfigFile = dirname(dirname(dirname(dirname(dirname(dirname(dirname(__FILE__))))))) . '/config.core.php';
if(file_exists($configFile)){
  require_once $configFile;
}
elseif(file_exists($devConfigFile)){
  require_once $devConfigFile;
}

Parse error that prevents CMP pages from working correctly

When you use bootstrap to create the files for your project, MyComponent replaces every instance of example in its templates with the name of your project. I discovered a small bug where it missed a couple of instances that stopped the CMP's from working correctly. It was in file controllers/mgr/home.php and looked like this:

$modx->regClientStartupScript($test->config['jsUrl'].'widgets/home.panel.js');
$modx->regClientStartupScript($test->config['jsUrl'].'sections/home.js');
$modx->regClientStartupScript($example->config['jsUrl'] . 'widgets/chunk.grid.js');
$modx->regClientStartupScript($example->config['jsUrl'] . 'widgets/snippet.grid.js');

In this example the project was called test, so just change the two instances of example to test.

So if you do all those things you should have a fully functioning example extra that you can play with and develop in your development environment.

Installing your extra on a different site

When you package it up and move it to another modx install you will either need to delete example.core_path and example.assets_url before you create your package or delete them when it is installed because now it is in the right place and can use the regular core_path and assets_url.

Ok, that's it for now, hopefully in my next post I will describe creating a custom table to be managed by my CMP.