Migrating to MODX Revolution

There is now another option for this process. I've written the GoRevo Package to handle most of the heavy lifting involved in converting a MODX Evolution site to MODX Revolution.

I've left the instructions below for people who prefer to do it manually.


Migrating an existing MODX site to MODX Revolution manually is definitely not for the faint of heart and absolutely not for people new to MODX.

Installing MODX Revolution

Go here to get the latest release of Revolution.

After unzipping the files, just direct your browser to https://mysite.com/setup (substituting the domain of your domain for mysite.com.

If setup fails to create the database, you may need to create it yourself in PhpMyAdmin. Create a database user with full rights and make a not of the DB name, username, and password. Some hosts will add a prefix, so the DB name and/or user name may not be what you entered.

After setup has finished, you should be able to log in to the MODX Manager of the new site. If you're using any of the versions I have, there's no site content at all so you can't preview the site until after you have a template and some documents. Note that the FURL settings in Revolution are in System | System Settings (search for "friendly" without the quotes to see all the FURL settings). I'd advise leaving FURLS off, though, until you have everything else ironed out.

Converting the MODX Tags

By the time you read this, there may be a migration tool for moving the site_content table from the old site to the new one. If not, you may have to cut and paste the old content into the new documents.

Converting the MODX tags can be done manually, or by doing 12 search-and-replace operations. You'll have to edit each document, each template, any chunks that contain these items, and any plugins that output them. And editor that does multi-file search-and-replace is invaluable here. The NetBeans open-source editor is a good option if you don't have one already. You can also use the FireFox "It's all text" plugin to edit them in the Manager, though it's a little slow.

First, here's an overview of the tag changes:

MODX Tags

OldNew
Resource Tags
[*ResourceField/TV*] [[*ResourceField/TV]]
Chunk Tags
{{Chunk}} [[$Chunk]]
Snippet Tags
[[Snippet]] [[Snippet]]
Placeholder Tags
[+Placeholder+] [[+Placeholder]]
Link Tags
[~ResourceId~] [[~ResourceId]]
Setting Tags
[(system_setting)] [[++SettingName]]
Language Tags
No Tag [[%LanguageStringKey]]

Cache Control

OldNew
[!Snippet!] [[!Snippet]]
No Tag [[!$Chunk]]
No Tag [[!*ResourceField/TV]

 

Here are the replacements:

  1. Replace [* with [[*
  2. Replace [+ with [[+
  3. Replace [~ with [[~
  4. Replace [( with [[++
  5. Replace [! with [[!
  6. Replace {{ with [[$
  7. Replace *] with ]]
  8. Replace }} with ]]
  9. Replace )] with ]]
  10. Replace +] with ]]
  11. Replace ~] with ]]
  12. Replace !] with ]]

Porting Your Templates

Create new templates in the new site and cut and paste your template code into them, making the replacements listed above.

Copying the .CSS file(s)

Copy any .CSS files at the old site to the same location at the new Revolution site.

Importing Snippets

Your own snippets will have to be cut and pasted into the new site. Many will work as is, others will have to be modified. The standard MODX snippets and plugins should be available directly in the Transport Packages section of the Manager. Go to System | Package Management and select Download Extras. Browse the repository to find the packages you want, select them and click on Finish. The packages will be downloaded to the core/packages directory and should show up in the grid. To actually install a package, simply right-click on it in the grid and select Install Package.

Wayfinder, as well as many other Evolution add-on components are available in Revolution (including SPForm, NewsPublisher, EZfaq, etc.). FormIt is the Revolution replacement for eForm. The getResources snippet replaces Ditto and most of the properties are the same, so conversion is usually fairly simple.

Importing Categories

All "Content Elements" in Revolution, as in Evolution, can have categories and they show in the tree at the left. You can create them by right-clicking on an item in the tree.

Importing Users

Until migration tools are finished, you'll have to create your users and set permissions manually. The permission system in Revolution is much more powerful, but also more complex and quite different from the one in Evolution, though the underlying concepts are similar. If you have a complex permission system, it can be a challenge to convert it.

Finishing Up

Now that you have templates, chunks, and .CSS files in place, your home page should look approximately normal except for any snippet-generated content from snippets that need conversion to Revolution.

For snippets that don't appear at the Web Transport Facility, you'll have to download the Evolution versions from the MODX Repository, install them the old-fashioned way, and convert them yourself.

 

My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book is available from Amazon.

If you have the book and would like to download the code, you can find it here.

If you have the book and would like to see the updates and corrections page, you can find it here.

MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:

  • Installing MODX
  • How MODX Works
  • Working with MODX resources and Elements
  • Using Git with MODX
  • Using common MODX add-on components like SPForm, Login, getResources, and FormIt
  • MODX security Permissions
  • Customizing the MODX Manager
  • Using Form Customization
  • Creating Transport Packages
  • MODX and xPDO object methods
  • MODX System Events
  • Using PHP with MODX

Go here for more information about the book.

Thank you for visiting BobsGuides.com

  —  Bob Ray