Migrating to MODx 0.9.7
Important Note: Following the steps documented here, I created a semi-working version of my original site. At some later point, I ended up with a corrupted MySQL database with some of the content from this site leaking into the database tables of other 0.9.6 sites I had on the same (localhost) server. I did a lot of goofing around, and 0.9.7 is in pre-release mode, so I don't know if the migration I documented here contributed to the problem or not. YMMV but I thought you'd want to be warned.
Migrating an existing site to MODx 0.9.7 is definitely not for the faint of heart and absolutely not for people new to MODx. MODx 0.9.7 hasn't officially been released yet and I suspect that there is no exhaustive list of the steps necessary to make the conversion. The information on this page is incomplete and only here as a potential resource for testers and those who can't wait to get started with 0.9.7.
Eventually, there will be automated processes to help with the conversion and, ultimately, the whole process may be automated. If you have a large site with a lot of content and many custom snippets and chunks, you may want to look at some of the tools mentioned in this thread at the MODx Forums.
The site I'm converting here is relatively modest and I'm simply documenting here the (very low-tech) way I made the conversion.
The basic steps I followed in Migrating the site to MODx 0.9.7 from an earlier version are:
- Install 0.9.7.
- Do an SQL dump of the appropriate tables in the old site.
- Convert the MODx tags in the .SQL dump files to the new format.
- Import the modified .SQL files into the new site.
- Edit the new fields in in PhpMySQL.
- Move the files to the new site.
- Clean up any remaining problems
- Manually create the user permission structure.
Installing MODx 0.9.7
The MODx 0.9.7 Beta hasn't been released yet as I write this, although it may be available by the time you read it. Go here to see if 0.9.7 is available. If not, you'll need a Subversion (SVN) client to checkout the current MODx 0.9.7. For Windows, Tortoise SVN is recommended, and for Mac OS X try SVN X.
In your SVN client, put http://svn.modxcms.com/svn/tattoo/tattoo/branches/0.9.7/ in the window that asks for the URL of the repository. In TortoiseSVN, you'll do this in the Repo Browser, then, once you connect to the repository, right-click on 0.9.7 and select "check out." Once you specify the directory where you want MODx 0.9.7 and click on the OK button, the files will download to your local machine. Be sure to put the files in a directory accessibly by web browser through your localhost web server.
If you get 0.9.7 through the SVN process, you'll need to follow the steps here to install it. Note that the 0.9.7 install directory is called "setup" not "install" as it was in previous versions.
You should be able to log in to the Modx Manager of the new site. If you're using the SVN version I have, there's no site content at all so you can't preview the site. Make sure Friendly URLs are turned off, for now, in Tools | Configuration | Friendly URLs.
Exporting Tables from the Old Site
Go into the old site database using PhpMyAdmin (or the equivalent).
NOTE: For each export, check the save as file check box near the bottom. Check the Add IF NOT EXISTS checkbox.
- Select the modx_categories table and export it.
- Select the modx_site_contents table and export it.
- Select the modx_site_templates table and export it.
- Select the modx_site_htmlsnippets table and export it (these are your chunks).
- Select the modx_site_snippets table but only export your own snippets. Don't export any of the MODx built-in snippets.
Converting the MODx Tags
Converting the MODx tags in the .SQL dump files is a matter of doing 12 search-and-replace operations. If you have an editor that allows you to do search and replace on selected files as a group, you can just go through the list once. If you have to work on each file, it might be worth making a macro to perform the replacements. You could also cut down the steps considerably if your editor has regular expression search-and-replace and you're good at using it.
First, here's an overview of the tag changes:
Content Elements
| Old | New |
|---|---|
| [*TemplateVariable*] | [[*TemplateVariable]] |
| {{Chunk}} | [[$Chunk]] |
| [[Snippet]] | [[Snippet]] |
Content Tags
| Old | New |
|---|---|
| [+Placeholder+] | [[+Placeholder]] |
| [~Link] | [[~Link]] |
| [(system_setting)] | [[++system_setting]] |
| No Tag | [[%language_string_key]] |
Cache Control
| Old | New |
|---|---|
| [!Snippet!] | [[!Snippet]] |
| No Tag | [[!$Chunk]] |
| No Tag |
[[!*TemplateVariable]] |
Here are the replacements:
- Replace [* with [[*
- Replace [+ with [[+
- Replace [~ with [[~
- Replace [( with [[++
- Replace [! with [[!
- Replace {{ with [[$
- Replace *] with ]]
- Replace }} with ]]
- Replace +] with ]]
- Replace ~] with ]]
- Replace )] with ]]
- Replace !] with ]]
Do the conversions above for all the .SQL dump files that might need them. You can skip the modx_categories file. It's a good idea to do the conversions in your editor and then "Save As:" fileneme-converted.sql.
Importing the Old Data into the New Database
Importing the modx_site_contents table
If you downloaded the release version of MODx 0.9.7, there may be some content in the modx_site_contents table. You should probably back up, then empty that table before completing the following steps.
The first file/table I imported was the modx_site_contents file, but there's a catch. In MODx 0.9.7, this table has three extra fields. There's probably a way to do the import without the new fields in the .SQL file, but I couldn't make it work. Instead, I created a whole new database called "dummy" on my machine and imported the old modx_site_contents-converted.sql file into it. Then I added the three new fields to the end of the structure of that database. I then exported the altered table from the dummy database and then imported that table in to the new O.9.7 database. Here are the steps in order (these are for PhpMyAdmin -- you'll have to translate them if you're using something else):
In PhpMyAdmin on your local machine, create a new database called "dummy." Be sure the character set and the collation match those in your MODx 0.9.7 database.
After selecting the "dummy" database, click on import and bring in the translated modx_site_contents-converted.sql file.
Select the modx_site_contents table in the "dummy" database and click on the structure tab.
Scroll down to the end of the first table and, next to word Add, change the 1 to a 3 and click on the Go button.
Fill in the information for the following three fields (the collation field may be different):
Click on the Save button.
Click on the Export tab at the top of the page, check the save as file check box near the bottom. Check the Add IF NOT EXISTS checkbox.
Click on the Go button at the bottom right.
Save the SQL dump to a file called modx_site_contents-dummy.
Change to the new 0.9.7 database using the drop-down box at the left.
Click on the Import tab.
Click on the Browse button, browse to the modx_site_contents-dummy.sql file you just created and click on the Go button at the bottom right.
You should see a message telling you that your import was successful.
At this point, you should be able to go to your site (http://localhost/yoursite) and see some version of your home page. There's no .css file yet and no template so it won't look very good, but it's encouraging to see some of your content. If you can't see it, make sure that the site start that is set in the Manager's Tools | Configuration section matches the page number of the home page in your modx_site_contents table.
Importing the modx_categories Table
This table contains the user-defined categories (if any) that are associated with the various MODx elements (ie. chunks, snippets, etc). If you have defined categories and fail to import this file, you many only be able to edit uncategorized elements.
Importing the modx_site_templates Table
Make sure you've done the search-and-replace conversion on the SQL dump file for the modx_site_templates table. Import the table into the new site.
Importing the modx_site_htmlsnippets Table
Make sure you've done the search-and-replace conversion on the SQL dump file for the modx_site_templates table. Import the table into the new site. Your chunks should now be in place but any snippets they call will be missing.
Importing the modx_site_snippets Table
Make sure you've done the search-and-replace conversion on this table and import it into the new site. This should add your own snippets to the site.
Import Troubleshooting
- If your import results in an error message telling you that the table already exists, you probably forgot to check the Add IF NOT EXISTS checkbox when you exported it.
- If you get an error message complaining about duplicate ID numbers, the table at the new site wasn't empty. Go into PhpMyAdmin and empty the table and try the import again. The version of 0.9.7 I used came with no templates and no default content so this wasn't a problem for me, but later versions may have some content in the tables.
Copying the .CSS file(s)
Copy any .CSS files at the old site to the same location at the new 0.9.7 site.
Finishing Up
Now that you have templates, chunks, and .CSS files in place, your home page should look approximately normal except that any snippet content generated by MODx snippets other than your own may be missing. The version of 0.9.7 I checked out had no snippets at all. The snippets are being converted and some or all may be included by the time you read this. If not, you may be able to download the current SVN version of the 0.9.7-compatible snippets here.
For snippets that don't appear there, you'll have to install the 0.9.6 versions from the MODx Repository and convert them yourself.
User Management and Permissions
User managerment, roles, and permissions have changed significantly in MODx 0.9.7. I'm still researching how best to make the conversion and whether any of the relevant tables from the old site can be transferred to the 0.9.7 site. If I get it figured out, I'll add the information on this page.
Questions and Problems
If you have any questions about the migration process, ask them on this thread of the MODx forums.
Thank you for visiting BobsGuides.com
— Bob Ray
