URL Rewriting

Making URLs prettier using URL rewriting.

URL rewriting is a completely optional feature of Wheels, and all it does is get rid of the index.cfm part of the URL.

For example, with no URL rewriting, a URL in your application could look like this:

http://localhost/index.cfm/blog/new

After turning on URL rewriting, it would look like this:

http://localhost/blog/new

Combine this with the routing functionality of Wheels, and you get the capablility of creating some really human-friendly (easier to remember, say over the phone, etc.) and search engine friendly (easier to crawl, higher PageRank, etc.) URLs.

Once you have uncommented the rewrite rules (found in either .htaccess, web.config or IsapiRewrite4.ini), Wheels will try and determine if your web server is capable of rewriting URLs and turn it on for you automatically. Depending on what web server you have and what folder you run Wheels from, you may need to tweak things a little though. Follow these instructions below for details on how to set up your web server and customize the rewrite rules when necessary.

Instructions for Apache

On most Apache setups, you don't have to do anything at all to get URL rewriting to work. Just uncomment the rewrite rules in the .htaccess file and Apache will pick up and use them automatically on server start-up.

There are some exceptions though...

If you have installed Apache yourself you may need to turn on the rewrite module and/or change the security settings before URL rewriting will work:

Check that the Apache rewrite_module has been loaded by ensuring there are no pound signs before the line that says LoadModule rewrite_module modules/mod_rewrite.so in the httpd.conf file.
Make sure that Apache has permission to load the rewrite rules from the .htaccess file. This is done by setting AllowOverride to All under the Directory section corresponding to the website you plan on using Wheels on (still inside the httpd.conf file).

If you have an older version of Apache and you're trying to run your Wheels site in a sub folder of an existing site you may need to hard code the name of this folder in your rewrite rules.

Change the last line of the .htaccess file to the following: RewriteRule ^(.*)$ /sub_folder_name_goes_here/rewrite.cfm/$1 [L]. Don't forget to change sub_folder_name_goes_here to the actual folder name first of course.

Instructions for IIS 7

Similar to Apache, IIS 7 will pick up the rewrite rules from a file located in the Wheels installation. In the case of IIS 7, the rules are picked up from the web.config file. (Don't forget to uncomment the XML block containing the rewrite rules in that file first.)

This requires that the URL Rewrite Module is installed. It's an IIS extension from Microsoft that you can download for free.

Instructions for IIS 6

Unfortunately, there is no built-in URL rewriting mechanism in IIS 6, so getting Wheels working with pretty URLs is a little more complicated than with Apache and IIS 7 (which often comes with the official "URL Rewrite Module" installed by default). Here's what you need to do:

Download Ionic's ISAPI Rewrite Filter. NOTE: the version must be v1.2.16 or later.
Unzip the file, get the IsapiRewrite4.dll file from the lib folder and put it in the root of your website. (It needs to be in the same folder as the IsapiRewrite4.ini file.)
To enable the rewrite filter in IIS 6, click on Properties for your website, then go to the ISAPI Filters tab and click the Add... button.
Type in anything you want as the Filter Name and point the Executable to the IsapiRewrite4.dll file.
Uncomment the rewrite rules in the IsapiRewrite4.ini file.

Deleting Unnecessary Files

The sole purpose of the .htaccess (for Apache), web.config (for IIS 7), and IsapiRewrite4.ini (for IIS 6) files is to make it possible to use URL rewriting.

Don't Forget to Restart

If you need to make changes to get URL rewriting to work, it's important to remember to always restart the web server and the ColdFusion server to make sure the changes are picked up by Wheels.

If you don't have access to restart services on your server, you can issue a reload=true request. It's often enough.

« Previous Chapter
Event Handlers

^ Top
Table of Contents

Next Chapter »
Using Routes

Comments

Read and submit questions, clarifications, and corrections about this chapter.

[Add Comment]

ColdFusion Developer says:

November 9, 2008 at 11:04 pm

Thank you for the link to download ISAPI filter. After watching the blawgh video I started searching for an URL rewrite utility for IIS but only found a tool which cost over $99. Good thing somebody has posted the above URL.

Best
Sam
ColdFusion Developer says:

November 22, 2008 at 5:21 am

I installed IIS7 and downloaded a simple install for URL Rewrite by Microsoft from http://www.iis.net/1692/ItemPermalink.ashx

If you too are running IIS7, you can you use my web.config file and place it to the root of your site after you have installed the utility.

The "web.config" file:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <rewrite>
            <rules>
                <rule name="CFWheels Rule>
                    <match url="^(.*)$" ignoreCase="false" />
                    <conditions logicalGrouping="MatchAll">
                        <add input="{SCRIPT_NAME}" negate="true" pattern="^/(flex2gateway|jrunscripts|cfide|cfformgateway|railo-context|files|images|javascripts|miscellaneous|stylesheets|rewrite.cfm|index.cfm)" />
                    </conditions>
                    <action type="Rewrite" url="/rewrite.cfm/{R:1}" />
                </rule>
            </rules>
        </rewrite>
    </system.webServer>
</configuration>

This works great and amazingly cool.

Best
Sam
Pushpa Gupta says:

December 25, 2008 at 4:12 am

I m using cold fusion built in server, I need to want to turn on URL rewriting, how i will do this. pls suggest me.

thanks
tsqware says:

June 21, 2009 at 12:53 am

I installed CFWheels on Mac OS X 10.4 using Apache 1.3 server. I added the LoadModule rewrite_module modules/mod_rewrite.so in the httpd.conf file and changed the AllowOverride to All. But when I try to do the HelloWorld tutorial and enter http://localhost:8500/WheelsSite/say/hello, I get a 404 not found error.
Please help.
Per says:

June 21, 2009 at 12:56 am

For URL rewriting to work the website needs to be at the root, i.e. http://localhost:8500/say/hello instead of http://localhost:8500/WheelsSite/say/hello.
reinhard says:

June 29, 2009 at 12:27 pm

*strange* i'm on an ubuntu (8.04) with apache2 and url_rewriting enabled. i can call all pages directly with
http://mysite.local/say/hello even deleting and adding work, but when i use linkto i and up with mysite.local/rewrite.cfm?controller=.... any guess about this?
thx!
Per says:

June 29, 2009 at 12:30 pm

Not sure, Reinhard but you can force Wheels to use a specific type of URL rewriting by adding set(URLRewriting="On") to your configuration files.
reinhard says:

June 29, 2009 at 12:32 pm

thx per ... that did the trick ;)
AJ Mercer says:

