Last updated: 2006-01-21 23:01

Clean mode is guaranteed to break your site

The default configuration for clean URLs will interfere with Texpattern’s normal operation if the assigned name of any custom field is also—

  • the name of any directory in your Txp root, like ‘textpattern’, ‘images’, or ‘files’.
  • the name of any section.
  • the name of any pseudo-path reserved for use by Txp, like ‘category’, ‘author’, ‘rss’, ‘atom’, etc.
  • the url-title of any article, when using Txp’s '/section/title' or '/title' permanent link mode.
  • a number, when using '/id/title' or '/year/month/day/title' mode.

Likewise, no section or article title can be the word ‘keywords’.

This does not mean you will be unable to use clean mode if any of the above hold true for your site. You will, however, need to adjust some plugin settings.

Also, it’s possible that some plugins may act unpredictably on keyword query pages. To avoid unwanted side-effects, make judicious use of the chh_if_keywords tag to separate keywords tags from normal article and article list tags.

Finally, clean mode is experimental. It may break in new and unusual ways that I have not anticipated. It will almost assuredly fail on IIS.

Okay, that’s all of the warnings.

Enabling clean URLs

By default, clean mode is disabled. Before attempting to enable clean mode, install the plugin and set up your article and page templates to work in messy mode.

Once everything is working to your satisfaction, go to admin > plugins and edit the chh_keywords plugin. At the top of the source code window, you will see a line like this:

define('CHH_KW_CLEAN', 0);

Change CHH_KW_CLEAN setting to ‘1’:

define('CHH_KW_CLEAN', 1);

Click 'Save', then browse to a page that has a chh_keywords_list on it. If all is well, the keyword links will open as normal, but with prettified non-messy URLs.

Producing rel-tag compliant links

Clean URLs means that your keywords links can now be recognized by crawlers from the various tag aggregator sites. Simple add the attribute rel="tag" to your chh_keyword_list tags.

Changing the supplemental path

The default scheme for clean URLs is

  • site-root/FieldName/Keyword
  • site-root/section/FieldName/Keyword

If your custom field names conflict with normal Txp operation (as indicated in “Clean mode is guaranteed to break your site” above), you may set a label—’kw’, for example—to differentiate the path, producing URLs like this:

  • site-root/kw/FieldName/Keyword
  • site-root/section/kw/FieldName/Keyword

It is set by changing another of the constant declarations at the top of the plugin source:

define('CHH_KW_PATH', '');

In the case of our ‘kw’ example, we would change the above line to this:

define('CHH_KW_PATH', 'kw');

The path label may be any legal URL-encoded text. Just make sure this supplemental path label won’t also conflict with any Txp URLs.