Category Archives: MODx

WordPress vs. MODx

There are a lot of Content Management Systems (CMS’s) out there, so I wanted to give a blow-by-blow analysis comparing two of them: MODx and WordPress. I feel oddly qualified to do so: Brian and I just authored a book on WordPress plugin plugin development (WordPress 3 Plugin Development), and I am a MODx Solution Partner who was invited to speak at the MODxpo conference in Dallas last year. I’ve used both flavors of MODx (Evolution and Revolution) and WordPress while building somewhere around 50 web sites over the past couple years, and I like both systems. I have even contributed a couple plugins for both systems (e.g. Custom Content Type Manager for WordPress). So after the urging of some friends and colleagues (like Kris), I’m organizing my techno-ramblings into a coherent article.

I’m going to walk through a series of areas and compare and contrast both how both CMSs work in those areas. The comments here apply to WordPress 3.x and (mostly) to MODx Revolution, but MODx Evolution is mentioned where appropriate.

Basic Stuff

System Requirements

WordPress 3.1 MODx Revolution
Server OS ???
  • Linux x86, x86-64
  • Windows XP
  • Mac OS X
Web Server
  • Apache ???
  • NGINX ???
  • Apache 1.3.x or Apache 2.2.x
  • IIS 6.0+
  • Zeus
  • lighthttpd
  • Cherokee
  • NGINX
Database
  • MySQL 4.1.20 or higher (5.0+ recommended)
  • SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, DROP privileges
  • MyISAM table types
  • MySQL 4.1.20 or higher (excludes 5.0.51)
  • Default table encoding of UTF-8
  • SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, DROP privileges
  • InnoDB and MyISAM table types
PHP Version 4.3+ (5.2+ recommended) 5.1.1+ (excluding 5.1.6/5.2.0)
 

  • Running as FastCGI
  • safe_mode off
  • register_globals off
  • magic_quotes_gpc off
  • PHP memory_limit 24MB or more

PHP Modules ???
  • zlib
  • JSON
  • cURL
  • ImageMagick
  • GD lib
  • PDO, with database driver
  • SimpleXML

*Source: WordPress requirements, MODx requirements

If the requirements for MODx Revo look insanely detailed, ask yourself this: “do you really want to be guessing whether or not your server will support a given app?” MODx Revo does a pretty good job of testing for the necessary requirements during installation, so you don’t have any unexpected surprises.

Installation

WordPress offers its “famous” 5-minute install, and I give them credit where credit is due: WordPress is a simple web app to install, but to be fair, installing MODx Evolution is also very straightforward.

MODx Revolution has beefier requirements, and it’s far more likely you’ll run into troubles setting up your webserver permissions or PHP extensions (e.g. PDO). Moving a Revolution install to a new server is also a tricky operation that requires some patience (see this how-to).

Summary

In short, WordPress and MODx Evolution are easily installed on practically any web server that supports PHP and MySQL. MODx Revo takes longer to install and configure and it requires a beefier server.

Templating

Hands down, MODx offers the gold standard in templating. Expression Engine is a healthy second place, but only in my days of doing Perl development with the venerable Template Toolkit did I encounter a templating system that followed good MVC architectural principles as well as MODx.

What does that mean? It means that if you’re a front-end designer who likes to roll your own HTML and CSS, then MODx will grant you total freedom to implement the designs you want, whereas WordPress may result in headaches and holes punched in your walls (no comment on the convoluted mess that is Drupal and Joomla templates). I’ve posted previously about creating templates in MODx Evolution and how to import existing layouts into MODx Evolution, and the process in MODx Revolution is nearly identical (the only difference is the format of the placeholders).

In MODx, you can easily have multiple templates (i.e. layouts), and use any one of them for any page. In WordPress, the ability to use a specific template is possible only with pages, not posts. The thing that really gives me convulsions is understanding how WordPress formats its special pages, e.g. a category page, or an author page. See the image below as a reference for how WordPress formats page requests.

WordPress Template Hierarchy
WordPress Template Hierarchy

See the official WordPress docs for Template Hierarchy for more information. I honestly have a hard time fathoming that this is the solution that actually got implemented… what other crazy ideas were on the drawing board?

Summary

If having a specific HTML/CSS layout for your site is more than a “nice-to-have”, then MODx will save you many hours; the time to rework layouts in WordPress can be considerable and some of the PHP hacks are not trivial, whereas MODx templates are easy to create, modify, and maintain.

Menus

MODx offers nearly infinite menu flexibility through use of menu-generating PHP Snippets, primarily WayFinder, but it’s not aimed at the average user. WordPress has a built-in GUI for creating menus, but I have experienced some bugs with it when using custom content types. Your WordPress theme may not support more than one or two menus, so in the end you may end up writing some code in your tmeplates (e.g. using my Summarize Posts plugin) so you can list the posts that you want to see.

In a nutshell, WordPress offers an easy GUI, but if you need more customization MODx’s flexibility here is far greater.

Plugins