August 20, 2009 at 7:10 am

This is what I have for Railo on Resin

    <host id="cfwheel.webonix.org">
        <root-directory>./cfwheel.webonix.org</root-directory>
        <web-app id="/" document-directory="webroot"/>

        <rewrite-dispatch>
            <forward regexp="^(/(flex2gateway|jrunscripts|cfide|cfformgateway|railo-context|files|images|javascripts|miscellaneous|stylesheets).*)$" target="$1" />
            <forward regexp="^(/.+/.+/.*\?.+\..*)$" target="/rewrite.cfm/$1" />
            <forward regexp="^(/[^.]*)$" target="/rewrite.cfm/$1" />
        </rewrite-dispatch>

    </host>

So far it seems to be working fine
Groovetrain says:

September 13, 2009 at 6:31 pm

In order for this to work for me, on my development environment (OSX Leopard), I had to add the option to enable symlinks in the directory in my virtualhost:

<VirtualHost *:80>
  ServerName cfwheels.local
  DocumentRoot "/blah/blah/cfwheels"
  <directory "/blah/blah/cfwheels">
    AllowOverride All
    Options FollowSymLinks
  </directory>
</VirtualHost>

If I didn't have followsumlinks there, it would constantly give me a 403 forbidden when I tried to hit a controller without index.cfm.

Hope this helps somebody!

Groove
voluzion says:

November 12, 2009 at 7:51 pm

URL ReWriting won't work for me on Win2k3/IIS6 but works fine on Win7/IIS7. Any suggestion, I followed the instruction and I'm using the supplied .ini file which of course I uncommented the included rules. Restarted CF & IIS without success.
Clarke Bishop says:

November 30, 2009 at 3:29 pm

I had to modify the .htaccess file to make it work with the Helicon ISAPI Rewrite Manager. Here's what I ended up with:

#This works for Helicon ISAPI Rewrite Manager
RewriteRule (^/(flex2gateway|jrunscripts|cfide|cfformgateway|railo-context|files|images|javascripts|miscellaneous|stylesheets|robots.txt|sitemap.xml|rewrite.cfm)($|/.*$)) $1 [L,I]
RewriteRule ^/(.*)$ /rewrite.cfm/$1 [L]
Andor Admiraal says:

January 2, 2010 at 3:06 am

Using IIS7 and CF9 it took me a while to figure out how to make URL rewriting work.

