Starting with Revo

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.

Some Basics

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.

If you are a PHP coder, there are lots of other things you’re going to love about MODX!

Managing content made easy

Adding and updating content in MODX is very straightforward. Take the MODX manager for a spin right now (username: demo_user, password: demo_user) at trymodx.com.

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.

Don’t panic

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

Manager
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.
Resources
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.
Templates
Your Resources show themselves to the world through a Template, which gives them an outer HTML “skin”.
Snippets
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. …
TVs
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
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
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.

System Requirements

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.

Download

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!

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

Install

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

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

Editing Resources

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.

Title
used by default to indicate the Resource’s name in the Resource Tree
Published
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.

Container
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

Searchable
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
Cacheable
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.)
Deleted
Flags the Resource as deleted. In deleted state, emptying trash will completely remove the Resource from the database.
Content Type
Allows you to change the type of document that MODX serves. Handy for when you want Resources to output XML, RSS, Javascript, CSS. MODX even lets you create your own custom content types.
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:

  1. Create a Template
    1. Give it any Template name you wish
    2. 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)
      
    3. Save your template
  2. Create a Page
    1. From the Resources tab of the manager’s left-hand pane, either create a New Document or Edit the default one named Home
    2. Make sure the Uses Template field is set to your new template
    3. Give the Resource a Title. (After the Resource is created, you’ll see it appear by this name in the Resources tree)
    4. In the Content field, create some test html content; this is going to be inserted into your template where the [[*content]] tag is
    5. Save
    6. Preview to see your awe inspiring new HTML5 site!
    7. 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.

  1. Create a Template Variable(for the sidebar)
    1. Click on the Elements tab in the left-hand pane of the manager
    2. Click the New TV icon, or right-click on Template Variables and select New Template Variable from the context menu
    3. 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?
    4. Set Input Type to Textarea
    5. Go to the Template Access tab
    6. Click on the Access checkbox next to your Template in the list
    7. All the rest of the defaults (empty fields and all) are fine for now. Click Save.
  2. Create another Resource or four(more pages)
    1. Under Site in the main menu, click New Document
    2. Set Uses Template to your Template
    3. Give the Resource a Title
    4. Make sure the Published checkbox is checked
    5. Give the Resource a Menu Title
    6. Add some html content to the Content field for this new page
    7. Click on the Template Variables tab
    8. Add some html for a sidebar for this page into the sidebar TV
    9. Save
    10. 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
    11. Go back to your first Resource and give it a Menu Title and some sidebar HTML as well
  3. Create a Chunk(the copyright notice)
    1. From the Elements tab (left-hand pane of the manager), create a New Chunk
    2. Name it copyright
    3. In the Chunk code field, make a nice little copyright notice
    4. Save
  4. Install the Wayfinder Snippet(the menu)
    1. Under System in the main menu, choose Package Management
    2. Click the Download Extras button
    3. Find Wayfinder listed under Most popular or search for it on the left, click it
    4. Click Wayfinder’s Download button
    5. Click Finish
    6. Next to wayfinder in the package list, click the Install button
    7. Follow the installation steps, clicking the console’s OK button when it’s finished
  5. Update your Template
    1. Edit the Template that you created before
    2. 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>
      
    3. Save
  6. 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.

Next Steps

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.