Customizing site off-line/maintenance page

May you never come face to face with this:



This is the page Drupal will throw up if something is wrong with the database. The root cause of the problem is displayed at the bottom of the screen if "display_errors = On' is set in php.ini. But it's suggested in php.ini that this should be "Off" for production site. So you may not see what the cause of the problem is. There are a few things not so good with this page:

1. The site name got changed to "Drupal", not your name.
2. The site logo and favicon are the Drupal versions.
3. Finally, the site is in the minnelli look

The good news is this page is fully customizable and I'll show the ins-and-outs about this here. This page is configured by a few Drupal variables. Normally, these variables are stored in the database. But there are two different causes of this off-line page: 1) when the database is down, 2) when the Admin place the site off-line mode. When the database is down, the only place to set variables is the $conf[] array variable in the settings.php file so we will make our setting there. The off-line page is controlled by the 'maintenance_theme' variable. Drupal looks for the maintenance-page.tpl.php template file in this theme to render this special page. Site name, logo and favicon are normally set through the theme's admin page and the values are stored in the database. For the off-line page to work, we need these values available even when database is down. So we must instead set them in settings.php. Keep in mind the values in settings.php override values set with the admin screen. Here is the settings.php code to setup maintenance theme and site name:

$conf = array(
  'maintenance_theme' => 'foliage',  
  'site_name' => 'My Extra Spiffy Site',
);

The off-line page now looks like this:



Now the page is in the Foliage look. But the styling is broken: the header and page content is not centered. This is due to the fact that the foliage theme does not provide a maintenance-page.tpl.php template file. So Drupal falls back to the system version and that does not play nice with the foliage stylesheet. If your theme doesn't have the maintenance-page.tpl.php template file, try copy the page.tpl.php to maintenance-page.tpl.php. The logo and favicon are not set yet: they are the theme's default. It a little bit tricky to make this change. By default, when the database is down, the fallback is the 'logo.png' and 'favicon.ico' files in the theme if those files exist. However, there is a trick way to override this in settings.php:

$conf = array(
  'site_name' => 'My Extra Spiffy Site',
  'maintenance_theme' => 'chameleon',
  'theme_settings' => array(
    'toggle_favicon' => FALSE,
    'favicon' => '/sites/www.mysite.com/files/favicon.ico',
    'toggle_logo' => FALSE,
    'logo' => '/sites/www.mysite.com/files/logo.png',
  ),  
);

the page now:


It's in the chameleon look (well, not really but let's pretend it's for now and I'll explain what it really is later), and the site name is correct, the logo is custom. Setting 'toggle_logo' and 'toggle_favicon' to FALSE by-passes Drupal's normal code, making the settings.php value to be used unconditionally. Now only the value in settings.php is in effect, by-passing the logic in theme.inc theme_get_setting() This only effects the off-line page:

function theme_get_setting($setting_name, $refresh = FALSE) {
  ...

    if ($settings['toggle_logo']) {
      if ($settings['default_logo']) {
        $settings['logo'] = base_path() . dirname($theme_object->filename) .'/logo.png';
      }
      elseif ($settings['logo_path']) {
        $settings['logo'] = base_path() . $settings['logo_path'];
      }
    }

    if ($settings['toggle_favicon']) {
      if ($settings['default_favicon']) {
        if (file_exists($favicon = dirname($theme_object->filename) .'/favicon.ico')) {
          $settings['favicon'] = base_path() . $favicon;
        }
        else {
          $settings['favicon'] = base_path() .'misc/favicon.ico';
        }
      }
      elseif ($settings['favicon_path']) {
        $settings['favicon'] = base_path() . $settings['favicon_path'];
      }
      else {
        $settings['toggle_favicon'] = FALSE;
      }
    }
  }

  return isset($settings[$setting_name]) ? $settings[$setting_name] : NULL;
}

Note that I use the theme_settings key, and not the theme_THE-THEME-ID_settings key. This is so that even in case the maintenance_theme is the same as your normal theme, you can use the theme specific settings page to set the logo and shortcut icon flag to true for normal operation. The theme system work differently in site off-line page. The normal theme registry is by passed. During off-line page theming, a special _theme_load_offline_registry() function build a new theme registry in memory and the file theme.maintenance.inc is only include'd when this path is taken. This special logic is broken if the theme system is initialized in hook_init() phase of bootstrap. Some modules do make this mistake causing the maintenance theme registry not built from scratch in memory and the database pre-cached version is used. The theme hook 'maintenance_page' in the pre-cached theme registry does not have the template_preprocess_maintenance_page(). That's because when that version of the registry is built, the file theme.maintenance.inc is not include'd. This result in blank looking off-line page because the template_preprocess_maintenance_page() is not in the normal theme registry so that function is not called to define the necessary variables. See http://drupal.org/node/374645#comment-1261689. Things the can cause the theme system initialized include calling any of these function: theme(), drupal_get_form(). So avoid calling these in hook_init(). One thing to be aware of is Drupal assumes the off-line page theme is a phptemplate engine base theme. The definition of the maintenance_page theme hook is in common.inc drupal_common_theme():

    'maintenance_page' => array(
      'arguments' => array('content' => NULL, 'show_blocks' => TRUE, 'show_messages' => TRUE),
      'template' => 'maintenance-page',
    ),

The system.module declares it in its hook_theme():

function system_theme() {
  return array_merge(drupal_common_theme(), array(
  ....

so the system module defines a theme hook 'maintenance_page' and it's a template hook and the template file base name is 'maintenance-page'. The default version is found inside system module directory. Phptemplate based themes can override this by having their own mainenance-page.tpl.php template file inside their own directory. During theme registry build, the phptemplate engine work its magic and incorporate the override template if one is defined in the theme. Non-phptemplate engine based theme do not have this kind of power. So for themes like Chameleon which is a pure php theme that doesn't not use any theme engine, there is no override template logic. So what actually happen is the version in modules/system is used. So earlier when we set the maintenance_theme = "chameleon", what we got is really the system module's maintenance-page.tpl.php rendered. That's why I said "let's pretend". The last act of the template_preprocess_maintenance_page() in theme.maintenance.inc is this:

  // Dead databases will show error messages so supplying this template will
  // allow themers to override the page and the content completely.
  if (isset($variables['db_is_active']) && !$variables['db_is_active']) {
    $variables['template_file'] = 'maintenance-page-offline';
  }

as the comment in the code clear explains, this is to allow an alternate template file called 'maintenance-page-offline' to be used when the database is dead if one exist. If not, then the usual maintenance-page.tpl.php is used. A few things theme needed to make sure to operate in off-line mode:

1. Must not access database for normal page render, avoid calling variable_set() anywhere such as template.php or in template files. It's probably good practice theme in general because themes are for presentation so they should only use data provided to them through variables. Some theme violates this and they cannot be used for off-line page.

2. Provide 'maintenance-page.tpl.php' and 'maintenance-page-offline.tpl.php' file tailored to the theme. The version in system module may not work with the theme's stylesheet as seen above for the Foliage theme.

   The samples in system and Garland is probably not the best example for regular maintenance theme duty. They are very complicated, supporting left, right blocks in addition to header, content and footer. The reason for such complexity is because this template also serves another duty: it is used during Drupal install and the install needs block support. For normal themes, it's probably enough to just render header, content and footer in their maintenance-page.tpl.php template.

3. Test the off-line page for both database down and site off-line conditions.

PS: Here is the page in drupal.org about theming maintenance page: http://drupal.org/node/195435

附加檔案	大小
Site off-line page theme.ppt	1.83 MB