Warning message

Documentation is currently being migrated into the new system. Some pages might be temporarily missing, and some guides might appear empty. Thank you for your patience while we are improving Drupal.org documentation.

Theming the Drupal maintenance page

Last updated on
September 8, 2016 - 13:42

What is the maintenance page?

The maintenance page is used when the site is set in off-line mode or the site is inoperable due to technical problems, such as a database failure. You can enable this mode from "Administer > Site configuration > Site maintenance". This mode will also trigger during a database failure. By default, the core theme Minnelli is used in this mode even if another theme is selected. However, you might like to include a maintenance page from within your own site.

Overriding template files in Drupal

Creating a custom theme in Drupal is a practice of overriding existing template (.tpl.php) files. You can find template files included with the core distribution and you can either copy these files into your theme folder, or create new files with the same name. Drupal will first choose your theme's template files before the core ones. In this way, you can override the default templates. For example, there is a maintenance-page--offline.tpl.php file which exists in Drupal core, that you can duplicate into your own theme.

Sometimes you can use template suggestions, which means example files don't exist with Drupal, but if you include a file with the suggested name, Drupal will pick it up. For example maintenance-page.tpl.php doesn't exist in core, but you can create a file with that name and Drupal will recognize it.

In this case there are two maintenance page files that you can create. You can duplicate your theme's page.tpl.php twice and name them:

  1. maintenance-page.tpl.php: This file controls the page that is displayed when the site is in "maintenance mode" but the database connection and database are still functioning correctly.
  2. maintenance-page--offline.tpl.php: This file controls the page that is displayed when Drupal cannot access the database (for whatever reason).

Step 1: Override the maintenance page template

Copy your main page.tpl.php and rename it to maintenance-page.tpl.php or copy the template located in modules/system/maintenance-page.tpl.php to your theme and edit so it matches the rest of your site.

Step 2: Indicate in your settings.php file

In the case of a database failure, your maintenance page setting must be indicated in configuration files so this can operate without access to the database. Specify your maintenance page in your settings.php file, which is usually located at sites/default or sites/yourdomain.com (if you are on a multi-site installation).

Option 1

In the settings.php file, enable the $conf variable with the internal name of your theme:

  $conf['maintenance_theme'] = 'themeName';

Option 2

In the settings.php file, numerous configurations are disabled with a # (hash) symbol at the start of the line. You can remove the # symbol at the start of the line to uncomment and enable that configuration.

Therefore, instead of adding the line as in Option 1 above to the settings.php file, you can also uncomment the relevant lines in settings.php. In that case, you have to uncomment 3 separate lines:

  • The array declaration (# $conf = array()
  • The maintenance theme setting (# 'maintenance_theme' => 'minnelli',)
  • The closing parenthesis (# );)

Verify the changes by setting the site into off-line mode then log out.

To account for database failures, try turning off your database. Any function call that depends on the database should be checked first with db_is_active. The variable $db_is_active can also be used from the template.

As an alternative to disabling your database, force a database connection failure. Examples for both methods can be found here.

Step 3: Create the maintenance offline page in the case of database failure

To prevent warnings about the database connection from appearing, copy your page.tpl.php file and rename it maintenance-page--offline.tpl.php. Change the $content variable with your custom message. Note, this template file is a template suggestion based on maintenance-page.tpl.php so they both need to exist in the same folder.

At the top of maintenance-page--offline.tpl.php, you might also want to set the following variables detailed in step 4.

Step 4: Hard code site settings

In this mode, your database is inaccessible, therefore some key settings about your site are not available. If you want this page to use the same theme and other settings that the site would normally use, you must replicate those settings by using hard-coded values.

Copy these variables into the maintenance-page--offline.tpl.php file:

  • $head_title - the value used in the HTML <title> tag. Defaults to "Site off-line | Drupal"
  • $site_name - the value used in the page's <h1> tag. Defaults to "Drupal". If "Site name" is turned off in your theme configuration, then you'll want to clear this variable (see example below).
  • $logo - if you're using a custom logo override in the theme settings. Use the full path of the custom logo, relative to the base directory of the Drupal installation. If you used the standard override upload function in the theme configuration for your custom logo, your logo will be stored in sites/all/files/ (see example below).
  • $site_slogan - your site's slogan. If "Site slogan" is turned off in your theme configuration but you still have a site slogan defined in Site Information, then you'll want to clear this variable (see example below).

Example additions at the top of maintenance-page--offline.tpl.php:

  $head_title = 'mysite.com :: Site-offline';
  $logo = 'sites/all/files/customLogo.png';

  // If your theme is set to display the site name, uncomment this line and replace the value:
  // $site_name = 'Your Site Name';

  // If your theme is set to *not* display the site name, uncomment this line:
  unset($site_name);

  // If your theme is set to display the site slogan, uncomment this line and replace the value:
  $site_slogan = 'My Site Slogan';

  // If your theme is set to *not* display the site slogan, uncomment this line:
  // unset($site_slogan);

  // Main message. Note HTML markup.
  $content = '

The site is currently not available due to technical problems. Please try again later. Thank you for your understanding.


If you are the maintainer of this site, please check your database settings.

';

A maintenance.css file is included in this mode. It is located in modules/system/maintenance.css. You can override this file with the instructions provided in the style sheets section.

Notes:

  • The initial install and updating of your site depends on the core themes, Minnelli and Garland. It cannot be changed for these modes.
  • The theme registry is not cached when set to off-line mode.
  • Ensure that the theme used as maintenance theme is enabled (Administer > Site building > Themes).