Starting with Evo

What is MODX Evolution

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

Managing content made easy

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

Add-ons (Snippets, Plugins, Modules)

MODX Evolution’s architecture allows it to be extended in many ways. A ton of Add-ons are created and shared freely by the community.

Don’t panic

MODX Evolution 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”). Resources can also create dynamic XML, RSS feeds, or other document formats than typical HTML web pages.
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 Evolution’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 (though still works on 4.x)
  • PHP 4.4 or 5.3

Download

If you’re just starting with MODX, go to our download page.

From Source
MODX ‘s code is open source and is hosted at GitHub.

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 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 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.
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
Elements and Files

There are also easy-to-use tabs for managing your Templates, Snippets, TVs, Chunks and Plugins (all under the Elements > Manage Elements menu), and for the built-in file manager (under the Elements > Manage Files menu) where you and your users can upload and manage files.

Learn by Example: Install a Sample Site

When you install MODX Evolution, you are given the choice to install a Sample Site. If you choose this option, you will be able to browse around and interact with the site on the front end, and have a look around in the Manager to see how it’s made.

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:
      <!doctype html>
      <html>
          <head>
              <title>My First MODX Site</title>
          </head>
          <body>
              
              <p>(top of template)</p> <hr>
              
              <div id="main">
      [*content*]
              </div>
              
              <div id="sidebar">
                  Email me at me //at// example.com
              </div>
              
              <p>(bottom of template)</p>
          </body>
      </html>
      
    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 > Manage Elements menu, then the Template Variables tab
    2. Click the New Template Variable link
    3. Give your new TV a name - make the Template 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 section further down the page
    6. Click on the 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. Click the New Resource icon above the left-hand tree
    2. Set Uses Template to your Template
    3. Give the Resource a Title
    4. Give the Resource a Menu Title
    5. Add some html content to the Content field for this new page
    6. Make sure the Published checkbox is checked on the Settings tab
    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 > Manage Elements menu, on the Chunks 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 (html) copyright notice
    4. Save
  4. Update your Template
    1. Edit the Template that you created before
    2. Replace the Template code with this:
      <!doctype html>
      <html>
          <head>
              <title>
      [*pagetitle*]
              </title>
              <!-- insert CSS here -->
          </head>
          <body>
      
              <div id="nav">
      [!Wayfinder? &startId=`0`!]
              </div>
      
              <div id="main">
      [*content*]
              </div>
      
              <div id="sidebar">
      [*sidebar*]
              </div>
      
              <p>
      {{copyright}}
              </p>
      
          </body>
      </html>
      
    3. Save
  5. 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. You can find out more in the MODX Evolution documentation.