1. Getting Started
      1. Basic Installation
      2. What is MODx
    2. Content Editing
      1. Editing Documents
      2. MODx Tags
        1. Document Variables
      3. Terminology
      4. The Manager
      5. Who Should Read This
    3. Designing
      1. Adding Chunks
      2. Adding MODx Tags
        1. Resource Fields
      3. Adding Snippets
      4. Document Caching
      5. Template Basics
    4. Administration
      1. Friendly URL Solutions
      2. Manager Users
        1. Manager Roles And Groups
        2. Reset your Password - Unblock your User
        3. Why Manager Users, Roles and Groups
      3. Moving Site
      4. Taking sites down for maintenance
      5. Upgrading
      6. Web Users
        1. Creating a Web User
        2. Web User Groups and Document Groups
        3. Why Web Users and Groups
    5. Developer's Guide
      1. API Reference
        1. DBAPI
          1. delete
          2. escape
          3. getInsertId
          4. query
          5. select
          6. update
        2. Document Object
        3. DocumentParser Object
          1. addEventListener
          2. changeWebUserPassword
          3. documentContent
          4. documentGenerated
          5. documentIdentifier
          6. documentListing
          7. documentMethod
          8. documentObject
          9. getAllChildren
          10. getCachePath
          11. getChildIds
          12. getDocumentChildren
          13. getDocumentChildrenTVarOutput
          14. getDocumentChildrenTVars
          15. getLoginUserID
          16. getLoginUserName
          17. getLoginUserType
          18. getManagerPath
          19. getParent
          20. getParentIds
          21. getUserData
          22. hasPermission
          23. isBackend
          24. isFrontend
          25. logEvent
          26. maxParserPasses
          27. minParserPasses
          28. regClientCSS
          29. runSnippet
          30. table_prefix
          31. tstart
          32. webAlert
      2. Chunks
      3. Modules
        1. How to create and run a module from within the Content Manager
        2. Managing module dependencies
        3. Setting up configuration parameters
        4. Writing the module code
      4. Plugins
      5. Snippets
      6. Template Variables
        1. (at) Binding
          1. (at)CHUNK
          2. (at)DIRECTORY
          3. (at)DOCUMENT
          4. (at)EVAL
          5. (at)FILE
          6. (at)INHERIT
          7. (at)SELECT
          8. What are (at) Bindings
        2. Creating a Template Variable
        3. What are Template Variables
        4. Widgets
          1. Misc. Widget
          2. DataGrid Widget
          3. Floater Widget
          4. Hyperlink Widget
          5. Marquee Widget
          6. RichTextBox Widget
          7. Ticker Widget
          8. Viewport Widget
          9. What are Widgets

Friendly URL Solutions

Last edited by JP DeVries on Aug 9, 2013.

Welcome to the MODX Documentation. It is an ongoing effort of the MODX community. If you would like to participate or if you notice any errors or missing content, please let us know.

Apache mod_rewrite .htaccess Solutions for MODx

MODx supports Friendly URLs via this .htaccess file. You must serve web pages via Apache with mod_rewrite to use this functionality, and you must change the file name from ht.access to .htaccess. Additional tweaks and environment specific additions follow the default template below:
# For full documentation and other suggested options, please see
# http://svn.modxcms.com/docs/display/MODx096/Friendly+URL+Solutions
# including for unexpected logouts in multi-server/cloud environments

Options +FollowSymlinks
RewriteEngine On
RewriteBase /

# Fix Apache internal dummy connections from breaking [(site_url)] cache
RewriteCond %{HTTP_USER_AGENT} ^.*internal\ dummy\ connection.*$ [NC]
RewriteRule .* - [F,L]

# Rewrite domain.com -> www.domain.com -- used with SEO Strict URLs plugin
#RewriteCond %{HTTP_HOST} .
#RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]
#RewriteRule (.*) http://www.example.com/$1 [R=301,L]

# Exclude /assets and /manager directories from rewrite rules
RewriteRule ^(manager|assets) - [L]

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

# Reduce server overhead by enabling output compression if supported.
#php_flag zlib.output_compression On
#php_value zlib.output_compression_level 5
If Windows IIS serves your pages, you're not left out of the Friendly URLs party, but optimal solutions do require a commercial IIS add on. For more information, see the SEO Friendly URLs with IIS page in the MODx forums.

For other web servers such as Zeus or lighttpd, see our General Requirements page under supported web servers.

Common Edits to the Default .htacces File

Make sure RewriteBase points to the directory where you installed MODx. E.g., "/modx" if your installation is in a "modx" subdirectory:

RewriteBase /modx

Note in the last block of directives the gzip compression was left commented out since this can potentially cause issues in some environemnts. For a faster webserver experience, ucomment the last two lines as follows:

# Reduce server overhead by enabling output compression if supported.
php_flag zlib.output_compression On
php_value zlib.output_compression_level 5

You may also want to make your URLs non-case-sensitive by adding a NC directive to the directive in the "For Friendly URLs" part:

RewriteRule ^(.*)$ index.php?q=$1 [L,QSA,NC]

If you prefer your website to always add the "www." part to always show "www.example.com" URLs, then the section below should be changed as follows:

RewriteCond %{HTTP_HOST} .
RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]
RewriteRule (.*) http://www.example.com/$1 [R=301,L]

If you're working off of virtual domains and have a preview for development or while waiting for DNS updates to occur such as accessing your site through http://10.0.0.1/~myacct, the rewrite rule should be written as follows. Don't forget to change it back when you go live.

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ /~myacct/index.php?q=$1 [L,QSA]

Manager Protection

If you would like to limit the manager to being accessed by only a specific IP address, but need access to some things on the public site like the captcha, use the following. Make sure this goes inside the Manager directory:

# Allow manager access to specific IPs only

Options +FollowSymlinks
RewriteEngine On

# Deny by IP. The IP address(es) listed will get through.
RewriteCond %{REMOTE_ADDR} !^(192\.168\.0\.128)$
RewriteCond %{REQUEST_FILENAME} !/includes/veriword\.php$
RewriteRule ^(.*)$ ../index.php?q=$1 [L,QSA]
The first line ("Options +FollowSymlinks") may need to be commented out in some situations where a similar line is present in the site install root to prevent server errors.

Session Handling

If you are deployed in an environment that has problems with aggressive garbage collection, as evidenced by unexpected and frequent logouts from the manager, then you can adjust the location of the sessions to remove them from the default and shared global tmp/session location:

If you add this to your .htaccess file, make sure to also add it to the .htaccess file located in the /manager directory.
php_value session.save_path /path/to/your/web/content/sessions/
php_value session.gc_maxlifetime 28800

CSS or JS files as MODx documents

By default, MODx Evolution's htaccess template file excludes the /assets and /manager directories from rewrite rules. If you are using a MODx document as a CSS file, you'll need to adjust the one line to allow rewrites in the /assets directory if that's where you store your CSS file.

RewriteRule ^(manager|assets) - [L]

Would become

RewriteRule ^manager - [L]
Tip
If you still wish to maintain some subdirectories in the exclusions, you could disable /assets/images and /assets/snippets for example with the following rule:
RewriteRule ^(manager|assets/images|assets/snippets) - [L]

Timezone

Some servers do not have their timezone settings set, which can cause issues. You can try the following setting with full details of timezone definitions available at http://php.net/manual/en/timezones.php

php_value date.timezone Europe/Moscow

or

SetEnv TZ America/Chicago

Default Character Sets

Really, you should fix your code and database to handle character sets properly. But, if you insist, please see http://httpd.apache.org/docs/2.0/mod/core.html#adddefaultcharset and you might consider using:

AddDefaultCharset utf-8

Register Globals

Warning
If your server has register_globals enabled (and it's not possible to disable), run as fast as possible to a new webhost. Seriously.

Your site is almost 99.99999% absolutely destined to be hacked at some point by script kiddies with register_globals on, ESPECIALLY in shared hosting environemnts. This is an inherrent security risk, equivalent to letting a baby play with a loaded gun and hoping they don't pull the trigger. If you're paying under $15/month, you're on a shared host. For more information: http://php.net/register_globals

To verify that this option has been set to OFF, open the Manager and choose Reports -> System Info and then click the phpinfo() link. Do a Find on Page for "register_globals". The Local Value should be OFF. If the Master Value is OFF then you do not need this directive here.

IF REGISTER_GLOBALS DIRECTIVE CAUSES 500 INTERNAL SERVER ERRORS:

Your server does not allow PHP directives to be set via .htaccess. In that case you must make this change in your php.ini file instead. If you are using a commercial web host, contact the administrators for assistance in doing this. Not all servers allow local php.ini files, and they should include all PHP configurations (not just this one), or you will effectively reset everything to PHP defaults. Consult www.php.net for more detailed information about setting PHP directives.

# Turn off register_globals because I have a lazy webhost that doesn't care about security
php_flag register_globals Off

Solving Internet Explorer Woes

If htc files are being used on your site, some servers may serve this with the incorrect mime type. The following can be added to resolve this. The following is critical for MS Windows XP SP2 surfers:

# Fix .htc mime type for Internet Explorer
AddType text/x-component .htc

The following directives stop screen flicker in IE on CSS rollovers. When they're in place, you may have to do a force-refresh in order to see changes in your designs.

# Fix screen flicker for images in Internet Explorer
ExpiresActive On
ExpiresByType image/gif A2592000
ExpiresByType image/jpeg A2592000
ExpiresByType image/png A2592000
BrowserMatch "MSIE" brokenvary=1
BrowserMatch "Mozilla/4.[0-9]{2}" brokenvary=1
BrowserMatch "Opera" !brokenvary
SetEnvIf brokenvary 1 force-no-vary
.htaccess directives provide directory-level configuration overrides when you cannot access the main Apache httpd.conf file. The main configuration file should be used for server directives whenever possible because .htaccess rules result in increased page processing times.