Installation » Friendly URLs » Configuring Apache

Configuring Apache to use Friendly URLs

The .htaccess files

We need two .htaccess files, one in the main Etomite folder, and one in the manager folder. In the first one, we tell Apache how to use the RewriteEngine to convert friendly urls back to calls to index.php, and in the second, we tell Apache not to use the Rewrite Engine at all (as it is not needed, or helpful, for the etomite manager).

Etomite folder

The first file, to be placed in the main Etomite folder, needs as a minimum to contain the following:

In the first line, we tell Apache we want to use the RewriteEngine.

The second line sets a condition that we will only continue if the request name does not match an existing filename (where presumably we actually want to use the existing file!

The third line sets a condition that we will only continue if the request name does not match an existing directory name. (Again, if it did, we probably want to use that directory.)

The last line does most of the work, and tells Apache how to rewrite the URL so it correctly calls the Etomite parser. In the example given it simply takes the requested filename, and pastes it in as a parameter to the etomite parser (index.php). The [L, QSA] part says firstly that this is the last command to execute for this request, and secondly that any query string appended to the original request should be added to the generated URL.

Improving the default .htaccess

The RewriteRule above is good for testing, as you don't have to worry about potential of errors in the match string, but is so broad as to give errors in some cases. An example is that the Firefox browser checks for a 'favicon.ico' file to display with the url when you open a page. If it doesn't exist, the request is passed on to index.php, ony to result in an error page being returned from etomite ... unless you happen to have named a page favicon.

If you have defined a suffix for friendly URLs you can modify the match string to check that the correct suffix is in place, and only match expected URL patterns. For example, if your suffix was ".htm" you could use

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

to replace the original rewrite rule. (The rule should be all on one line.) You probably don't want to do this until you've tested that everything works with the supplied file, though.

Etomite manager folder

The second .htaccess file, located in the manager folder contains only one line:

RewriteEngine Off

This tells Apache not to apply any rewriting rules in the manager folder.

Testing

Before moving on to configure etomite its worth doing a simple test that the files don't cause problems. Rename the ht.access file provided in the Etomite distribution to .htaccess in both directories, and check that the site still operates. (Until you enable friendly URLs in etomite all URLS are of the form index.php?id=nn, which are caught by the first condition and passed on unaltered. If all is working correctly, the site should work exactly as before. If not, ask for help in the forum.

Configuring Etomite - Friendly URL settings

Now we need to tell Etomite to use Friendly URLs. To do this, in the Etomite manager, go to Etomite configuration in the Administration menu. There you will see three options for Friendly URLs: First, set 'Use friendly URLs' to 'Yes'. Then, specify your prefix and suffix, and enable friendly URLs. Use the prefix and suffix you decided on when planning.

Save the settings and that's all there is to it!

Open your site, and hover your mouse over a link in your page. If everything's working properly, you should see links like you planned - something like 'alias.html' instead of 'index.php?id=123'. Clicking on one of the links should open the correct page. (They are now being changed by the rewrite rule to call index.ph with the right parameters.

There is more chance of problems at this stage; if you do have problems, ask in the forums after looking at the long discussion of friendly URLs on the forum at http://www.etomite.org/forums/index.php?showtopic=548

Etomite Documentation