A Simple Guide to Packaging Themes

With the Envato's Most Wanted MODX Theme contest underway, we wanted to provide a simple guide for creating a MODX Theme package using the ThemePackagerComponent. For folks new to MODX, I've included instructions for installing it.

By Jay Gilmore
April 16, 2014
A Simple Guide to Packaging Themes
Image: 'Cardboard boxes stick dispenser for adhesive tape.' from Shutterstock

This past few weeks we launched a huge $10,000 contest with Envato to build up the inventory of MODX website themes for ThemeForest. Just like any other MODX Add-on, MODX Themes, are collections of resources, elements and files, all bundled in a MODX Transport Package. To make it easy to build these Transport Packages we created ThemePackagerComponent.

ThemePackagerComponent is available in Package Management in MODX Revolution for installation. If you're new to MODX Revolution, here are the instructions for installing:

  1. Go to System>Package Management
  2. Click 'Download Extras'
  3. In the search field type 'ThemePackager'
  4. Click 'Download'
  5. Once the download dialog completes, click on 'Back to Package Management'
  6. From Package Management, locate the ThemePackagerComponent and click 'Install'
  7. The installer will bring up an installation UI, to proceed with the installation, click 'Continue'
  8. Upon completion the installation dialog will close and display the installation log.

Once installed you'll find ThemePackagerComponent can be accessed by locating Components in the main navigation of the site, if you do not see the Components link in the Manager navigation, just refresh your browser (F5 (Win) or CMD+R (Mac).

Now that you have the ThemePackagerComponent installed, to package your MODX Theme you'll launch the ThemePackagerComponent and complete the fields and review each tab to ensure you're including all those Resources, Add-ons, files etc. Once done, you can click on the 'Export Transport Package' at the top right of the UI.

  1. Launch the ThemePackagerComponent via Components>Theme Packager Component
  2. On the Package Tab, complete the Package Name and version fields
  3. Optionally, select installation options for the Theme user
  4. On the Elements tab select each of the available Elements you wish to include in your Theme Package
  5. On the Subpackages tab, select from any installed Add-ons to include with your Theme such as getResources or Articles, etc.
  6. On the Files tab, select any files or directories beneath the /assets directory such as CSS or Javascript
  7. On the Advanced tab you can optionally add System Settings or Context Settings as comma separated key names, in addition, if you have sample content, you can enter the comma separated list of Resource IDs to include in your package
  8. Once you've entered all the data for your package, click 'Export Transport Package'
  9. You will now have a functional MODX Transport Package of your MODX Theme. Be sure not to alter the file name as the name contains important meta data MODX Package Management relies upon.

ThemeForest has some specific requirements for MODX Theme Packages that you can find in the MODX Theme Authoring Requirements. The two chief rules are that your MODX Theme needs to be a MODX Transport Package (a specially formatted zip file) and your themes should live under the /assets directory, ideally as /assets/themes/themename.

If you encounter a bug or wish to request a new feature for the ThemePackagerComponent, you're encouraged to submit them on the ThemePackagerComponent project at GitHub.

Have fun building your themes and feel free to post any questions you might have in the comments. Or you could ask in this MODX Forum Thread (requires a modx.com account). Happy MODXing!