[title sub="Written by Chris Graham"]Composr Tutorial: URL Schemes in Composr[/title]

Composr supports short URLs. [i]Officially[/i] we only support them in Apache, but practically you can get them working on any web server.

[media thumb="0" framed="0" float="right"]data_custom/images/docs/advantage.png[/media]
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 [page="_SEARCH:tut_seo"]URL moniker feature is more relevant to SEO[/page])

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

[contents]decimal,lower-alpha[/contents]

[title="2"]URL Schemes[/title]

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. [tt]/pg/home[/tt])
 - Use .htm to identify CMS pages (e.g. [tt]/home.htm[/tt])
 - Very simple unadorned URLs (e.g. [tt]/home[/tt])

"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 [tt].htaccess[/tt] 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 [tt].htaccess[/tt] files.

[title="3"]An example: linking to your own member profile[/title]

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 [tt]id[/tt] parameter to the [tt]view[/tt] screen of the [tt]members[/tt] 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:
[tt]:members:view[/tt]
(I've assumed "Single public zone" is on, if that option is off then it would be [tt]site:members:view[/tt])

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

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

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

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

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

[title="2"]Setup instructions[/title]

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

[title="3"]Apache[/title]

[media thumb="0" framed="0" float="right"]data_custom/images/docs/tut_url_schemes/apache.png[/media]
Perform the following steps:
1) If you haven't already got a working Composr [tt].htaccess[/tt] file (the quick installer may have made it for you automatically), rename [tt]recommended.htaccess[/tt] to [tt].htaccess[/tt].
2) If things go wrong, you can disable URL Schemes via an emergency shut off option in the [tt]http://yourbaseurl/config_editor.php[/tt] 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).

[title="4"]If it won't save[/title]

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

Composr checks both that the [tt].htaccess[/tt] contains an instruction to enable rewrite rules, and that the sitemap page loads via a URL Scheme.
If the [tt].htaccess[/tt] is incorrect, in the wrong place, if the [tt]RewriteBase[/tt] 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 [tt]http://yourbaseurl/sitemap.htm[/tt] and see what happens. If it won't load, debug your [tt].htaccess[/tt] and/or server settings, then try again to change the Composr configuration as above.

[title="4"]Debugging[/title]

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

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

A good first step is to add some gibberish at the very top of [tt].htaccess[/tt], like [tt]gdfgdfgdfgd[/tt]. If adding this doesn't stop Composr pages loading, then the [tt].htaccess[/tt] file is not being read at all. This will usually be caused by Apache not having [tt]AllowOverride[/tt] 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 [tt].txt[/tt] 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 [tt]<IfModule mod_rewrite.c>[/tt] line and the [tt]</IfModule>[/tt] line further down.
If you then get a 500 Internal Server Error again then the [tt]mod_rewrite[/tt] 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 [tt].htaccess[/tt] is being read, and [tt]mod_rewrite[/tt] is set up), but rewrite rules still don't work, it's a bit of a mystery. You may need to talk to your webhost, a developer, or Apache expert.

[title="2"]Enabling a URL Scheme retroactively[/title]

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
 1_key="URL Scheme"      1_value="A way to make URLs simpler than the default PHP URLs"
]Concepts[/concepts]

[title="2"]See also[/title]

 - [page="_SEARCH:tut_adv_configuration"]Advanced configuration[/page]
 - [page="_SEARCH:tut_seo"]Improving your search engine ranking[/page]

{$SET,tutorial_tags,SEO,Configuration,core,regular}{$SET,tutorial_add_date,Nov 2014}{$SET,tutorial_summary,Enabling attractive short URLs, for usability and SEO.}[block]main_tutorial_rating[/block]