WordPress has a huge number of user-contributed plugins available, whereas MODx has relatively few. The sheer number is not a good comparison, however; I downloaded and tested hundreds of plugins in the process of writing my WordPress book, and the number of plugins that are unusable due to sophmoric errors or plain-old bad coding is huge. I estimate that at least half of the plugins in the WordPress repository are unusable, and perhaps only a tenth of them are worth using. There are crufty plugins in the MODx repo to be sure, but the playing field is more even than you might think.

The real difference here comes when you have to write your own code: MODx is a lot easier to work with with a shorter learning curve for a majority of code, whereas learning the ropes of WordPress plugins requires more guidance (hey, did I mention we wrote a book about that?).

Architecture

This is an area that is hard to discuss unless you’re a geek, but in a word, MODx offers a robust and well-architected MVC framework under the hood that can make writing custom plugins (Snippets, manager pages, et al) a breeze. The work done by Jason Coward and Shaun McCormick is really astounding.

Some of the limitations to WordPress are really staggering: it is basically a stateless application, so by default it does not use sessions, and nearly all of its API functions exist as procedural functions in the main namespace, so naming collisions are a big concern when authoring plugins. This makes certain functionality damn near impossible in WordPress. For example, creating a WordPress application with a login portal and access to custom data models would require an enormous amount of time. Even accessing WordPress’s posts and categories is difficult at times; I basically had to rewrite core WordPress functionality with another plugin (Summarize Posts) just to get the menus and summaries I needed for one recent site.

Another severe limitation is WordPress is that all extensions to the core occur via plugins that are triggered by system events (confusingly they are loosely categorized into “actions” and “filters”). This construct can be awkward at times, and the WordPress architecture is showing its age as the number of events exponentially increases, whereas the amount of documentation for them continually wanes. Realistically you can get WordPress plugins to do just about everything you need using only a handful of events, but debugging someone else’s plugins is a nightmare: there is no centralized location listing which events are being hooked into, and new events are often created and executed on the fly. Debugging WordPress plugins is like Alice’s trip down the rabbit hole: majorly trippy,and you don’t know if you’ll ever come out.

User management is another area where MODx dwarfs WordPress: Revolution can handle totally granular control of permissions, but it is admittedly overly complex for 90%+ of use cases. Evolution offers a much more sensible permissions scheme that covers most use cases.

MODx offers much more sensible implementations of custom code: like WordPress it uses event-driven plugins, but it also uses custom PHP snippets which can be placed anywhere on a page or in a template.

Another impressive feat is how MODx Revolution has abstracted the database into a separate coding layer — that means it is relatively easy to interface with custom database tables (or even to other database engines) using code that is completely database agnostic (support for SQLite and PostGREs is in the works). That’s some seriously geeky stuff that has kept me awake at night trying to comprehend how they accomplished that. MicroSoft has even worked directly with the MODx team because MODx’s architecture is flexible enough that it can run on an all MicroSoft stack (i.e. IIS and MS-SQL). I can’t think of a single other system that switch-hits as well as MODx.

Summary

If the site you are building is more of a web application that requires a lot of custom coding, go with MODx; the level of maturity in the underlying MODx framework is light years ahead of WordPress, but be advised that the coding in MODx is sometimes so advanced, it takes a very senior developer to understand what’s going on. If you decide to do a more serious application-type-project in WordPress, be sure to allocate extra time to augment or rewrite the core code. If you’re doing basic extensions or variations of a simple site/blog, then WordPress plugins can do that pretty well, so don’t overcomplicate things.

Dashboard

WordPress offers a clean manager dashboard for its administrators which relies on the jQuery JavaScript library to provide AJAX functionality and smooth user experience. It’s pretty easy to find your way around.

WordPress Manager dashboard
WordPress Manager dashboard

MODx underwent a huge change in its manager dashboard between Evolution and Revolution, and the Revolution dashboard is overwhelming for many. Evolution’s dashboard is cleaner and snappier.

MODx Evolution Dashboard
MODx Evolution Dashboard

MODx Revolution’s manager dashboard is still being optimized. It’s based on ExtJS. For those of you not familiar with ExtJS, it was based on YUI (the Yahoo User Interface library), and it offers some fatastically powerful features for building interfaces for web applications. My only complaint with it is that it’s heavy: the MODx Revo dashboard can take a long time to load, and sometimes clicking on buttons and links feels unresponsive.

MODx Revo dashboard
MODx Revo dashboard

Summary

Do not make your decision about which system to use based on the dashboard alone — that’s like marrying a girl for how big her tits are. I know some clients who have loved and hated the dashboards in both systems. Again, MODx offers more flexibility if you want to change the dashboard behavior. The big difference here is simple: WordPress gives you a super clean view of your posts based on time whereas MODx gives you a hierarchical view of your posts.

Blog

Everybody wants a blog, just like everybody wants a shiny new car. Authoring blogs has been a core competency of WordPress, and they get massive props for making them very simple to setup: out of the box, you can get a blog up and running with integrated tags and categories and comments within minutes. It’s really what WordPress is all about: blogging. WordPress even has some nice security features in place with its Akismet spam filter.

