Skip to main content

Clean URLs

Backlight's pages use clean URLs when run on Apache servers in conjunction with the mod_rewrite module and .htaccess files.

In most cases this should work without any need for further configuration. This page serves to document steps needed in the event that clean URLs are not working, or that your site fails completely with the .htaccess files.

Clean URLs are not appearing

On launch, Backlight uses clean URLs in two ways:

  • Page URLs. If you have the Pages module installed, then page URLs should look like one of these, depending on the value of the Page URL Format setting found in the Backlight Settings: /about, /about/, about.html or about.php.
  • Single image URLs. These links are created in albums, and take the form image1234-single.php.

You'll know that clean URLs are not working, if those URLs are parameter based, such as ?page=about, or single.php?id=image1234. There is no harm in your site creating URLs in this format. Backlight is designed to use this format if .htaccess files are not found, empty or not supported.

If your site is using parameter based URLs there are some steps to take:

  • For Page URLs, check that the .htaccess file has been copied over from your setup zip file to the top of your site. You may need to configure your FTP client to be able to see hidden files in order to be able to copy this file over.
  • Check that your server supports .htaccess files and mod_rewrite and over-writing of configuration values in .htaccess files. Such settings are host-specific. You'll need to work with your host's technical support to assist.

You see a message 'No input file specified'

We have made the .htaccess files shipped with Backlight as flexible as possible. However, there are some server setups that we cannot cater for out-of-the-box. The 'No input file specified' message is one particular case. This is caused by your host's PHP being configured to run in FastCGI mode.

The main benefit of FastCGI is that it speeds up PHP execution. However, this mode changes the paths on the server, breaking our .htaccess files. Here are some options to resolve this:

  • Disable FastCGI. This would usually be set via your host's cPanel. As stated above, FastCGI provided performance benefits, so this option is less than ideal.
  • Edit the .htaccess files to cater to FastCGI setups.

There are two places to edit the contents of the .htaccess files.

  • For Backlight installations with Pages, you'll need to edit the .htaccess file at the top of your site. The file is annotated with the lines you'll need to change for FastCGI. The edits consist of disabling two lines by adding # to the beginning, and enabling one other line by removing a leading #.

  • For albums and album sets, the .htaccess file is controlled via a Backlight setting. To update this setting:

    • Log into Backlight
    • Click on the Backlight then Settings menu
    • Scroll to the bottom of the page, and click on Show Advanced Settings
    • Click on Edit Settings
    • Edit the contents of the Album .htaccess field
    • Click Save Settings
    • Click on the Backlight then Publisher menu
    • Click on Update Album Files
    • Click Update

.htaccess files are causing your site to fail completely

Some hosts may disallow .htaccess files or certain directives within the files. Fixing this is beyond the scope of this article. One option is to locate your Apache error file and determine the underlying error. This file may be found via FTP, or via your cPanel.

As stated above, Backlight is designed to work without .htaccess files, albeit without clean URLs in certain locations. As such, removing or renaming the .htaccess file at the top of your site, and following the preceding steps for updating Album .htaccess files so that the field is empty, should solve any issues with .htaccess files.