Getting Started with MODx
Before starting this section, you'll want to read the basic introduction to MODx and how it works here if you haven't done so already.
The MODx Manager is where you'll do most of the work on your site. The great thing about the Manager is that it is completely web based. You can work on your site from anywhere with any web browser. The Manager uses Ajax to make things relatively fast and smooth.
Getting Started
Once you have installed MODx, you can reach the manager by pointing your browser to http://yoursite.com/manager and logging in (where "yoursite.com" is the location of your MODx install). Once you log in, you'll be looking at the MODx Manager screen. Here you can change configuration details; add or edit web pages; create snippets, chunks, templates, snippets, and plugins; manage users and permissions; and much more. If you don't know what all that means, relax, it will all make sense eventually.
You can see the "front end" of your site, the site that regular users will see, by going to the same address but leaving off "manager." (The MODx Manager is considered the "back end.") You can also see the "front end" by selecting Preview on the Site tab but there's a drawback to this. Because MODx knows you are logged in as a Manager, you won't necessarily see the site as a regular use would. This wouldn't be much of a problem now, but as your site grows more complex, this view might be very different from the one a Manager sees. If you want to review your changes as you work on a site, it's usually a good idea to open the "front end" in a different browser from the one you're using in the Manager. It's not enough just to use a different browser window because, in that case, MODx will still think you're a Manager as long as you're logged in to the Manager. If I'm editing a site in IE, for example, I'll open the "front end" in FireFox (or vice versa).
After installing MODx, your site will be just the default MODx home page (which uses the default template). You'll eventually replace it with your own site, but it's nice to have something there to see so you know the install went without a hitch. The links you see on the default MODx home page are not to places in your site, they're links other MODx sites such as the MODx Resource Repository, the MODx forums, etc. They're just there as examples although some point to useful information about MODx.
NOTE: If you chose to install the sample web site during your MODx install (and it's a good idea for beginners to do so) you will see the content of that web site in the manager. It uses most of the main MODx snippets and a working blog. You can examine it (and modify it) to see how everything works. You can follow the instructions below to add your own content to that site, or you can create a separate, empty MODx site to try out the techniques on this page.
Log in to the MODx Manager as described above. On the left side of the Manager screen, you'll see the document tree for your site. There won't be much there, but it will grow as you add documents to the site. A document in MODx generally holds the distinct content for a particular web page. Most documents are for displayable web pages but the word "document" is used intentionally in MODx because documents can play other roles. Some are just containers for other documents and are never seen by users. A few might be utility pages that you create to perform some chore like searching the site, displaying information about your server, or backing up all or part of the MODx database. On many sites, all the documents are for actual web pages. It depends on the complexity of your site, how much work you want to do, and your programming abilities.
Notice the little number to the right of each filename in the document tree. This is the Document Identifier (also called a Doc ID). It's a very important number because almost all references to documents in MODx are by the Doc ID. If you want to put a link to a document on any page in your site, a correct MODx link contains just the Doc ID. MODx will make sure that the correct document is served up even if its name changes, it's moved, or even if the site is moved to another domain and all the paths change.
Notice the toolbar at the top of the document tree. You can hover the mouse over the icons to see what they do. The one with the little arrow on the right will hide and restore the tree. This is useful if you're editing a document and would like a bigger space to work in.
It's a fact of life in MODx that there are multiple ways to accomplish almost any task. The toolbar at above the document tree has an icon for creating a new document but there are several other ways to do the same thing. Try right-clicking on a document in the tree. You'll see a menu that lets you create a new document or change some of the settings of the document you right-clicked on. As usual, there are other ways to do this too.
On the right side of the Manager screen, if you've just installed MODx, you may also see some messages about MODx security and configuration that will disappear once you follow the advice they give. If you've installed MODx on your local machine, you may choose to ignore them but on a public server, you should clear them up before proceeding.
Notice the colored tabs at the the top of the Manager screen. Each one contains a section of the Manager where various tasks can be performed. Click on each of them and take a look. Don't be alarmed by how many settings there are. Most of the defaults will work fine for you for now.
If you are just playing around with MODx, you can continue to use the default home page and template. Add some new documents, change their settings and edit their content to see how MODx works. Even if you're porting an existing site to MODx, you'll want to go through this section to see how things work in MODx. It's a good idea to practice all the tasks involved in working on a MODx site before trying to plug in important content of your own.
You can create and delete documents to your heart's content. You'll notice that deleted documents still appear in the tree but with a line through them. They'll stay there in the "trash can" until you click on the little trach can icon and delete them permanently. When you're ready to create a real site, just create the documents you really want and delete all the one's you don't want. The only effect of this playing around is that you'll have bigger document ID numbers. This has to happen because every document ID is unique and can't be re-used. It doesn't really matter, though, because those numbers are just used internally by you and MODx and no user ever sees them.
If you don't know what a MODx template is, go back here for an explanation. The MODx default template is just an example of what a template looks like in MODx. You can modify it but it's probably better to create new templates for your own use and leave it for future reference. Lets take a look at the default template. In the MODx Manager:
- Click on the Resources tab at the top of the page.
- Select Manage Resources.
- Select the Template tab on the right if not already selected.
- Click on the default template on the right side.
Before putting your own stuff in a page, take a look at some of the features in the MODx default template. Notice the square brackets with stars inside them
The ones contained here are standard template variables that are available for any MODx document. When you create the document, you'll fill these in on the document creation screen. The most commonly used TVs are title, longtitle, and content. You can also create your own custom TVs, but for now, we'll just talk about the standard ones. Look for the TVs in the template. It's not a bad idea at this point to print out the default template so you can refer to it when you create your own. Note that like most of the references in MODx, TV names are case-sensitive ("MyPage" is not the same as "myPage") so be careful to use the same case when creating and refering to them.
Notice in the default template how the title TV is used to set the page title (appears at the very top of the browser window). The longtitle TV is used as the main heading for the page and the content TV contains the document's actual content (what the user sees in the body of the web page). If this is unclear, it will make more sense after you create a document or two. It might help to look at the "front end" in another browser to see what MODx replaces them with. You can also right-click on the home document in the document tree and select Edit document. This will show you the document's TV fields although it will take you away from looking at the default template and you'll have to navigate your way back by following the numbered steps above.
You might also notice that, in the default template the content tag has a pound sign after the first star. This means that users who are logged on and have the appropriate permissions can edit the content text using the MODx QuickEdit editor from the "front end" of the site. You'll see the QuickEdit button next to the content if you "preview" the site while logged in to the MODx Manager. Another thing to look for in the default template is snippets which look like this:
You should see the Wayfinder snippet and the PoweredBy snippet. The Wayfinder snippet creates the menu at the side of the page and the PoweredBy snippet creates the "Powered by MODx" message in the footer.
By the way, there's nothing special about the term "default template." It's just what that template happens to be called. You can change it's name without causing any trouble.
Take a look at the site from the "front end" (when you are in the Modx Manager, we say that you're looking at the site from the "back end"). There are two ways to see the "front end" of the site. Although we advised against it above, for now, try selecting Preview on the Site tab in the MODx Manager.
In looking at the home page from the Preview "front end", you can see that MODx has replaced the Wayfinder snippet with a menu and the PoweredBy snippet with a message about MODx at the bottom of the page. Since you are logged in to the manager, you should also see a little QuickEdit button next to the page content when you Preview the page. (Users who are not logged in won't see that.) When you look at the "front end" through Preview, you see the little edit button next to the page content. Earlier, we mentioned the pound sign next to the content tag in the default template. That's what tells MODx to put the QuickEdit button there. In the upper left corner of the page, you should also see a little menu that provides yet another way to change some of the page's settings. The Go drop-down menu there will take you back to the "back end," the MODx Manager.
Now it's time to add some content to the site by creating a new page.
Creating a New Document
Now, let's create a new document that will be used in a new web page. Remember that a web page is what the user sees in his or her browser, a document contains the unique content of that page and information about that page. First, we'll create a new document and then we'll add some content to it. In the MODx Manager, right-click on the MODx home page in the document tree on the left side of the screen and select Create document here. The create/edit document page should open on the right side of the screen. Notice that the page has three tabs, General, Page Settings, and META keywords. We'll start on the General tab. Note that if you scroll down, the tabs will disappear but they're still there if you scroll back up.
Fill in:
- "New Document" in the Title field
- "My New Document" in the Long title field
- "NewDocument" in the Document alias field
- "New Document" in the Menu title field.
You can use other terms in the fields if you like. Documents in MODx are always referred to by document ID numbers so the content of these fields is completely up to you.
Use the drop-downmenu next to Uses template to set the template to either the default template or (if you created a new template) to the one you created.
Now, click on the Page setting tab and make sure that the Published? checkbox is checked. If it's not, your document won't show up in the "front end" of the site. This is handy for working on pages that aren't yet ready for publication. (Note for future reference: Whether the Published? checkbox is checked by default when you create a new document is set in the Tools | Configuration section near the bottom of the Site tab.)
Make sure, also, that the Empty cache checkbox is checked. This is the default and it's important because without it, MODx will often serve up a cached version of a page and any changes you've made won't appear. They're still there but you won't see them until the cache gets cleared. (You can also clear it manually by selecting Clear Cache on the Site tab). With the Empty cache checkbox checked, you won't have to worry about the MODx cache because MODx will clear the cache every time you save the page although it's good to remember that your browser can still serve up an older version of the page from its cache.
Notice also that you can set the Published date and the Unpublished date by clicking on the little calendar icon next to those fields. MODx will automatically publish the document on the Published date and unpublish it on the Unpublish date. If these are left blank, the document will be published or not depending on the Published? checkbox. Don't change any of the other fields but take a look at them for future reference.
On the right, notice that there is one scroll bar for the document and, unless you have a very high-resolution monitor, another for the browser window. You often have to use both to edit a document. Scroll down to expose the Content window. This window will be visible no matter which tab you are on. The text you enter in the Content window will appear wherever you put the
Enter some text. Notice that if the Rich Text checkbox on the Page Settings tab is checked, you can use the quasi-WYSIWYG editor to style the page. (Note for future reference: In the Tools | Configuration section near the bottom of the Interface and Features tab, you can set the .css file that the editor will use. If you set it to your site's .css file, the styles you've set there will be available in the editor's --Styles-- drop-down menu.)
If you prefer working in raw HTML, uncheck the Rich Text checkbox. There is an HTML button on the Rich Text editor that let's you see and edit the raw HTML, but using it can cause problems when the editor tries to be intelligent in figuring out what you want and changes some of your code when the page is saved. Unchecking the Rich Text checkbox will prevent this. Changing the setting of the Rich Text checkbox won't take effect until you save the page.
The Save link at the top of the page does just what it says. For convenience, there is also a Save link at the bottom of the page. Notice the radio buttons at the top of the screen that determine what happens when you save a page. You can add another page, continue editing the current document, or close the document depending on which one is checked. If you attempt to navigate away from a page you have edited but not saved, you'll get a warning message telling you that your work will be lost if you don't Save the page first.
When you've finished entering your text, scroll to the top or bottom and click on Save. Your new document should appear in the document tree at the left of the screen. Notice the number in parentheses next to the document. This is the document's document identifier (or doc ID) we talked about earlier. This is the number that MODx uses to refer to the document. It will never change and you should always refer to the page by this number in links or other references since it will be good even if the page is moved in the site, the site moves to a new domain, or the document's title changes.
Adding the New Document to the Menu
Take a look at your document from the "front end" using one of the methods described above. If you have the Wayfinder snippet call in your template, you should see that the new document is already there in the menu. Is this a great CMS or what? Generally, every new page will automatically show up in a properly configured Wayfinder menu as long as it's published and the show in menu checkbox is checked. The only exception to this is a page that has permissions set to deny certain users access to the page, but that's a topic for another time. Notice that the reference in the menu is what you entered in the Menu Title field when you created the document. As long as all your links refer to the Doc ID, you can change the Title, Longtitle, and Menu Title fields as often as you like. In fact, you can change any of the fields by right-clicking on the document in tthe document tree and selecting Edit document.
When you were looking at the General tab when creating your new document, you may have noticed the Menu index field. This allows you to set the order of menu items in any Wayfinder menu. An item with a menu index of 0 will show up at the top of its menu. If you want a document to always be listed as the last item in any menu, you can give it a Menu index of 999. You can change a document's Menu index any time you want to move it up or down in the menu.
What Next?
Create some more pages (documents), and play around until you're comfortable with creating, configuring, and saving pages. You can edit an existing document (or change its settings) by right clicking on the document in the tree and selecting Edit.
To put a link to another document on a page if you are using the Rich text editor, you can just highlight the text for the link and click on the link icon in the editor toolbar. (If you are using the default TinyMCE editor, it looks like a chain link.) For the URL of the link, simply put
To return to the main MODx page, click here.
Thank you for visiting BobsGuides.com
— Bob Ray
