Advanced help

by Gisle Hannemyr

The Advanced help module allows module developers to store and manage their help texts as plain html-files outside the module system.

Table of contents

Drupal projects discussed in this chapter: Advanced help.

Introduction

Drupal expects module developers to provide integrated help by implementing hook_help() as part of the module. However, for longer help, it is more convient to provide this is the form of plain html-files. This module implements a framework for doing that.

The module also supports multi-lingual sites. The help-files can be easily made aviailable in alternative languages simply by copying them into the right translations directory and translating them.

In addition to ordinary help pages, pages, popups with help texts can be added to any form or page. Access to Help text can appear in an ordinary web popup or a popup. y taking away access to view the popups, a site can force the popups to not exist.

Installing and enabling the module

[TBA]

Creating help files

[TBA]

[users]
title = Topic title
weight = 2

Calling the theme function with the hook advanced_help_topic will create markup that, when inserted in a page, will display a question mark to the left of text. Here is a typical call:

$popupanchor = theme('advanced_help_topic', array(
  'module' => 'module',
  'topic' => 'helpfile',
));

The module is the name of the module that has the help text file inside its help/ directory. The topic is also the file name, without the .html extension.

The following markup is produced. Given the code snipped above, it will be stored in $popupanchor.

<a href="/help/module/helpfile?popup=1"
  class="advanced-help-link"
  onclick="var
    w=window.open(this.href,
      'advanced_help_window',
      'width=500,height=500,scrollbars,resizable');
    w.focus();
    return false;"
  title="Topic title"><span>Help</span></a>

The example below is from the Views module. It provides pop-up help for some form elements:

if (module_exists('advanced_help')) {
  $title = theme('advanced_help_topic', array(
    'module' => 'views',
    'topic' => $form_state['help_topic']
  )) . $title;
}

Below is a another example. It provides pop-up help about a particular form element:

$form['formelement'] = array(
  '#type' => 'select',
  '#title' => t('Form element'),
  '#default_value' => $this->options['formelement'],
  '#options' => $sort_options,
  '#description' => theme('advanced_help_topic', array(
    'module' => 'module',
    'topic' => 'helpfile',
  )) . t('Some text about this form element.'),
);

Final word

[TBA]

Last update: 2014-04-26 for D7 [gh].