In the description above, it is mentioned that Wheels turns on URL rewriting automatically when it finds your server is capable. Apparently, that doesn't always work correctly.

If rewriting isn't working on IIS and you checked all the basics, you can go to the IIS7 management console and choose the correct site for your Wheels application. Under the heading IIS, you find a button called 'URL Rewrite'. Double click this button, and under 'state' you see if rewriting is 'disabled' or 'enabled'. From here on it's pretty self explanatory: if it's disabled, right click on the rule and choose to enable it.

After puzzling for quite some time as to what could be the problem, this solved it for me. No clue why Wheels 1.0 isn't able to turn it on by default on my particular server.
Keith says:

February 20, 2010 at 12:31 pm

I'm in the same boat with Pushpa. Any way to make rewriting work with the built-in dev server?
Claude says:

May 31, 2010 at 1:36 pm

For those of you asking if rewrite is possible without a front-end server like Apache or IIS the answer is no.

I just setup cfwheels 1.0.4 on Mac OSX with Apache 2.2.14. I use virtual hosts in order to develop multiple sites at once, here is my config:

<code class="block">
<VirtualHost *:80>

  ServerAdmin cbetancourt@gmail.com
  DocumentRoot "/Users/myaccount/Documents/WHEELS_TEST"
  ServerName wheelstest.com
  ErrorLog "/private/var/log/apache2/wheels-test-error.log"
  CustomLog "/private/var/log/apache2/wheels-test-access.log" common

  <Directory "/">

    Options +FollowSymLinks

    <IfModule dir_module>
      DirectoryIndex index.cfm
    </IfModule>

    # BEGIN Wheels redirect
    <IfModule mod_rewrite.c>
      RewriteEngine On
      RewriteBase /
      RewriteCond %{REQUEST_FILENAME} !-f
      RewriteCond %{REQUEST_FILENAME} !-d
      RewriteRule ^(.*)$ ./rewrite.cfm/$1 [L]
    </IfModule>
    # END Wheels redirect

  </Directory>

</VirtualHost>
</code>

Notice I've replaced the RewriteCond provided (in .htaccess) with the framework to one that redirects only when the file or directory requested doesn't exist.
Mike Henke says:

June 10, 2010 at 5:34 am

Claude is mistaken. It is possible to have url rewriting with just the application server (Tomcat, Resin, JRun). Jrun is the built in Adobe CF application server. http://www.henke.ws/post.cfm/jrun-url-rewriting
jmail says:

June 11, 2010 at 11:22 pm

Claude sorry but you are completly wrong!

I have mad Tomcat config using urlrewrite http://tuckey.org/urlrewrite/ and with that xml:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE urlrewrite PUBLIC "-//tuckey.org//DTD UrlRewrite 2.6//EN"
        "http://tuckey.org/res/dtds/urlrewrite2.6.dtd">;
<urlrewrite>
    <rule>
       <condition type="request-uri" operator="notequal">^/$</condition>
       <condition type="request-uri" operator="notequal">^$</condition>
       <condition type="request-uri" operator="notequal">^(.*)/railo-context(.*)$</condition>
       <condition type="request-uri" operator="notequal">^(.*)/flex2gateway(.*)$</condition>
       <condition type="request-uri" operator="notequal">^(.*)/jrunscripts(.*)$</condition>
       <condition type="request-uri" operator="notequal">^(.*)/cfide(.*)$</condition>
       <condition type="request-uri" operator="notequal">^(.*)/cfformgateway(.*)$</condition>
       <condition type="request-uri" operator="notequal">^(.*)/files(.*)$</condition>
       <condition type="request-uri" operator="notequal">^(.*)/images(.*)$</condition>
       <condition type="request-uri" operator="notequal">^(.*)/javascripts(.*)$</condition>
       <condition type="request-uri" operator="notequal">^(.*)/miscellaneous(.*)$</condition>
       <condition type="request-uri" operator="notequal">^(.*)/stylesheets(.*)$</condition>
       <condition type="request-uri" operator="notequal">^(.*)/robots.txt(.*)$</condition>
       <condition type="request-uri" operator="notequal">^(.*)/sitemap.xml(.*)$</condition>
       <condition type="request-uri" operator="notequal">^(.*)/rewrite.cfm(.*)$</condition>
       <condition type="request-uri" operator="notequal">^/(.*).gif$</condition>
       <condition type="request-uri" operator="notequal">^/(.*).jpg$</condition>
       <condition type="request-uri" operator="notequal">^/(.*).png$</condition>
       <from>^/(.*)$</from>
       <to>/rewrite.cfm/$1</to>
    </rule>
