Composr Tutorial: URL Schemes in Composr

Written by Chris Graham
Composr supports short URLs. Officially we only support them in Apache, but practically you can get them working on any web server.

These short URLs have the following advantages:
  • More intuitive URL structure
  • More professional looking URLs, no direct reference to the website's implementation language
  • Easier to communicate, either verbally or through services such as Twitter
  • Quicker to type in
  • SEO improvement (to be honest, it is debatable, but it is very popular – the URL moniker feature is more relevant to SEO)

Short URLs are enabled via the "URL Scheme" feature. In fact we have a number of different schemes you can choose from.

Table of contents

  1. Composr Tutorial: URL Schemes in Composr
    1. URL Schemes
      1. An example: linking to your own member profile
    2. Setup instructions
      1. Apache
        1. If it won't save
        2. Debugging
    3. Enabling a URL Scheme retroactively
    4. See also

URL Schemes

Composr uses "page-links" for internal configuration instead of URLs because of how the URL Scheme changes how URLs are structured. The URL Scheme determines how a page-link is turned into a URL.

The available URL Schemes are:
  • Use /pg/ to identify CMS pages (e.g. /pg/home)
  • Use .htm to identify CMS pages (e.g. /home.htm)
  • Very simple unadorned URLs (e.g. /home)

"Use /pg/ to identify CMS pages" is recommended for novice users because it is unambiguous and simple to set up.

"Use .htm to identify CMS pages" requires the .htaccess file (or non-Apache equivalent) to have an awareness of each Composr zone, so it can disambiguate requests and thus route them to the correct zone.

"Very simple unadorned URLs" is great, but the webmaster may need to be very skilled at web server administration if they have other software packages installed in the same directory as Composr. The redirect rules for this are commented out in the default .htaccess files.

An example: linking to your own member profile

Often site owners wish to link to the current logged in member's profile. It is not obvious how to create a generic link for this, and it is hard to give one to a webmaster because it depends upon their URL Scheme (and base URL).
We therefore will use this scenario of an example of how the URL would look in all the different URL Schemes.

Let's start with the page-link. If you don't supply an id parameter to the view screen of the members module then it will automatically use the current member's ID (or show a login screen if it's a guest).
The page-link is therefore:
:members:view
(I've assumed "Single public zone" is on, if that option is off then it would be site:members:view)

If no URL Scheme (Raw PHP-style URLs) is enabled then the URL generated would be:
http://yourbaseurl/index.php?page=members&type=view

If the URL Scheme is "Use /pg/ to identify CMS pages":
http://yourbaseurl/pg/members/view

If the URL Scheme is "Use .htm to identify CMS pages":
http://yourbaseurl/members/view.htm

If the URL Scheme is "Very simple unadorned URLs":
http://yourbaseurl/members/view

For completeness, let's show what they would be if it was linking to member #3:
  • :members:view:3
  • http://yourbaseurl/index.php?page=members&type=view&id=3
  • http://yourbaseurl/pg/members/view/3
  • http://yourbaseurl/members/view/3.htm
  • http://yourbaseurl/members/view/3
(actually, depending on configuration, the number might be based on the username rather than the ID)

Setup instructions

Composr can do URL Schemes on the following web-servers:
  • Apache (using mod_rewrite, and our rules in recommended.htaccess – details below)
  • Litespeed Server (as above, Litespeed simulates Apache)
  • IIS7 (due to the rules in our web.config)
  • Advanced users: potentially any server that supports URL rewrites that you are able to hand-configure

Apache

Perform the following steps:
  1. If you haven't already got a working Composr .htaccess file (the quick installer may have made it for you automatically), rename recommended.htaccess to .htaccess.
  2. If things go wrong, you can disable URL Schemes via an emergency shut off option in the http://yourbaseurl/config_editor.php script. Make sure you see where it is before proceeding to the next step.
  3. Enable a URL Scheme from your site options (Admin Zone > Setup > Configuration > Site options > Search Engine Optimisation / Tagging).

If it won't save

It is possible saving the configuration will result in an error like following:
Before you may enable mod_rewrite support, you must enable it on the web server.

Composr checks both that the .htaccess contains an instruction to enable rewrite rules, and that the sitemap page loads via a URL Scheme.
If the .htaccess is incorrect, in the wrong place, if the RewriteBase line is wrong, or if somehow it is not working right for any other reason, this error could happen.

A good manual debug tool would be to go to http://yourbaseurl/sitemap.htm and see what happens. If it won't load, debug your .htaccess and/or server settings, then try again to change the Composr configuration as above.

Debugging

This section covers the case where the rewrite rules are not working on the server level. e.g. loading http://yourbaseurl/sitemap.htm fails.

A number of things can be wrong to stop the rules defined in .htaccess from working.

A good first step is to add some gibberish at the very top of .htaccess, like gdfgdfgdfgd. If adding this doesn't stop Composr pages loading, then the .htaccess file is not being read at all. This will usually be caused by Apache not having AllowOverride set for the path you are working in. This will need resolving at the main Apache configuration level. Alternatively you could be making some silly mistake, e.g. missing the dot off the start of the filename, or accidentally adding .txt on the end, or doing it in the wrong directory – so re-check your basic assumptions too.

If you did get an error (500 Internal Server Error), then take the gibberish back out. Try now removing the <IfModule mod_rewrite.c> line and the </IfModule> line further down.
If you then get a 500 Internal Server Error again then the mod_rewrite module is not set up in Apache. This will need resolving at the main Apache configuration level.

If you're still stuck (i.e. you've determined .htaccess is being read, and mod_rewrite is set up), but rewrite rules still don't work, it's a bit of a mystery. You may need to talk to a developer or Apache expert.

Enabling a URL Scheme retroactively

Enabling a URL Scheme on an existing site will not break old URLs, those URLs will just redirect, and the canonical URL will be specified in the HTML header under a meta tag regardless.
So don't think that changing the URL Scheme is disastrous for your SEO.


See also


Feedback

Please rate this tutorial:

Have a suggestion? Report an issue on the tracker.