Managing 404 errors in SPIP

Since [Spip 1.8], it has become quite simple to create a template to manage the 404 errors that a site visitor encounters if they requested a page that does not exist.

What is that, a 404 error page?

Whenever someone surfs on the Internet, it can often arise that the web page does not exist, or has ceased existing. Whenever a web server receives a request to supply that page, it can proceed in one of two fashions:

  • either it returns a 404 error message — the number 404 having been previously assigned to this type of error [1] — to inform the user that the requested page does not exist
  • or it returns a specific "404" page defined by the site owner which usually contains a message that explains the error in terms considerably more humane than the default "404 Error has occurred" page.

So what’s that got to do with SPIP ?

In the same manner, it can easily happen that a site visitor requests a page that actually appears to be a valid request, but, for lack of appropriate data, doesn’t deliver any content. Taking a concrete example in SPIP, if a site visitor types into their browser an address like http://spip-website-address/spip.php?article520, and this article 520 doesn’t exist yet — or is simply not published online yet —, it makes sense that SPIP returns a useful message back to the site visitor similar to that described above. For our purposes, we’ll call this a "pseudo 404 error".

And that’s effectively what SPIP does. SPIP returns a 404 error page built from a regular SPIP template(squelette). In order to personalise this for your own site, you need only create your own 404.html file, in the same manner and same location as any other SPIP template file (for more information, refer to this article "Where do I put the template files for my site?").

Implementation in SPIP

But SPIP can’t know without instruction when it should return this "pseudo 404 error" page, so it needs to be explicitly referenced in each template file that might cause such an error (articles, sections, news, etc.).

By convention, SPIP will return the 404 errors page only when the content returned by the template is completely empty.

The principle is simple enough, for example:

  • the search template, if it finds no matching results, will display the search page bit with a message telling the user that the search failed to find matching results. But this is one of the "normal" behaviours resulting from a search, and does not constitute one of our "pseudo 404 errors".
  • on the other hand, an article template, if requested for an article number that does not exist, should not display such an empty page, but should display the "pseudo 404 error" page.

Taking our previous example of an unpublished or non-existing article 520, the article template should be built in the following manner:

<BOUCLE_main(ARTICLES) {id_article}>
HTML code for normal display of an article, including the HTML headers

The _main loop won’t return anything at all for a non-existing or unpublished article, the template will return an empty page, and SPIP will pick this up and return instead the contents of the page generated by our "pseudo 404 error" template automatically. Even though we haven’t actually typed anything pointing to the 404 page, we have caused our template to return empty, which for SPIP constitutes an explicit request for 404 treatment. It’s critical to note that any code outside of that _main loop may still return code if the article does not exist - this would not return an empty page, and SPIP would not automatically take control and divert to the "pseudo 404 error" page - moral of the story: keep your headers inside your loop.

Web server parameters

This following procedure is necessary for "normal" 404 error pages, that is, errors due to the absence of files requested by the user.

Beyond a doubt, the simplest method is to make use of the .htaccess file supplied with SPIP, even is you don’t make use of "clean" URLs. To do this, simple rename the htaccess.txt file delivered in the standard distribution to .htacesss. [2]. And that’s all there is to it ! [3]

Note!: it may happen that your ISP has deactivated the use of the .htaccess file, in which you case you will need to contact them directly to resolve the problem.

Generating a page that is genuinely empty

It may be the case that you want to return an empty page without provoking one of these "pseudo 404 errors". To do this, since SPIP 1.9, all you need to do is output


[1In reality it is an HTTP protocol code

[2It’s possible that you won’t be able to name a file as such on your personal computer. In such cases, rename it first as htacces.txt and then rename it to .htaccess once you have put it on line.

[3There are considerably more detailed operations you can perform to process 404 errors. Signalling to a webcrawler that the requested page is invalid and should not be indexed, and reusing your site map are two items mentioned in this contribution: Clean processing of 404 errorsarticle in French only

Author Mark Published : Updated : 26/10/12

Translations : català, English, Español, français, italiano, Nederlands