Contrary to some of the on-line murmurings out there, both versions of MODx can run blogs, but until MODX 2.2, the process to set them up was painfully laborious in comparison. The Articles extra for MODX gives you a quick and easy blog — it can even import your posts from WordPress, so the gap between the two systems is closing quickly. The only thing it doesn’t do as well as WordPress right out of the box is its taxonomies (tags and categories): you still have to do some configuration to get those configured how you want them, but as the docs say:

“MODx Revolution is not blogging software, but rather a full-blown Content Application Platform, it doesn’t come pre-packaged with a cookie-cutter blogging solution.” 

Summary

If your priority is to get a blog up and running as quickly as possible, and you have few requirements for supporting any other content, then WordPress is the way to go. Starting with MODX 2.2, however, you can use its “Articles” extra, which gives you simple blogging functionality, with many of the features available to WordPress.

Custom Content (CMS functionality)

If blogging is where WordPress shines, then CMS functionality is where MODx clearly has the upper hand. WordPress does support custom fields for its posts and pages, and in version 3.x, they support additional “post types”, so finally WordPress is getting some traction as a CMS, but it’s still a bit of a toy in comparison to MODx.

One of the biggest problems with WordPress as a CMS is its lack of support for sensible custom fields: for each post or page, you have to manually add the same custom fields over and over again, and by default, the custom fields are always simple text fields. I have attempted to rectify this in my Custom Content Type Manager plugin, and my plugin does a lot to give WordPress CMS capabilities, but it still represents a series of awkward workarounds that stretches the WordPress core nearly to its breaking point.

One related area here is how MODx can manage and serve static files via what MODx calls “Static Resources”. This is a great way to enforce permissions on viewing, streaming, or downloading static files (e.g. PDFs or Flash movies). WordPress just flat out can’t do that.

Although MODx offers greater flexibility, WordPress’ integration is a bit cleaner for the manager user (it’s a holy pain in the ass for the developer, but if you download my plugin you should avoid this unpleasantness). When WordPress registers a new “post type”, you get a nice menu icon in your dashboard and it’s really clear to the manager that he/she is adding a new post, page, or movie (etc). For example, if you want to add a movie post, you’d click on “Add Movie”. It’s really quite logical. In MODx, this same type of distinction occurs at the template level. Architecturally, this makes sense, but it’s confusing for the manager user, because it may not be at all clear that they need to add a “normal” page (i.e. resource), and then choose to use the “movie” template. I’m planning a MODx plugin to help rectify this UI “wart”.

A custom post type in WordPress
A custom post type in WordPress

Summary

If you have to display multiple types of content on your site (e.g. an eCommerce site), then MODx offers far greater flexibility, but it does take longer to configure. If your CMS requirements are simple and you don’t need to worry too much about customizations, then WordPress can do that very well and very quickly.

SEO

SEO is the an cyclical buzz, and at the moment, a lot of SEO guys are hailing WordPress as the holy grail of search-word wad-shooting. To be blunt, I think SEO is largely an over-hyped crock of crap. If you build a well-structured site with good content, your pages will show up in search results: if there is a site out there with awesome content that is not showing up in relevant search results, I have yet to see it. Search engine optimization is often a pseudo-science practiced by get-rich-quick marketeers who are convinced that they can turn lead into gold by over-hyping a site with various gimmicks. 90% or more of SEO should have to do with creating good content, and perhaps the last 10% of your efforts should go into polishing your site. It can be used to improve search results, but it tends to fail when you try to make search results come out of thin air. Too often I have seen companies do this the wrong way around: they spend 90% of their time publicizing a site that is a vapid cesspool instead of spending their time making a site that’s worth visiting. At best, SEO techniques are constantly changing as Google updates and refines their indexing algorithms. If you optimize your site today and Google farts tomorrow, all of your work may be for naught. Do your due dilligence, but it’s just not worth spending inordinate amounts of time tring to beat Google at their own game.

Rants aside, both systems offer ample ways to do search engine optimization. Assuming that you have good content, the rest of the process boils down to having well structured HTML (which relies on a solid templating system), and the ability to effectively index your pages. WordPress offers built-in taxonomies (categories and tags) for flagging your posts, and MODx can be set up to do this rather easily by using an Auto-Tag custom field (a.k.a. a MODx “Template Variable”).

MODx offers a much more flexible system for generating URLs (basically you can use any URL you want for any page). WordPress does offer flexibility here, except for its special pages (e.g. category listings or author pages).

Summary

Comparing SEO features between MODx and WordPress is a moot point: both systems allow you to adequately structure your content and your site.

Security

No system is 100% secure. MODx has had relatively few serious exploits; WordPress has had many, no doubt due in part to its popularity. For what it’s worth, I have had WordPress and MODx Evolution sites hacked, but not yet a Revolution site. It’s hard to quantify how secure an application is… I’d love to see the detailed forensic results of a penetration test against default installations of both CMS’s. In general though, the WordPress architecture is primitive and more ripe for being hacked: it’s more difficult to lock down spaghetti code. WordPress also offers many more plugins, and the plugin authors tend to be less experienced, so their code is more likely to have security holes.

