Friendly URLs Guide
From MODx Wiki
Contents |
Background
By default, MODx uses a URL structure like this:
www.mysite.com/index.php?id=123
Friendly URLs (a.k.a. Human-readable URLS or Search-Engine-Friendly URLs) can take one of the following forms:
Change the Prefix: www.mysite.com/index.php?page=123 Use the page alias instead of the numerical id: www.mysite.com/index.php?page=my-blog-post-about-modx
Use the alias with a suffix: www.mysite.com/my-blog-post-about-modx.html
Which format you can use depends on how your server is configured. Search engines examine how urls are formed, that's why friendly urls are sometimes also referred as search engine friendly urls or SEO urls. You can view Google's guidelines for examples and guidelines (note that all 3 examples are more SEO friendly than the default format, but Google's guidelines do change). The following sections show how you can set up different levels of friendly urls in MODx.
Friendly URLs via Changing the Prefix
If you read the above (Google's guidelines for webmasters), you probably noticed that it said: "Don't use "&id=" as a parameter in your URLs, as we don't include these pages in our index."
Currently, the default MODx installation uses index.php?id=123 to build urls, which Google says not to do... however, there is a way to fix this! Here are the steps:
- Log in to MODx Manager.
- In the manager, go to "Tools" -> "Configuration" (or "Administration" -> "System Configuration" pre 0.9.5)
- In the System configuration, choose "Friendly URL Settings" tab.
- Set "Use friendly URLs" to "Yes".
- Change "Prefix for friendly URLs" to "index.php?q=" (or index.php?page= etc.)
- Select "Save" to save the MODx configuration settings.
- Done! Visit your site and look at the urls. The "id" should be replaced with "q" or "page" or what ever you used in the "Prefix for friendly URLs" field. Your urls are now google friendly.
...or so would you think, wouldn't you? If you look closely Google's webmaster guidelines also says: "If you decide to use dynamic pages (i.e., the URL contains a "?" character), be aware that not every search engine spider crawls dynamic pages as well as static pages. It helps to keep the parameters short and the number of them few." So if you want to be sure that all of your pages are indexed fully, look at the section Friendly URLs With Mod Rewrite.
With recent changes to the way Google, Yahoo and MSN's search engines work, dynamic URL's (ie. index.php?id=3) will get indexed just fine. The article references a few, obscure search engines. As far as the Big 3 goes, you're fine either way.
Friendly URLs without mod_rewrite (using the page alias)
Ok, by doing what is described in SEO (Google) Friendly url's section, we get urls that look something like www.mysite.com/index.php?q=123. Now, how to get that to a url like www.mysite.com/index.php?q=my-blog-post-about-modx you say? Well we are not far. Here's the steps how to set that up.
- Do the steps that are described in SEO (Google) Friendly url's
- Go to the "Friendly URL Settings" tab.
- Set "Use friendly aliases" to "Yes".
- Select "Save" to save the MODx configuration settings.
- Edit some document and set something to the "Document's alias" field.
- Done! Visit your site and look at the url to that document. It should have changed from index.php?q=123 to index.php?q=your-alias.
Friendly urls with mod_rewrite (dropping the ?query string and using ONLY the alias)
This is arguably the most powerful way to change your URLs. When you're using this method, your MODx pages will look and feel just like they were uploaded into a directory on a web server. This is good news for bookmarking and SEO.
To have the fully qualified friendly urls you have to have mod_rewrite support on your server. (The technology here revolves around regular expressions, which is a huge topic in and of itself). Here are the steps how to get this set up:
- You will find a ht.access named file at the root of the MODx folder. That file contains the url rewrite settings. You will also find another one in /manager folder.
- Rename both of these files to .htaccess (Note that on windows you have to do this from the command line with ren [ht.access directory]\ht.access .htaccess)
- See the link below for a tutorial on these files, but a quick explanation is they allow cascading control of how Apache handles requests.
- Open the file that is in MODx root folder for editing
- If you use pre 0.9.5 MODx add the following setting to the .htaccess file:
- RewriteBase / if MODx is installed to the site root
- RewriteBase /folder if MODx is installed in to a subfolder called "folder"
- If you have installed MODx in to a subfolder you may also need to do the following change:
- change RewriteRule ^(.*)$ index.php?q=$1 [L,QSA] into RewriteRule ^(.*)$ /folder/index.php?q=$1 [L,QSA]
- If you use pre 0.9.5 you might need to comment the the following lines (if your webserver does not support them) by placing # before the line, or you can remove the whole line
- php_flag zlib.output_compression On
- php_value zlib.output_compression_level 5
- If you use pre 0.9.5 you can also comment the following lines if they case problems
- 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
- Save the file and upload it to your MODx root folder
- If you are editing the file in Windows and try to save it with notepad, you may have problems saving the file as .htaccess, use ".htaccess" (with quotes) in the filename field instead and it should save fine. Or you can upload it to your webserver and rename using your FTP client.
- Log in to MODx manager
- In the manager, go to "Tools" -> "Configuration" (or "Administration" -> "System Configuration" pre 0.9.5)
- In the System configuration, choose "Friendly URL Settings" tab.
- Set "Use friendly URLs" to "Yes".
- Clear "Prefix for friendly URLs" field if it has anything.
- Set "Suffix for friendly URLs" to .html.
- Set "Use friendly aliases" to "Yes".
- Select "Save" to save the MODx configuration settings.
- Done! Edit some document and set something to the "Document's alias" field. Visit your site and look at the url to that document. It should be something like www.yourdomaing.com/alias.html.
Example .htaccess file
This is a example .htaccess file for a site that is installed in to a subfolder of the name "modx"
RewriteEngine On
RewriteBase /modx
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]
Non case-sensitive urls
If you want your urls to be non case-sensitive, you need to do the following change to the .htaccess file:
Replace:
- RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]
With:
- RewriteRule ^(.*)$ index.php?q=$1 [L,QSA,NC]
So add NC to the rewrite rule settings.
Troubleshooting
Added by: Rambat 17:10, 23 August 2007 (PDT)
If you have followed all the steps and you cannot obtain that it works, you would have to verify if your server allows .htaccess files. In order to verify it, simply add any junk text at the beginning of the .htaccess file (e.g. "Aq23we5a") and point your browser to the URL of your site. The idea here is to purposely throw an error. If you get one "500 Internal Server Error" then the .htaccess file is being parsed on your server and the problem lies somewhere else. (Don't forget to delete your junk text when you're done testing).
If you get any other response (e.g. the page loads normally), the most probable cause lies in the main Apache configuration file (commonly in /etc/httpd/conf/httpd.conf in Linux). The directive "AllowOverride" is probably set to "None". Change AllowOverride from "None" to "All" and test again (this assumes you have access to the file... which is probably only the case if you are the admin for the web server). Note that the AllowOverride setting appears in a LOT of places inside the config file. Specifically, you probably want to change the one that lives inside a tag something like this:
<Directory />
Options FollowSymLinks
AllowOverride all
</Directory>
(Did you remember to delete the junk text out of the .htaccess file?)
For more help:
- Apache Tutorial: .htaccess files
- Apache AllowOverride Directive
- Apache Module mod_rewrite
- URL Rewriting Guide
Friendly alias paths
Ok, ok.. This has been all fun and educative etc, but I have a site tree structure that looks like this:
- Blog
- Cars
- Did you know that a car has four wheels?
- Girls
- Cars
- About me
- Etc
How can I get a url to that blog page to be like www.mysite.com/Blog/Cars/Did-you-know-that-a-car-has-four-wheels you ask? Here's the steps to do just that:
- First, enable Friendly urls with mod_rewrite
- Make sure the HEAD element of all the templates you use contains a <base href="[(site_url)]" /> tag (or the MODx-generated links will be incorrect).
- Go to MODx manager and in to the "Friendly URL Settings" tab in system configuration.
- Set "Use friendly alias path" to "Yes".
- Set "Allow duplicate aliases" to "Yes".
- Select "Save" to save the MODx configuration settings.
- Done! Visit your page and navigate to that document. The site structure is turned in to "virtual folders" and you should see the effect in the urls.
NOTE! When using friendly alias paths, some snippets may not work correctly and you may have problems getting your css file or images included correctly. This happens because in the url, it looks like you are in for example /Blog/Cars/ folder and the web browser tries to search the resources that actually reside in site root from there. To fix this, you need to put [(base_url)] before the paths in your links and snippet developers should allways use $modx->config['base_url'] when building links manually. This is not needed when linking in to MODx documents using [~ID~] or in snippets, using MODx api (makeURL).
Making Friendly URLS work With XAMPP on Windows
I've been staging my website on Windows using XAMPP prior to uploading it to my server. I have had a number of problems with setting up the mod_rewrite until I discovered that Apache mod_rewrite is not enabled in the default XAMPP installation. You must enable it manually.
To do so, make the following two setting changes to the Apache httpd.conf file:
- mod_rewrite module is installed (Search file for "LoadModule rewrite_module" and un-comment that line)
- AllowOverride All (Search file for "AllowOverride None" and change it to "AllowOverride All")
Restarting the Apache web server is required for the changes to take effect.
I have XAMPP installed on my C drive, so my httpd.conf file is here: C:\xampp\apache\conf\httpd.conf
Adjust this for where you installed XAMPP.
See also
Making QuickEdit work with Friendly URLs
Categories: Tips | HOWTO
