Friendly URLs Guide

From MODx Wiki

Jump to: navigation, search

Contents

[edit]

Background

URLs are something we see and use everyday on the net. People share urls in chatrooms, emails, mailing lists etc.. Wouldn't it be nice if you had at least a little idea what you can expect to be behind that url? That's what friendly urls are about. Friendly urls are often referred as human readable urls, so instead of having url www.mysite.com/index.php?id=123 you have something like www.mysite.com/index.php?page=my-blog-post-about-modx or with some server side support, you can achieve urls like www.mysite.com/my-blog/post-about-modx.html. Search engines also 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 for example Google's guidelines [here]. Following sections shows how you can set up the different level friendly urls in MODx.

[edit]

SEO (Google) Friendly URLs

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, so that fails when looking through Google's glasses. There is a way to fix this though! Here are the steps:

  1. Log in to MODx Manager.
  2. In the manager, go to "Tools" -> "Configuration" (or "Administration" -> "System Configuration" pre 0.9.5)
  3. In the System configuration, choose "Friendly URL Settings" tab.
  4. Set "Use friendly URLs" to "Yes".
  5. Change "Prefix for friendly URLs" to "index.php?q=" (or index.php?page= etc.)
  6. Select "Save" to save the MODx configuration settings.
  7. 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.

[edit]

Friendly urls without mod_rewrite

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.

  1. Do the steps that are described in SEO (Google) Friendly url's
  2. Go to the "Friendly URL Settings" tab.
  3. Set "Use friendly aliases" to "Yes".
  4. Select "Save" to save the MODx configuration settings.
  5. Edit some document and set something to the "Document's alias" field.
  6. 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.
[edit]

Friendly urls with mod_rewrite

To have the fully qualified friendly urls you have to have mod_rewrite support in your server. Here are the steps how to get this setup:

  1. 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.
  2. Rename both of these files to .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.
  3. Open the file that is in MODx root folder for editing
  4. If you use pre 0.9.5 MODx add the following setting to the .htaccess file:
    1. RewriteBase / if MODx is installed to the site root
    2. RewriteBase /folder if MODx is installed in to a subfolder called "folder"
  5. If you have installed MODx in to a subfolder you may also need to do the following change:
    1. change RewriteRule ^(.*)$ index.php?q=$1 [L,QSA] into RewriteRule ^(.*)$ /folder/index.php?q=$1 [L,QSA]
  6. 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
    1. php_flag zlib.output_compression On
    2. php_value zlib.output_compression_level 5
  7. If you use pre 0.9.5 you can also comment the following lines if they case problems
    1. ExpiresActive On
    2. ExpiresByType image/gif A2592000
    3. ExpiresByType image/jpeg A2592000
    4. ExpiresByType image/png A2592000
    5. BrowserMatch "MSIE" brokenvary=1
    6. BrowserMatch "Mozilla/4.[0-9]{2}" brokenvary=1
    7. BrowserMatch "Opera" !brokenvary
    8. SetEnvIf brokenvary 1 force-no-vary
  8. Save the file and upload it to your MODx root folder
    1. 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.
  9. Log in to MODx manager
  10. In the manager, go to "Tools" -> "Configuration" (or "Administration" -> "System Configuration" pre 0.9.5)
  11. In the System configuration, choose "Friendly URL Settings" tab.
  12. Set "Use friendly URLs" to "Yes".
  13. Clear "Prefix for friendly URLs" field if it has anything.
  14. Set "Suffix for friendly URLs" to .html.
  15. Set "Use friendly aliases" to "Yes".
  16. Select "Save" to save the MODx configuration settings.
  17. 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.


[edit]

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]
[edit]

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.

[edit]

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 ErrorTest (Or any other word) at the beginning of the .htaccess file and point your browser to the URL of your site. If you get one "500 Internal Server Error" then the .htaccess files work on your server and the problem is other.

If you get any other answer, the most probable is than in the main configuration file of apache (normally in /etc/httpd/conf/httpd.conf in Linux) the directive "AllowOveride" is set to "None". If that is the problem change the "None" to "All" and test again.

For more help:

[edit]

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
  • 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:

  1. First, enable Friendly urls with mod_rewrite
  2. 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).
  3. Go to MODx manager and in to the "Friendly URL Settings" tab in system configuration.
  4. Set "Use friendly alias path" to "Yes".
  5. Set "Allow duplicate aliases" to "Yes".
  6. Select "Save" to save the MODx configuration settings.
  7. 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).

[edit]

See also

Making QuickEdit work with Friendly URLs

Retrieved from "http://wiki.modxcms.com/index.php/Friendly_URLs_Guide"
Personal tools