Porting an Existing Site to MODX

Porting Your Template

(Note: Skip this section if you're just playing around with MODX.)

If you have an existing site that you are porting to MODX, you'll want to create a site template based on the look of your existing site. Take a look at the MODX default template to see some of the things that should be in a MODX template. There's an excellent video here that shows how to make a MODX template based on an existing site.

Here are the basic steps for creating your own:

MODX Evolution:

  1. Click on the Resources tab

  2. Select Manage Resources

  3. Select the Template tab on the right if not already selected

  4. Click on the default template on the right side

  5. Click on duplicate at the top of the right side

  6. Click on yes when asked "are you sure?"

MODX Revolution:

  1. Click on the Elements tab at the left

  2. Click on the Templates section to expand it

  3. Right-click on the Base Template

  4. Select Duplicate Template on the drop-down list

  5. Give your new template a name and click on the "Save" button

Now you have a new template and you can edit it. Click on its name in the tree at the left. Edit the description. Save it.

Now it's time to create your first MODX page. Here's one way to do it. You can actually do most of these steps in any order. Just make sure not to leave any out. It's a good idea to print out the MODX default template to use as a reference. Do these steps one at a time and look at the page in a browser as directed. If you mess up a page, sometimes the browser will show a blank page and it's nice to know what step caused that.

  1. Copy your site's CSS file to the new MODX site and make a note of where it is. There's no right place to put it. Some MODX users create an assets/css folder. Others put it in the site root (where index.php and the Manager folder is) so things will load a little faster.

  2. Paste the code from the <body> section of your home page into the new template's <body> section (later, you'll remove the stuff that doesn't belong there).

  3. In the <head> section of the template, edit the reference to the CSS file so it points to the place where you put your .CSS file in step 1:

    <link rel="stylesheet" href="assets/css/yourcssfile.css" type="text/css" />

  4. Remove the main content of the page (the material that is unique to that page). Save it somewhere or cut it to the clipboard, and replace it with the following MODX content tag:

    MODX Evolution: [*content*]

    MODX Revolution: [[*content]]

  5. Save your new template.

Porting Your Content

  1. Now, in the MODX Manager, create a new document. See the Getting Started page if you need help on how to do it.

    Important: Make sure the "rich text" editor is OFF before pasting any code. Go to the Page settings tab. Uncheck the rich text checkbox. Save the document. The rich text editor will now be off and will not try to be "intelligent" about saving your code.

    You can turn the Rich Text editor back on after you're done porting your page by checking the rich text checkbox and saving the document.

  2. Fill in the Title and Alias fields. These are the only two required fields. The Alias will be used for the URL of the page and is typically a lowercase version of the Title with hyphens instead of spaces. Create a Long Title for your document and, if you want, add a description and summary.

  3. Paste the content you saved from the Home page into the Resource Content field of the new document. If there is any PHP code on the page, you'll have to remove it and save it somewhere. It will have to go in a snippet (or snippets if there's more than one section) to be created later. If there is a menu on the page, save it somewhere for future reference and replace it with the following snippet tag:

    MODX Evolution: [!Wayfinder? & startId=`0`!]

    MODX Revolution: [[!Wayfinder? & startId=`0`]]

  4. If there are images in the page content, you'll have to move the image files to the MODX site. They can go anywhere, but the assets/images directory is a common place for them. You'll also have to correct the links in the page content to point to wherever you put them.

  5. If there are links to other pages on your site in the page content, wait to correct them until you have created the documents they point to. Then, make a note of their document ID numbers (in parentheses in the Resource tree at the left side of the Manager screen) and change the links to look like this (using the actual document ID numbers instead of "999"):

    MODX Evolution: <a href="[~999~]">My link</a>

    MODX Revolution: <a href="[[~999]]">My link</a>

  6. Save the new document. Right-click on the document in the Resource tree at the left of the screen and select View Resource. You should see your original page, more or less, but with an abbreviated, unstyled, Wayfinder menu. The page may be styled strangely, but you should see your content and some of your own styling from the .CSS file.

  7. Now go back and edit the template you created. In the head section, replace the title code with a title content tag like the one in the MODX default template:

    MODX Evolution: <title>[(site_name)] | [*pagetitle*]</title>

    MODX Revolution: <title>[[++site_name]] | [[*pagetitle]]</title>

    Preview the page again to make sure this worked. You should see your page title in the title bar at the very top of the browser window.

  8. At the top of section where your main content goes (just above the content tag), insert a longtitle content tag:

    MODX Evolution: <h2>[*longtitle*]</h2>

    MODX Revolution: <h2>[[*longtitle]]</h2>

    Preview the page again. You should see your longtitle as a heading above your content. If you would rather have the longtitle below the content, just move the tag.

  9. You'll probably have some cleaning up and styling to do, but you should now have the beginnings of a MODX site. The Wayfinder menu is infinitely styleable (with drop-downs, flyouts, etc.), but that is beyond the scope of this section.

  10. To port the rest of your pages, you should be able to just create new documents in MODX and paste their unique content into the Resource Content field. They will automatically show up in the Wayfinder menu.

If your site has a "tree" structure or a hierarchy of documents. You will want to duplicate that on the MODX site.

To create a child document, you can right-click on the parent in the Resource tree and select Create | Create a Document Here. If you forget or you want to reorganize the structure later, you can set a document's parent by clicking on the "Parent" field (on the Page Settings tab) when editing the document and selecting the desired parent in the tree at the left. You can also drag parents and children around in the tree with your mouse. Your menu will generally show the documents in the order they appear in the Resource tree at the left. Don't forget to Save the document after doing this (or making any other changes on the Create/Edit Resource panel).

Porting Your Files

Yous site probably has some files that need to be moved as well. There's no need to move your .html files because their content will be in the MODX database, but you may have some CSS files, JavaScript files, text/data files, or other files that the site will need. These can go anywhere as far as MODX is concerned, but for typical locations for them, look here.


My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book may still be 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