Composr Tutorial: URL Schemes in Composr

Written by Chris Graham (ocProducts)
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
      2. IIS6 and below
    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/start)
  • Use .htm to identify CMS pages (e.g. /start.htm)
  • Very simple unadorned URLs (e.g. /start)

"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 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 also 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)
  • IIS6 and below, if the IIRF extension is installed (details below)
  • Facebook's HHVM (built into our bundled configuration files)

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. If your site gives errors after doing this, try plain.htaccess instead.
  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, and 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.

IIS6 and below

You need to be a server administrator of your server, to install the free IIRF ISAPI module available from:
https://iirf.codeplex.com/

The developers cannot take responsibility or provide support for this feature. We're happy to answer questions, but fiddling with your web server is only for those in the know. It is best you try things out on a test website before your live one.

To install IIRF:
  1. Copy IIRF.dll into your Inetpub folder
  2. In IIS manager add the dll as an ISAPI filter, but only to the website that runs Composr. This means that the IIRF plugin will only affect the Composr website, which is important because the IIRF configuration file is not modular – if it were applied to all websites on the server, it could cause serious problems.
  3. Make an IirfGlobal.ini file in your Inetpub folder containing the following:

    Code

    # Anything that would point to a real file should actually be allowed to do so. If you have a "RewriteBase /subdir" command, you may need to change to "%{DOCUMENT_ROOT}/subdir/$1".
    RewriteCond %{DOCUMENT_ROOT}/$1 -f [OR]
    RewriteCond %{DOCUMENT_ROOT}/$1 -l [OR]
    RewriteCond %{DOCUMENT_ROOT}/$1 -d
    RewriteRule (.*) - [L]

    # Redirect away from modules called directly by URL. Helpful as it allows you to "run" a module file in a debugger and still see it running.
    RewriteRule ^([^=]*)pages/(modules|modules_custom)/([^/]*)\.php$ $1index.php\?page=$3 [L,R,QSA]

    # PG STYLE: These have a specially reduced form (no need to make it too explicit that these are Wiki+). We shouldn't shorten them too much, or the actual zone or base URL might conflict
    RewriteRule ^([^=]*)pg/s/([^\&\?]*)/index\.php$ $1index.php\?page=wiki&id=$2 [L,QSA]

    # PG STYLE: These are standard patterns
    RewriteRule ^([^=]*)pg/([^/\&\?]*)/([^/\&\?]*)/([^\&\?]*)/index\.php(.*)$ $1index.php\?page=$2&type=$3&id=$4$5 [L,QSA]
    RewriteRule ^([^=]*)pg/([^/\&\?]*)/([^/\&\?]*)/index\.php(.*)$ $1index.php\?page=$2&type=$3$4 [L,QSA]
    RewriteRule ^([^=]*)pg/([^/\&\?]*)/index\.php(.*)$ $1index.php\?page=$2$3 [L,QSA]
    RewriteRule ^([^=]*)pg/index\.php(.*)$ $1index.php\?page=$2 [L,QSA]

    # PG STYLE: Now the same as the above sets, but without any additional parameters (and thus no index.php)
    RewriteRule ^([^=]*)pg/s/([^\&\?]*)$ $1index.php\?page=wiki&id=$2 [L,QSA]
    RewriteRule ^([^=]*)pg/([^/\&\?]*)/([^/\&\?]*)/([^\&\?]*)/$ $1index.php\?page=$2&type=$3&id=$4 [L,QSA]
    RewriteRule ^([^=]*)pg/([^/\&\?]*)/([^/\&\?]*)/([^\&\?]*)$ $1index.php\?page=$2&type=$3&id=$4 [L,QSA]
    RewriteRule ^([^=]*)pg/([^/\&\?]*)/([^/\&\?]*)$ $1index.php\?page=$2&type=$3 [L,QSA]
    RewriteRule ^([^=]*)pg/([^/\&\?]*)$ $1index.php\?page=$2 [L,QSA]

    # PG STYLE: And these for those nasty situations where index.php was missing and we couldn't do anything about it (usually due to keep_session creeping into a semi-cached URL)
    RewriteRule ^([^=]*)pg/s/([^\&\?\.]*)&(.*)$ $1index.php\?$3&page=wiki&id=$2 [L,QSA]
    RewriteRule ^([^=]*)pg/([^/\&\?\.]*)/([^/\&\?\.]*)/([^/\&\?\.]*)&(.*)$ $1index.php\?$5&page=$2&type=$3&id=$4 [L,QSA]
    RewriteRule ^([^=]*)pg/([^/\&\?\.]*)/([^/\&\?\.]*)&(.*)$ $1index.php\?$4&page=$2&type=$3 [L,QSA]
    RewriteRule ^([^=]*)pg/([^/\&\?\.]*)&(.*)$ $1index.php\?$3&page=$2 [L,QSA]

    # HTM STYLE: These have a specially reduced form (no need to make it too explicit that these are Wiki+). We shouldn't shorten them too much, or the actual zone or base URL might conflict
    RewriteRule ^(site|forum|adminzone|cms|collaboration)/s/([^\&\?]*)\.htm$ $1/index.php\?page=wiki&id=$2 [L,QSA]
    RewriteRule ^s/([^\&\?]*)\.htm$ index\.php\?page=wiki&id=$1 [L,QSA]

    # HTM STYLE: These are standard patterns
    RewriteRule ^(site|forum|adminzone|cms|collaboration)/([^/\&\?]+)/([^/\&\?]*)/([^\&\?]*)\.htm$ $1/index.php\?page=$2&type=$3&id=$4 [L,QSA]
    RewriteRule ^(site|forum|adminzone|cms|collaboration)/([^/\&\?]+)/([^/\&\?]*)\.htm$ $1/index.php\?page=$2&type=$3 [L,QSA]
    RewriteRule ^(site|forum|adminzone|cms|collaboration)/([^/\&\?]+)\.htm$ $1/index.php\?page=$2 [L,QSA]
    RewriteRule ^([^/\&\?]+)/([^/\&\?]*)/([^\&\?]*)\.htm$ index.php\?page=$1&type=$2&id=$3 [L,QSA]
    RewriteRule ^([^/\&\?]+)/([^/\&\?]*)\.htm$ index.php\?page=$1&type=$2 [L,QSA]
    RewriteRule ^([^/\&\?]+)\.htm$ index.php\?page=$1 [L,QSA]

    # SIMPLE STYLE: These have a specially reduced form (no need to make it too explicit that these are Wiki+). We shouldn't shorten them too much, or the actual zone or base URL might conflict
    #RewriteRule ^(site|forum|adminzone|cms|collaboration)/s/([^\&\?]*)$ $1/index.php\?page=wiki&id=$2 [L,QSA]
    #RewriteRule ^s/([^\&\?]*)$ index\.php\?page=wiki&id=$1 [L,QSA]

    # SIMPLE STYLE: These are standard patterns
    #RewriteRule ^(site|forum|adminzone|cms|collaboration)/([^/\&\?]+)/([^/\&\?]*)/([^\&\?]*)$ $1/index.php\?page=$2&type=$3&id=$4 [L,QSA]
    #RewriteRule ^(site|forum|adminzone|cms|collaboration)/([^/\&\?]+)/([^/\&\?]*)$ $1/index.php\?page=$2&type=$3 [L,QSA]
    #RewriteRule ^(site|forum|adminzone|cms|collaboration)/([^/\&\?]+)$ $1/index.php\?page=$2 [L,QSA]
    #RewriteRule ^([^/\&\?]+)/([^/\&\?]*)/([^\&\?]*)$ index.php\?page=$1&type=$2&id=$3 [L,QSA]
    #RewriteRule ^([^/\&\?]+)/([^/\&\?]*)$ index.php\?page=$1&type=$2 [L,QSA]
    #RewriteRule ^([^/\&\?]+)$ index.php\?page=$1 [L,QSA]
  4. Reset IIS
  5. Test a short URL (e.g. http://yourbaseurl/site/pg/downloads) – if it doesn't load, you've got a IIRF/IIS configuration problem.
  6. 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.

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.

Concepts

URL Scheme
A way to make URLs simpler than the default PHP URLs

See also


Feedback

Please rate this tutorial:

Have a suggestion? Report an issue on the tracker.