Custom Error Pages

A generic plugin for OJS 3.3.0-x that replaces OJS' bare 404 Not Found message with a page rendered in the active theme, with the theme's own header, footer and navigation. It needs no core changes and works with any theme.

What it does

OJS answers a missing page with Dispatcher::handle404(), which prints <h1>404 Not Found</h1> and stops, bypassing the theme. This plugin serves a themed page with a real 404 status in these cases:

• an unknown page or a mistyped operation (/journal/nosuchpage, /journal/about/editorailTeam)
• a valid operation whose data is gone (/journal/article/view/<deleted-id>)
• a missing issue (/journal/issue/view/<bad-id>, /issue/download/...). OJS would otherwise redirect to the login page.
• an unknown journal path (/index.php/nosuchjournal). This page is rendered in the site's theme.

When the article or issue exists but the requested file does not, the page says File not found and links back to that article or issue instead of the home page. The article case covers a missing galley and a galley file that is gone from disk. When the request will be shown inside a frame (?inline=…, which the HTML galley viewer uses, or Sec-Fetch-Dest: iframe), a small standalone box is sent instead of the full themed page. An issue galley whose file is missing from disk gets an empty 200 response from OJS itself; the plugin answers 404 + File not found instead. An unknown issue galley id still redirects to the issue, as in OJS.

Valid pages, the REST API, component requests, redirects and file downloads are left untouched. The error page is sent with Cache-Control: no-store.

Screenshots

The 404 page in OJS' default theme:

A missing galley file requested for a frame (?inline=…) gets a standalone box without the theme's header and footer:

The screenshots live in the repository only; they are not part of the release package.

Installation

Either of these works:

• Upload: Settings → Website → Plugins → Upload a new plugin, then choose customErrorPages-<version>.tar.gz.
• File copy: extract the archive into plugins/generic/customErrorPages, open Settings → Website → Plugins once (OJS registers the plugin when that list loads), then enable Custom Error Pages.

Enable the plugin in each journal where you want the themed page. Unknown journal paths get the themed page as long as the plugin is enabled in at least one journal.

Upgrading from 1.3.x or 1.4.0.0 (folder customerrorpages)

From 1.4.1.0 the plugin lives in plugins/generic/customErrorPages, following PKP's folder naming. OJS cannot upgrade a plugin across a folder rename (the plugin manager's Upgrade reports a wrong plugin name), so replace it instead:

1. Settings → Website → Plugins → Custom Error Pages → Delete. This removes the old customerrorpages folder and marks its version as no longer current.
2. Upload a new plugin and choose customErrorPages-<version>.tar.gz.

Do the steps in this order. While both folders exist, the plugin list loads both, and both declare the same PHP class.

Settings and the per-journal enabled state are kept: OJS stores them under the plugin's class name, which has not changed. After step 2 the plugin is active again in every journal where it was enabled.

Upload a release newer than the installed one (1.4.1.0 or later over 1.4.0.0). OJS matches version rows without regard to letter case; re-uploading the same version number would reactivate the old customerrorpages row, and on a case-sensitive file system (Linux) the plugin would then not load.

Upgrading from 1.1.x (themederror)

Versions up to 1.1.x lived in plugins/generic/themederror. Delete that folder, install this plugin as above, and enable it again in each journal. The old settings are not carried over.

Settings

Open Plugins → Custom Error Pages → Settings:

• Background
  • Accent colour only (default): the theme's flat colour. This is the lightest option.
  • Background image: shows the image shipped at images/404-bg.webp, or the URL below.
• Background image URL (optional): a full http:// or https:// URL of at most 255 characters. It takes precedence over the shipped image. Quotes, parentheses, backslashes and whitespace are rejected.

To use a different shipped image, replace images/404-bg.webp. A .webp, .jpg, .jpeg or .png file named 404-bg is also picked up, in that order. Delete the file to fall back to the flat colour.

On Apache, images/.htaccess gives the image a one-year cache lifetime. The image URL includes ?v=<file mtime>, so replacing the file updates it for visitors. On other web servers, add an equivalent rule if you want it cached.

Theming

The page body uses plain classes (.error-hero, .error-hero-inner, .error-card, .error-title, .error-msg, .error-back). A small inline stylesheet centres it on any theme. A theme can restyle it with a more specific selector, for example body.mytheme .error-hero { … }.

Notes

• show_stacktrace: when [debug] show_stacktrace = On in config.inc.php, OJS appends a stack trace to its 404 output. The plugin then leaves that response as it is, so a deleted article or an unknown journal path shows OJS' own page. Unknown pages, mistyped operations and missing issues are still themed.
• Large downloads and output_buffering: OJS streams article galleys with fpassthru(), which PHP passes to the output layer as a single write. When PHP's own output_buffering is enabled in php.ini, a large article download therefore uses as much memory as the file size, whether or not this plugin is installed. This is PHP and OJS behaviour. The plugin itself steps out of the way of every download.
• HTML galleys: the HTML Article Galley plugin reads the galley file itself, before OJS checks that it exists, and fails with an uncaught exception (HTTP 500) when the file is missing. The plugin runs the same existence check first, so a missing HTML galley file gets a 404 File not found instead.
• PDF viewer: the PDF.js viewer fetches the PDF itself, so a missing PDF shows PDF.js' own error message inside the viewer, not this plugin's page.
• Deleted journals: the plugin caches whether it is enabled in any journal. Deleting a journal does not update that cache until the plugin is next enabled or disabled somewhere, so site-level unknown URLs may stay themed until then.

Requirements

• OJS 3.3.0-x
• PHP 7.3 or later (tested on 7.4, 8.0, 8.1 and 8.2)

Licence

GNU General Public License v3. See LICENSE.

© OJS Services — info@ojs-services.com