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. Click on duplicate at the top of the right side

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

Now you have a new template and you can edit it. Change the name to whatever you like and edit the description. Save it.

Now it's time to create your own 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 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 MODx Resource tag:

   MODx Evolution: [*content*]

   MODx Evolution: [[*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. When you create the document, check the continue editing radio button at the top of the page so you won't have to keep selecting edit. 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. Paste the content you saved into the Resource Content field of the new document. If there is any PHP code on the page, you'll have to remove it. 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`]]

3. 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.

4. If there are links on the page, 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>

5. Save the new document. Right-click on the document in the Resource tree at the left of the screen and select Preview document. 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.

6. 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.

7. 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.

8. At the bottom of the body section (perhaps in your footer), you may want to add the Powered By MODx line from the original MODx default template.

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 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. Make sure that any document that will have children is designated as a "container" by checking the "container" checkbox on the document's create/edit page.

To create a child document, you can right-click on the parent in the Resource tree and select create document here. If you forget or you want to reorganize the structure later, you can set a document's parent by clicking on the little folder icon just above the Content field in the document's create/edit page (on the General tab) and then clicking on the desired parent in the Resource tree at the left of the screen. Don't forget to save the document after doing this (or making any other changes on the create/edit page).

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.