There are many fingerprinting utilities out there that will attempt to locate known weaknesses in plugins, and WordPress is more easily fingerprinted; MODx Revo allows you to change default locations for the MODx manager or to even remove it from public view altogether. There are some discussions in the MODx Forums about how to harden MODx, but I haven’t yet seen a detailed how-to on how to eliminate the most common attack vectors. There are also good posts out there for hardening WordPress.

I reported a nasty vulnerability in phpThumb that affected MODx and numerous other CMS’s (phpThumb is a popular image manipulation library), but the MODx Revo architecture prevented the exploit from succeeding on Revo (good job to Shaun and Jason for architecting the connectors in the way they did).

Summary

I feel that MODx Revolution is probably more secure, but there are no guarantees when it comes to security. No system is bulletproof, so you best have redundant backups on hand and follow the recommendations of Basic Web Security no matter which system you’re on.

Support

This is another area that is pretty black and white in my opinion: WordPress support sucks. Although WordPress is more popular if you look at the numbers, you wouldn’t know it if you post questions in the WordPress Forums. I have rarely gotten any useful answers (if I got answers at all): anything beyond simple inquiries tend to go unanswered, leaving me alone in the dark reverse-engineering damn near everything.

My other gripe with WordPres is their weird distinction between WordPress.com and WordPress.org. You can host your blog at WordPress.com, and then you get more support, but it is effectively software as service: you can’t upload plugins and you can’t modify code, so the interface suddenly becomes a bit like BlogSpot.

By contrast, the MODx Forums are full of helpful people. It’s a great place to be: it’s not uncommon to get responses from the core team on almost any level of inquiry, from trivial to cerebral meltdowns. There are some superstar participants, such as Susan Ottwell and Bob Ray, who have both contributed immensely helpful posts and tutorials on how to use MODx. MODx also offers commercial support; it’s still in its infancy, but for a yearly fee, you can get access to a kind of “MODx hotline” and get help resolving MODx issues on your sites.

Documentation

In the same breath as support, I must mention documentation. In general, documentation for both systems is lacking, in some areas painfully so. While using WordPress, I have often I have searched for hours trying to find a way to do a certain thing, only to end up grepping through the code base and deciphering the raw code myself. Frequently the official documentation has holes or in some cases, it’s just plain wrong. The best resources for some advanced WordPress features are blogs written other developers.

MODx’s documentation is also frustratingly AWOL on a number of topics, but least the MODx code base is integrated with a standard documentation publishing system so if needed you can see for yourself how the functions are structured without having to grep through the code base. The vibrant MODx forums fill in a lot of the holes in the documentation, and that’s a huge benefit for any open-source project.

Summary

If you need support for your site, especially guaranteed support, then only MODx offers a paid support service; WordPress doesn’t offer a paid support option.

Scalability

WordPress can handle a huge number of posts, but it does get bogged down with a large number of pages, and there are lots of whisperings about this (e.g. here). I suspect it has to do with WordPress’ convoluted templating system (see above), which makes me wonder what the limits are on custom post types.

MODx Evolution suffered from a limit of approximately 5000 resources (in MODx, pages and posts are types of resources), but that limit has been corrected in an upcoming release thanks largely to the efforts of Charlie over at ProWebscape.com.

MODx Revolution has no such limits: it offers a great built-in caching system that allows it to serve pages very quickly. It has been benchmarked as twice as fast as Expression Engine (see this blog post).

More importantly, MODx Revolution was built with scaling in mind: it stores session data in the database, so it is easily deployed on load-balanced servers. This is hugely important if you are building a site that might one day get massive amounts of traffic; WordPress can be deployed like this, but such usage is not generally anticipated. I don’t know of many large commercial sites running WordPress (in fact, I only found one: 9rules.com).

Summary

MODx is by far the more mature option here if you anticipate building a large site.

Conclusion

I do like both systems, and I use them both daily. WordPress has a much lighter footprint and is easier to use for a large number of use-cases: if you just need to get a site out the door fast, then WordPress is really hard to beat. WordPress is plug-and-play for just about everything and that saves you hours of setup time, so it can be the right solution for a majority of sites. But the more customizations you require (particularly in scripts or in layouts), then the more appealing MODx becomes: WordPress has thousands of plugins available, but if those aren’t meeting your needs, I’ve found certain types of customizations to be extremely difficult in WordPress whereas most often, MODx handles them with ease. Doing things like building web applications with strict formatting requirements is much easier in MODx because it’s built more as a launchpad for customizations: it’s really more of a content management framework (CMF). MODx Evolution is the best system I’ve used for building small to medium sized informational/brochure sites, WordPress rules as the blogging king, and I’ve been very impressed with how easily I can build web applications using MODx Revolution. There isn’t one tool that’s right for every job; the more projects you complete, the better idea you’ll have as to which system will accomplish your requirements more easily, and hopefully this article helps you spot more of what each system is good at.

Writing Custom PHP Snippets for MODx (part VII)

This article and tutorial video takes on how to add custom PHP scripts (known as Snippets) to the MODx content management system. This covers MODx Evolution (version 1.0 and before), but many of these methods and principles are applicable to MODx Revolution (version 2.0) and PHP coding in general.

Please enable Javascript and Flash to view this Blip.tv video.
Watch Video @ Blip.Tv