</urlrewrite>

Now i've got problem beacuse wheels don't want to rewrite the URLs properly. they are giving links with partial rewrite but I have forced that on the settings file
Graham says:

September 15, 2010 at 8:12 am

I followed the instructions to implement the url rewrite for IIS 6. I went to the http://iirf.codeplex.com/ website and downloaded the zip. I could not find any lib folder and there is no IsapiRewrite4.dll file.

The only thing that I could find is IIRF.dll file. Can you use this file to make the CfWheels rewrite work, because I placed this file IIRF.dll in the root directory along with the IsapiRewrite4.ini file then I went into IIS 6 website properties and added this ISAPI filter to point to the IIRF.dll file. I also uncommented out the rewrite rules in IsapiRewrite4.ini file. I restarted Coldfusion and IIS 6 and rebooted the server and my rewrite does not work.

I also renamed this IIRF.dll to IsapiRewrite4.dll and went through the whole process again and this does not work.

Please if anyone has any knowledge on this, I would greatly appreciate your help!!
Kristof Polleunis says:

September 17, 2010 at 7:25 pm

If you would like to place all  your sites in a subdirectory and still have url-rewriting working for Resin you can do this:
The only thing you need to do is for each site create an entry in your /etc/hosts file for each of your sites.

    <host regexp="([^.]+)\.local">
      <host-name>${host.regexp[1]}.local</host-name>
      <root-directory>${resin.home}/webapps/CFWheels/${host.regexp[1]}</root-directory>
      <web-app id="/" document-directory="."/>
      <rewrite-dispatch>
          <forward regexp="^(/(flex2gateway|jrunscripts|cfide|cfformgateway|railo-context|files|images|javascripts|miscellaneous|stylesheets).*)$" target="$1" />
          <forward regexp="^(/[^.]*)$" target="/rewrite.cfm/$1" />
      </rewrite-dispatch>
    </host>

You can then access your subfolder sites, like this :

http://SUBFOLDER1.local/
http://SUBFOLDER2.local/

If you work on Mac you can download a fully functioning wheels server (just an app you drag into your Application folder and that's it) from:

http://github.com/Stofke72/CFWheels-Server
John Moran says:

October 14, 2010 at 7:44 am

I am trying to use the testing framework in version 1.1 however with url rewriting turned on when I try to run the tests the URL rewriting no longer works. It works in all other cases however. Is there a way to fix this?

P.S. The error I'm getting is "Could not find the view page for the wheels action in the rewrite controller."
Jason Weible says:

October 15, 2010 at 11:44 am

Ionic's Isapi Rewrite Filter version 2.1 (the most recent version) does not work with IIS6. I went and found the version 1.2.16 and it started working immediately. Maybe it is just because the file name of the .dll is different, I didn't try renaming it.
Jaynay.com says:

January 11, 2011 at 4:53 am

Here is where you can download the correct version of Ionic's Rewrite (the one that has the right .dll file)

http://iirf.codeplex.com/releases/view/29936
Nor says:

January 14, 2011 at 2:29 am

For apache
Options +FollowSymLinks
RewriteEngine On
RewriteBase /cfwheels/
RewriteCond %{REQUEST_URI} (/|\.htm|\.cfm|\.html|/[^.]*)$ [NC]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^([^/\.]+)/?$ rewrite.cfm/$1 [L]
Jed says:

February 16, 2011 at 3:02 am

actually, Ionic's Rewrite 2.1 does work. It took me a second, but the trick is to rename the IsapiRewrite4.ini file to iirf.ini and it should pick it up right away.
Ennio Bozzetti says:

March 2, 2011 at 5:01 am

Thanks for the tip Jed... got it to work. :D
tony petruzzi says:

September 20, 2011 at 7:51 am

need to update this page with the tomcat instructions from.

http://craigkaminsky.me/cfwheels-and-ses-urls
John Sieber says:

December 9, 2011 at 9:57 am

I'm struggling with getting url rewriting to work on the following setup:
IIS 7 and Railo 3.3 with Tomcat
I'm trying to run my cfwheels application from within a sub directory that is off of the root of my site. The root folder contains a mango blog installation that is also using url rewriting and that portion is working properly.

I also have these sites on another server that is running Apache and Railo with Resin and the url rewriting works properly for both the Mango blog site in the root and the cfwheels application that is running out of a folder off of the root.

Any thoughts or ideas on steps to troubleshoot this further? All thoughts are appreciated.