Including other Extras in a MODX Transport Package

What to do if your extra requires the installation of other extras


In the previous article, we looked at some reasons why getResources and pdoResources might not be showing your TV values. In this one, we'll see how to include other extras in a MODX transport package.


MODX logo

The Problem

Suppose you're creating a MODX extra that uses one or more other extras. You could tell your users to install the other extra, or hope that they have it installed, but luckily, there's a very easy way to have MODX install the other extras for you automatically if they're not already there.

Another use case is creating a transport package you use to create new web sites that installs a standard set of MODX extras that you want on every one of your sites. The MyComponent extra is great for this, because it allows you to easily include Top Menu items, new System Settings, chunks, templates, custom snippets, plugins, and TVs, in addition to the extras.


Dependencies

The other extras you want installed are called "dependencies" and having them installed automatically when your package is installed is as easy as specifying their names and the required versions in your build.transport.php file.

Every build.transport.php file should contain a section like this:

$attr = array(
    'license' => file_get_contents($sources['docs'] . 'license.txt'),
    'readme' => file_get_contents($sources['docs'] . 'readme.txt'),
    'changelog' => file_get_contents($sources['docs'] . 'changelog.txt'),
);

Adding dependencies is a simple as adding a few lines to that array. In the example below, MODX will install a version of FormIt greater or equal to version 4.2.0. If the user has an earlier version of FormIt, it will be updated when the user installs your package.

$attr = array(
    'license' => file_get_contents($sources['docs'] . 'license.txt'),
    'readme' => file_get_contents($sources['docs'] . 'readme.txt'),
    'changelog' => file_get_contents($sources['docs'] . 'changelog.txt'),
    'requires' => array(
        'formit' => '>=4.2.0',
    ),
);

If you need to add more extras, just add them to the array:

$attr = array(
    'license' => file_get_contents($sources['docs'] . 'license.txt'),
    'readme' => file_get_contents($sources['docs'] . 'readme.txt'),
    'changelog' => file_get_contents($sources['docs'] . 'changelog.txt'),
    'requires' => array(
        'FormIt' => '>=4.2.0',
        'getResources' => '>=2.6.0',
        'Wayfinder' => '>=2.3.3`,
    ),
);

Finer Control

The dependency specifications work just like they do in Composer. You can specify an exact version, a range of versions, the latest version, or the latest major (.0) version. You can even specify versions that you don't want (e.g., '>=1.3.0,<1.4.0,!1.3.5' which means greater than or equal to version 1.3.0 and less than version 1.4.0, but *not* version 1.3.5). For more details on specifying versions, see this page.

The dependency operations are only available in MODX 2.4 and up. If people might be installing your extra in older versions of MODX, you may want to either make MODX 2.4+ a requirement for your extra when you submit it to the MODX extra repository, or include a validator in your package that checks the MODX version and aborts the install if it's not >= MODX 2.4.0.


MyComponent

If you're using MyComponent already, an upcoming version will let you specify the dependencies in the config file. Until it's released, you can use the method described above. MyComponent will never alter an existing build.transport.php file.


Coming Up

In the next article, we'll look at how to create Articles in code.



For more information on how to use MODX to create a web site, see my web site Bob's Guides, or better yet, buy my book: MODX: The Official Guide.

Looking for high-quality, MODX-friendly hosting? As of May 2016, Bob's Guides is hosted at A2 hosting. (More information in the box below.)



Comments (0)


Please login to comment.

  (Login)