What is MODX Revolution
MODX Revolution is a Content Management System and platform for building websites and web applications. It is ideal for small and large scale projects alike. MODX is used by both non-programmers and programmers to build web solutions that can be easily managed by end users.
HTML is a first-class citizen
You don’t need to know PHP to build stuff in MODX. One of the things you’re going to love is the fact that HTML comes first. You control the HTML completely, from top to bottom, and use tags to inject all of the cool dynamic stuff wherever you need it.
Managing content made easy
If your project requires custom data, MODX gives you the tools to build great-looking and secure custom user interfaces right in the manager.
Add-ons and Extras
MODX Revolution’s unique architecture allows it to be extended in so many ways. Not only are these Extensions and Add-ons easy for the community to create and share, you can install and upgrade them with just a few clicks right from inside the Revo Manager.
MODX Revolution starts as a completely clean slate allowing site builders to add just what they need. This can be disorienting if you have used another (we might say less flexible) CMS. You’ll be on your way in no time though - more on that below.
MODX’s legendary flexibility is probably one of the reasons you’re here. Embrace this, remember that there are often several ways of doing something, have fun, let MODX play to your strengths and you’ll be fine. (If you do panic, visit our wholly remarkable community at the MODX forums and don’t be shy.)
Key MODX Concepts
- The Manager is the back end “control panel” for your website, usually accessed at your-web-address.com/manager/. You’ll set up your Admin username and password when you install MODX.
- In MODX, website content is generally organized around Resources, virtual web pages stored in the database. Technically a MODX Resource represents, amazingly, a web resource. Many Resources in your sites will be documents, which themselves can represent a web page, a product, a blog post, etc. Resources can also link to other web pages (“Weblinks” and “Symlinks”), or manage actual files on the web server (“Static Resources”). Resources can also create dynamic XML, RSS feeds, or other document formats than typical HTML web pages. Read more about Resources.
- Your Resources show themselves to the world through a Template, which gives them an outer HTML “skin”.
- Snippets are bits of php code that inject dynamic functionality into content. You just insert Snippets wherever you want in your HTML via a simple tag. Examples: a shopping basket, site navigation, adding user generated comments to anything in your site etc. …
- Template Variables (TVs) are custom fields that you create when you need to add new fields to your content. They automatically appear for your users to edit in the manager, and you add them to your HTML with a simple tag.
- Chunks may be the simplest concept in this list. They just contain HTML (which can contain other MODX tags, even other Chunks!) A Chunk is inserted into your HTML via a tag (surprise!) Don’t let this simplicity fool you - Chunks are a key part of MODx Revolution’s powerfully flexible awesomeness.
- Plugins, like Snippets, are bits of php code. However, while Snippet code runs wherever a Snippet tag is found, Plugins are different. They are triggered by various system events, so they can extend MODX’s behavior in all kinds of ways. No core hacks required.
MODX will run in a wide variety of PHP-enabled environments. The best-case scenario is latest stable versions of:
- Apache 2.2 or IIS 7
- MySQL 5.1
- PHP 5.3 (with PDO enabled)
If your host meets these specs, you most likely will have no problems. For full requirements, see our server requirements documentation.
If you’re just starting with MODX, go to our download page and get the traditional install package which should work on virtually all servers, including shared hosts. Unless absolutely necessary, use the traditional installation when starting.
If you are an an experienced MODX user, you can explore advanced ways to customize your configuration and with alternate installations. But then again if you’re an advanced MODX user you’re probably not reading this page!
- This is recommended if you wish to move MODX’s core files, Manager or connectors directories, you have SSH access and are familiar with making folders writable.
- From Source
- MODX Revolution’s code is open source and is hosted at GitHub. If you’re the bleeding-edge sort—maybe you want to contribute to the project or you’re just morbidly curious—read how to build and install from Git.
MODX is easily installed or upgraded in just a few minutes by uploading files to your website and following the web based setup through a few steps. Read install documentation
Get to know the Manager
The Resource Tree
90% of your content management work in MODX will be spent editing or creating resources. The MODX manager’s resource tree makes this very straightforward, allowing you quickly find the resource you want to edit, or to add new resources with one click. Right-clicking a resource in the tree gives you a context menu from which you can edit or perform a number of other actions on the resource.
When you are editing a Resource, the Create/Edit Resource tab contains all of the default fields associated with the Resource. All of these fields can be placed in your HTML via tags, but some of them carry additional functionality or meaning.
- used by default to indicate the Resource’s name in the Resource Tree
- controls whether the Resource appears in the site
- Resource Alias
- with Friendly URLs (a system setting) enabled, makes up part of the page’s friendly URL
- Link Attributes
- can be used to inject HTML attributes into links to the Resource in menu-builder Snippets
- Menu Title
- menu builders use this field, by default, to name the Resource
- Menu Index
- determines the order of this Resource in a list, when Resources are being summarized, listed or menus are being built
- Hide from Menus
- when checked, can indicate that a Resource is not to show up in a menu
The manual contains additional detail about Resource fields and how to use them.
The Page Settings tab of the Edit Resource screen contains many fields that control how MODX treats the Resource.
- This is automatically checked if the Resource “contains” other Resources, i.e. if it is the parent of other Resources in the tree. The field can also be checked if you want the Resource to behave as if it is a Container (you would have set up some custom behavior in a menu builder or similar functionality)
- Rich Text
- If you have a Rich Text Editor (RTE) installed (which is easily done in Package Management) and this checkbox is checked, then the Content field and any rich text Template Variables will appear in the RTE.
- Published On
- A date/time field to track when the Resource was published
- Publish Date
- Used to control when the Resource will automatically become published
- Unpublish Date
- Used to control when the Resource will automatically become unpublished
- If you have a site search Snippet or some other search functionality on your site (maybe a Google Analytics helper), this field can indicates whether you want the Resource to appear in searches or not
- If the Resource is Cacheable, the first time MODX “parses” or assembles this resource into HTML for the browser, the HTML is saved to the caching system. This can improve the performance of your site in certain situations by decreasing the load on your database server. MODX’s caching is more configurable and granular than this, however; there are certain tricks you can do to cache only parts of pages. More tech jargon on caching can be found on our documentation site.
- Empty Cache
- When this is checked, MODX will empty the site cache when you save this Resource. This will result in all pages being rebuilt from the database as they are viewed. (This is normally what you want, so that you can actually see the changes you’ve made appear in your site.)
- Flags the Resource as deleted. In deleted state, emptying trash will completely remove the Resource from the database.
- Content Type
- Content Disposition
- Normally Inline but if you want a Resource to be directly downloadable, you can change to Attachment
- Class Key
- This is used by Ninjas
Elements and Files
There are also easy-to-use trees for managing your Templates, Snippets, TVs, Chunks and Plugins (all under the Elements tab), and for the built-in file manager (under the Manage Files tab) where you and your users can upload and manage files. With this common tree paradigm, combined with customizing the manager for your users, your training sessions should be a breeze.
Learn by Example: Install a Sample Site
- Log into your manager
- Navigate to System > Package Management
- Click the “Download Extras” button
- In the dialog that pops up, open the tree node named “Site Packages” and click on “DemoSites”
- Choose a site and click it’s Download button
- When it’s finished downloading, click OK
- The demo site will be shown in your list of packages, and you will then be able to click on it’s Install button.
- From the main manager menu, choose Site > View to view the website
- Explore the various Resources and Elements (tabs in the left-hand pane of the manager) to see how the site is constructed
Learn by Doing: Build your first site
Step 1: Hello World
It’s this easy to create your first content-managed web page:
- Create a Template
- Give it any Template name you wish
- Copy and paste the following html into the Code field:
<h1>My First MODX Site</h1> (top of template) <hr /> <div id="main">[[*content]]</div> <div id="sidebar">Email me at me //at// example.com</div> (bottom of template)
- Save your template
- Create a Page
- From the Resources tab of the manager’s left-hand pane, either create a New Document or Edit the default one named Home
- Make sure the Uses Template field is set to your new template
- Give the Resource a Title. (After the Resource is created, you’ll see it appear by this name in the Resources tree)
- In the Content field, create some test html content; this is going to be inserted into your template where the [[*content]] tag is
- Preview to see your awe inspiring new HTML5 site!
- Read The Free Manual to see what else is possible
You now have a web page whose content you can edit in the MODX manager and whose HTML you have 100% control over! How long did that take? 8 seconds?
Step 2: MODX Fu FTW!
Now we’ll explore Snippets, Chunks and Template Variables by adding more pages, a sidebar, a copyright notice and dynamic navigation to the site.
- Create a Template Variable(for the sidebar)
- Click on the Elements tab in the left-hand pane of the manager
- Click the New TV icon, or right-click on Template Variables and select New Template Variable from the context menu
- On the General Information tab, give your new TV a name - make the Variable Name sidebar. Guess what we’re going to use this TV for?
- Set Input Type to Textarea
- Go to the Template Access tab
- Click on the Access checkbox next to your Template in the list
- All the rest of the defaults (empty fields and all) are fine for now. Click Save.
- Create another Resource or four(more pages)
- Under Site in the main menu, click New Document
- Set Uses Template to your Template
- Give the Resource a Title
- Make sure the Published checkbox is checked
- Give the Resource a Menu Title
- Add some html content to the Content field for this new page
- Click on the Template Variables tab
- Add some html for a sidebar for this page into the sidebar TV
- Repeat if you want more pages to play with in your site. hint: you might try using the Duplicate button to duplicate an existing resource
- Go back to your first Resource and give it a Menu Title and some sidebar HTML as well
- Create a Chunk(the copyright notice)
- From the Elements tab (left-hand pane of the manager), create a New Chunk
- Name it copyright
- In the Chunk code field, make a nice little copyright notice
- Install the Wayfinder Snippet(the menu)
- Under System in the main menu, choose Package Management
- Click the Download Extras button
- Find Wayfinder listed under Most popular or search for it on the left, click it
- Click Wayfinder’s Download button
- Click Finish
- Next to wayfinder in the package list, click the Install button
- Follow the installation steps, clicking the console’s OK button when it’s finished
- Update your Template
- Edit the Template that you created before
- Replace the Template code with this:
[[*pagetitle]] <!-- insert CSS here --> <div id="nav">[[!Wayfinder? &startId=`0`]]</div> <div id="main">[[*content]]</div> <div id="sidebar">[[*sidebar]]</div> <p>[[$copyright]]</p>
- View the site (Site > View from the main menu)
See how simple it is to add Resource fields (e.g. Title = pagetitle, Content = content), the sidebar Template Variable, the copyright Chunk and the Wayfinder menu builder snippet to the Template HTML? Only about 25 seconds, right? When you’re done saving your template, re-review the site from the front end. After doing so, add another page in the tree menu and re-review the site from the front end. You should now see that page in the Wayfinder navigation.
We’ve introduced you to MODX, explaining the core concepts, how to create and edit content, and how to convert a very simple template into a fully functional MODX site. Find out more at the MODX Revolution Documentation.