Adding a Snippet

MODx newcomers are sometimes confused as to where to upload the PHP files… YOU DON’T UPLOAD IT. You paste it into a database record. You can reference files on the file system, but you don’t have to.

1. To add a Snippet from the MODx (v1) manager go to Elements –> Manage Elements –> Snippets then paste in your PHP code.
2. Be sure to give it a unique name (I recommend avoiding spaces in the name)
3. Give it a category: this will make your Snippet easier to find in the manager.

Recommended Components of a PHP Snippet

This applies to ANY code you write, but for the record, please include the following documentation as comments in your Snippet:
1. SUMMARY: a sentence describing what the Snippet does.
2. INPUT: list any input variables the Snippet can accept. It’s good to note the data type (e.g. integer/string), whether or not they are required, or whether or not they have a default value.
3. OUTPUT: list any special output created by the Snippet. Usually it’ll just be HTML, but it’s good to note any external actions (e.g. whether it updates a database row).
4. EXAMPLE: give an example of how the Snippet should be called.

Sample Comment Block


/*---------------------------------------------------------
SUMMARY: Formats list of cartoon characters using referenced chunk
INPUT:
$chunk_name = string; Name of Chunk to be used for formatting output.
OUTPUT:
HTML or it logs an error.
EXAMPLE:
[!ComicExample? &chunk_name=`myChunk`!]
----------------------------------------------------------*/
?>

Coding Suggestions and Rules of Thumb

1. Develop your Interface before you code: that bit about adding comments isn’t just for other users, it can help you determine how you want to be able to interact with your code. Coding to an interface is good way of establishing goals and structure before you even start writing the actual code.
2. Initialize your variables: This cuts down on the possibility of security exploits, bugs, and it makes your code easier to read, e.g.:
$output = '';
$garfield_characters_array = array();

3. Sanitize your input: if you are getting any user entered data (e.g. anything out of the $_POST or $_GET array), sanitize the data using regular expressions and if/then statements. Make SURE you have eliminated any possibility that the data is something other than what your program expects.
4. Test as you Go: PHP doesn’t have a built-in debugger, so don’t go too long without checking to see if your code still “compiles” (technically, you should check to see if it has a valid syntax and if it executes). Checking often will help you track down where you made a mistake.
5. Use Good Variable and Function Names: be descriptive. Don’t become a member of the hated “ASCII Preservation Society”. Besides, if you use unique variable names, it becomes MUCH easier to search for instances of that variable, and you’re less likely to have variable collisions.
6. Group your Code into Units: In a word, use functions that fit on the page. If you can SEE it, you’re less likely to UNDERSTAND IT. Chapters of uninterrupted code are hard to debug and test.
7. Reuse your Code: if there are cases in your code where you’re copying and pasting identical or NEARLY identical parts, then it’s time to relegate that code to its own separate function.
8. Log your Errors: if something goes wrong, let your users know about it. It’s a wonderful thing to use the MODx logging function.
9. DO NOT MIX HTML and PHP! There are a few cases where where this is acceptable, but it is good architectural design to separate your view (i.e. your HTML) from your logic. If you have to edit your PHP code to change div tags or CSS classes, then you probably did something wrong. Instead, use MODx Chunks to format Snippet output; your code will be MUCH cleaner as a result and MUCH easier to maintain.

Including Files from the File System

If you write anything more than simple Snippets, you’ll want to put your PHP file(s) on the file system and reference them from the Snippet stored in the MODx database. You can do this by including a standard include or require statement, e.g.

include($modx->config['base_path'].'assets/snippets/mysnippet/include_me.php');

The standard MODx location would be in your own folder within the /assets/snippets directory.

Things to Remember When Including Files and Using Functions

1. Variable Scope: the $modx super-object and the methods that go along with it will not remain in scope within a funciton; use the global to ensure that the globally scoped $modx variable instance is used inside the function. Compare the two instances of the same API call:
// INSIDE a function
function inside_a_function($chunk_name,$garfield_characters_array)
{
global $modx;
$output = $modx->parseChunk($chunk_name, $garfield_characters_array, '[+', '+]');
return $output;
}

// Or OUTSIDE a function
$output = $modx->parseChunk($chunk_name, $garfield_characters_array, '[+', '+]');

2. You can’t return a value directly from an included file: because MODx treats Snippets as functions, it’s considered good form to always return a value, e.g. “return $output;” or “return TRUE;” but this MUST be returned from the original Snippet in the database; if you return output from the included file, you’ll have to return it again from the original database Snippet code. See the video for this quirk in action.
3. Take advantage of the File System: if you are developing stand-alone PHP files, you can use the bash terminal (on Linux or OS X machines) to test the PHP syntax. Simply navigate to the directory where your file is and type:
php -l name_of_your_file.php

Forgot your MODx Password? You can reset it…

I have *cough* never forgotten my password to anything because I followed Brian’s excellent advice about storing passwords, but just in case some of you have, I thought I’d help you out.

If you have access to your MySQL database, you can still log into the MODx manager.
If you have access to your MySQL database, you can still log into the MODx manager.

First off, if you are locked out of your MODx manager, you can use the standard link on the manager page to email you your password, but I’m outlining how to do this in the event that you either didn’t enter a valid email address or you aren’t receiving your emails somehow. There are two things I’m going to outline:

  1. Resetting your MODx manager password
  2. Adding a new MODx manager user

WARNING: Both options require that you have read/write access to the MySQL database where the MODx information is installed. PROCEED WITH CAUTION… THIS REQUIRES DATABASE EDITS.

Option 1 is nicely outlined by this article at Lucid Green: How to get into MODx when your blocked or lost your password. The article is a bit dated (2006), but it’s still valid… to summarize, do the following:

Resetting Your MODx Manager Password

We’re going to do two things here: change your password, and clear any blocks on your manager user.

  1. Login to your site’s database (e.g. using phpMyAdmin).
  2. Find the table modx_manager_users –in phpMyAdmin, find the table in the list on the left.
    phpMyAdmin lists all tables on the left-hand side
    phpMyAdmin lists all tables on the left-hand side

    NOTE: the modx_ is the default table prefix… your installation may use a different prefix, or it may use no prefix. If you honestly can’t locate the table, you may have to resort to the following query to find the table: SHOW TABLES LIKE '%manager_users';

    Can't find the table? SHOW TABLES LIKE ...
    Can't find the table? SHOW TABLES WHERE ...

    Type that at the MySQL prompt and any tables with a name ending in “manager_users” will be shown.

  3. Select your user from the list — in phpMyAdmin you can click the “Browse” tab to browse the rows in each table. Choose to CHANGE or EDIT the row.
    Edit your user
    Edit your user
  4. Select the MD5 function to operate on the password column. In phpMyAdmin, when you edit a record, you can use functions to operate on each column. Once you’ve selected to use the MD5 function, you can type your new password normally.
    Make sure you use the MD5 function!
    Make sure you use the MD5 function!

    If you are doing this via the MySQL command line, the actual query we execute looks something like this:
    UPDATE `your_db`.`modx_manager_users` SET `password` = MD5( 'changeme' ) WHERE `modx_manager_users`.`id` =1 LIMIT 1 ;

    NOTE: if you execute this query at the command line, you must type apostrophes to delineate your password (they will not be included as part of the password). If you are doing this via phpMyAdmin, do NOT type the apostrophes.

  5. Save the changes to the row.
  6. Please note the id for the row that you just edited… you may need it.
  7. Go to the modx_user_attributes table and find your manager user and edit this row (here’s where it’s handy to have that id from the above steps.
  8. Change only the following items then save the row:
    * Set “blockeduntil” to zero (0).
    * Set failedlogincount to zero (0).
    Remove blocks on your user
    Remove blocks on your user

    On the MySQL command line, your query looks something like this:
    UPDATE `your_db`.`modx_user_attributes` SET `blockeduntil` = '0',`failedlogincount` = '0' WHERE `modx_user_attributes`.`id` =1 LIMIT 1 ;
  9. You should now be done… head over to yourdomain.com/manager and login using your new password.

Adding a New MODx Manager User

This is a bit more devious, but the commands aren’t much different than the above, except that we are INSERTING rows into 2 tables instead of UPDATING them. There are many times I’ve needed to “let myself in” using this technique…

  1. As above, login to your site’s database (e.g. using phpMyAdmin).
  2. As above, find the table modx_manager_users –in phpMyAdmin, find the table in the list on the left. (If you have trouble finding the table, see the tip in step #2 above).
  3. Instead of updating an existing record, we are going to create one — in phpMyAdmin, click the “INSERT” tab. Be sure that you do the following:
    * type a valid username (usually, this is one word, lowercase)
    * type a valid password (use the MD5 function!)
    * Leave the id field blank (it will auto-increment).
    * Select “MD5″ as the function for the password field (don’t forget!)
    * Leave the “Ignore” box checked — phpMyAdmin allows you to insert a couple rows at once, but we only need to insert one.
    Create a new User
    Create a new User

    Then click Go to insert the new record.

    The actual MySQL query used here is something like this:
    INSERT INTO `your_db`.`modx_manager_users` (
    `username` ,
    `password`
    )
    VALUES (
    'everett', MD5( 'changeme' )
    );

  4. Remember the id of the newly inserted user! You’ll need it — phpMyAdmin shows it after the row was inserted. If you misplaced it, you can simply browse the table and find your user — remember the id!
    The new User's ID is shown here
    The new User's ID is shown here
  5. Go to the modx_user_attributes table and insert a new row:
    Add the following values:
    * id LEAVE BLANK. It will auto-increment.
    * internalKey should also be equal to the your user id from step 4.
    * role = 1 (for manager users)

    The actual query looks something like this:
    INSERT INTO `your_db`.`modx_user_attributes` (`internalKey` ,
    `role`
    )
    VALUES (
    '9', '1'
    );

  6. That’s it. You should now be able to use that username and password to login into your MODx manager at www.yourdomain.com/manager

Enabling SEO Friendly URLs in MODx (part VI in the series)

Apache .htaccess Rewrites are Powerful
Apache .htaccess Rewrites are Powerful

Many content management systems rely on URL parameters like ?page=3 to determine which page is displayed to the user. MODx (like many other CMS’s) can use Apache’s .htaccess file to rewrite URLs so they are easier to read, e.g. www.mydomain.com/modx/tutorial, and this usually results in higher SEO scores. This article and its video walk you through how to accomplish this for MODx running on an Apache web server. Windows servers have something similar, they just charge more for it (haha).

Here’s the video. I was going to re-do this in high-def, but this was one of those lightning-strike rants that I was on… I just know it wouldn’t be as good if I attempted to remake it.
YouTube Preview Image

* I mispronounced MODx in the video (sorry). It should be “mod” as is “modular”.

The Quickie Text Version of the Video

  1. Make sure MODx is installed and your site works.
  2. Go to the root of your site, verify that you have an .htaccess file (MODx often includes a dummy file named “ht.access” which needs to be renamed before it is parsed). Be sure to keep a backup copy of the original!
  3. Edit the .htaccess file and type some junk at the very top of the file. For example, type in “asdpfasdfj” at the top of the file, then save it. Now try to visit any page on your site. You should get an server error, and this is GOOD! This means that the .htaccess file is being parsed, so go back and delete that junk from the file. If you don’t get an error, it means that the .htaccess file is NOT being parsed, and you may need to contact your ISP to see how to enable it. You can’t get friendly URLs working without this!
  4. Once you’ve confirmed that your .htaccess file is being parsed, you can make the appropriate edits (see below). The dummy file included with your MODx install is very well annotated. I’ve listed the most important bits below (please change yourdomain to the appropriate domain). Note that in some of the lines, you must precede periods with a backslash (i.e. you must escape them). Any line starting with “#” is a comment.
    # Vital components of your .htaccess file
    RewriteEngine On
    RewriteBase /

    # Force “www.yourdomain.com” instead of just “yourdomain.com”
    RewriteCond %{HTTP_HOST} .
    RewriteCond %{HTTP_HOST} !^www\.yourdomain\.com [NC]
    RewriteRule (.*) http://www.yourdomain.com/$1 [R=301,L]

    # The Friendly URLs part
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]

  5. Make sure your site is still working… you can still use the same un-friendly URLs after making these edits; you just want to make sure you didn’t misspell something in your .htaccess file and cause it to parse incorrectly.
  6. Login to the MODx manager (www.yoursite.com/manager) and go to Tools→Configuration→Friendly URLs and change the following settings:
    * Use friendly URLs: YES
    * Use friendly aliases: YES
    * Use friendly alias path: YES

You should now be able to navigate to pages by using their alias!

More Information

Friendly URLs Guide — From the MODx Wiki.

Technical Details about .htaccess

What exactly is happening? Well, the .htaccess file can control a lot of server settings, and you can think of it almost like a style sheet: the server has global settings, but the .htaccess file provides a way to override some of those settings locally for a particular directory or site. It really merits its own article (stay tuned), but let’s look at the the friendly URLs part of the .htaccess file.

The core of this functionality is Apache’s mod_rewrite module. My snarky description is this: it lets the server lie to your address bar! Your browser window may SAY that you are visiting www.mydomain.com/modx/tutorial, but really, the page you are viewing (on a MODx site) is:
www.mydomain.com/index.php?q=modx/tutorial
Try this on your own MODx site! You should see the same page as you did when you visited the friendly URL.

Here’s what the .htaccess file is doing. The first RewriteCond is checking the file system for a file of the name you are requesting. In the example, it’d look for a file named “tutorial” in the “modx” directory. The “!-f” at the end of the line is basically saying “IF there isn’t a file of this name”… then the next line’s “!-d” says “OR there’s not a directory of this name”, THEN perform the rewrite defined by the RewriteRule.

Here you see a good example of a regular expression, and if you haven’t heard that term before, I can sum up quickly: if you’ve ever done a “search” or a “find and replace” in a document, you’ve utilized a simple type of regular expression. A regular expression searches for a pattern. The $1 is a common shorthand notation that back-references what exactly was found, in this case, it’s the argument that’s being passed to the server for the REQUEST_FILENAME, i.e. “modx/tutorial”. The contents of the $1 variable is then added onto “index.php?q=” and you end up with the REAL URL being:
www.mydomain.com/index.php?q=modx/tutorial

Tricky tricky! I skipped over a lot of details for this brief overview, but hopefully you can see some of the process here. This is how most CMS’s handle this sort of thing. The .htaccess parsing requires more overhead from Apache, but it offers a lot of flexibility in how you access your files, and for most sites, this is a very worthy tradeoff.

Creating Templates in MODx Part II (part V in the series)

Now that you are able to create basic MODx templates from watching the previous video, this video shows you how to extend their functionality even further with the inclusion of reusable chunks of code and dynamic PHP snippets.

Please enable Javascript and Flash to view this Blip.tv video.

Vocabulary

You only have to learn a couple new terms to understand what MODx is talking about — it’s not a steep learning curve, so jump in!

  1. Chunk — any bit of reusable text (usually HTML). Text used in a site’s footer is commonly placed into a chunk. MODx references chunks using double curly-braces: {{name_of_your_chunk}}, and they can be used almost anywhere, including page content and templates. Chunks can also contain Snippets!
  2. Snippet– this is a bit of PHP code (I remember Snippet by its double-P’s: sni-PhP-et). You can literally cut and paste almost any working PHP script into a MODx Snippet; once it has been created, you reference it using either double-square brackets or with a bracket and an exclamation point: [[Like_this]] or [!Like_this!], depending on whether you want it to always execute, or whether its output can be cached. See the MODx Wiki for more information.

Clarification

To clarify the process here, first you create a Chunk or a Snippet by logging into the MODx Manager and navigating to Resources→Manage Resources, then selecting the appropriate tab (for Snippet or for Chunk). You paste in the code you want to use, then save it. Back in your documents or templates, you can reference the Chunks and Snippets by name, flagging the names with either “{{ name }}” (for Chunks) or “[[ name ]]” (for Snippets). When MODx parses the document or template, the text in the Chunk will replace the tag, or in the case of a Snippet, the code will execute and its output will replace the tag.

Template Tips

  1. If you keep pasting the same bit of text into lots and lots of pages, consider adding that text into a Chunk. Also consider adding the reference to that chunk to your template.
  2. Set up a good working Snippet to auto-generate your menus. Wayfinder is a very flexible Snippet designed explicitly for this task, and it is included with MODx. Check the official site for up-to-date documentation; there are also lots of examples on the MODx Wiki
  3. Plan your site and its templates before trying to code them; then make sure you code them before adding them to MODx.
  4. If your site has too many templates, you probably are doing something inefficiently. Ask around: is there a better way to accomplish what you’re trying to do?
  5. When adding your templates and its associated chunks/snippets to MODx, take advantage of the “category” field. It offers a simple way to keep your components organized.

Other Tutorials: don’t just take our word for it

  1. Net tuts
  2. Bob’s Guides — Bob is very active in the MODx Forums, and he knows what he’s talking about.
  3. The Coding Pad

Download MODx Templates

You can also download MODx templates from a number of other sites! And since it’s so easy to integrate existing templates, you can download templates for virtually any platform and incorporate them into MODx.

Summary

After watching these two videos, I hope you can see how simple it is to get CMS functionality out of existing HTML/CSS using MODx. Again, the big thing I didn’t explicitly point out in the videos is that MODx stores its template code in its database: you can create and use a MODx template without uploading a single file to your webserver. Of course, if you want to reference CSS or Javascript files on your webserver, it’s accomplished in exactly the same way as you would do it on a static site: just make sure your paths to your resources are correct. I’ll cover how to write your own Snippets in another video. For now, just review the wiki page about MODx placeholders as you build your own templates. Please note, I did make one slip up in the video… Snippet values should usually include backticks, like this: [[MySnippet? &parameter1=`value`]].

Creating Templates in MODx Part I (part IV in the series)

I’m continuing my series of hi-res videos of the MODx content management system, this time I’m stepping through how you can easily take existing HTML and CSS layouts and adapt them for use with MODx. For my example, I take Eric Meyer’s “Complex Spiral” demo and within a few minutes, I have it adapted for use with my site.

It’s an exciting time to be writing about this platform: the first book about MODx was published by Packt Publishing, and we anticipate the release of their “2.0” version (dubbed “Revolution”) later this year.

Please enable Javascript and Flash to view this Blip.tv video.

I include the image below as a quick reference for the placeholder tags used by MODx. Refer to the wiki page for a more complete list.

MODx uses simple placeholders for templates
MODx uses simple placeholders for templates

Summary: Creating a Custom MODx Template

  1. Create a working HTML/CSS/Javascript web page. Make sure it works!
  2. Upload the template files to your web server (e.g. CSS, Javascript). Note that the actual template code will live in the MODx database, not on the file system, but you do upload the related assets to your webserver. The recommended location for assets is in a dedicated folder in /assets/templates — make sure that you update your image paths or Javascript paths so that a page at the root of the site can safely reference the assets contained in the /assets/templates/name_of_your_template folder.
    * In the video, I upload the HTML file too just as a final check to make sure it works in the new location.
  3. Replace appropriate areas of your HTML with MODx placeholders. Refer to the image above or to the wiki page so you know which placeholders are available.
  4. Login to the MODx Manager, create a new template in Resources→Manage Resources→Templates. Be sure to save it and give it a good name.
  5. Edit a page and choose to use the new template, and save the page! In other words, you need to tell your MODx documents to use your new template.
You upload the template code to the database, but it still can reference files on the webserver
You upload the template code to the database, but it still can reference files on the webserver

Clarifications

MODx handles templates differently than some CMS’s, and I didn’t point this out in the video. A MODx template lives in the MODx database. You cut and paste the HTML into the MODx manager Resources–>Manage Resources–>Templates. Even though your template code lives in the database, it can still reference files on the web server. For example, if you upload your CSS and Javascript files to /assets/templates/my_template/, then your HTML should use paths like href=”/assets/templates/my_template/style.css”.

Keep Watching…

Part two of this video shows how to add Chunks and Snippets to your template for more dynamic functionality.