The Advanced Help module provides a framework that allows module and theme developers integrate help texts in a Drupal site. Although the Advanced Help does not provide general help by itself, it provides a powerful and easy framework that modules and themes may use to provide their own help.

Enabling the module

To enable the module navigate to Manage » Extend and check the box next to “Advanced Help”, the press “Install”.

After you have enabled the module, a new tab with the legend “Advanced help” will show up alongside with “Help” when you navigate to Manage » Help. Select that to see the list of help topics available.

Creating help

Modules and themes utilizing Advanced Help should create a subdirectory named help inside their own main directory. Place the file MODULENAME.help.yml (resp. THEMENAME.help.yml) in this subdirectory. formatted similar to the following example:

about-php:
  title: 'About PHP'
  weight = -10
history:
  title: 'History of PHP'
  parent: about-php
usage:
  title: 'Usage of PHP'
  weight: 1
security:
  title: 'Security of PHP'
  weight: 2
syntax:
  title: PHP syntax
  parent: usage

This file defines five help topics (the lines that are not indented), and some settings for them. See: Advanced Help .help.yml file format for a list of defined settings.

Linking to help

All topics are addressed by the module or theme providing the topic, and by the topic id. For Drupal 7, one could use the a format similar to the following example to produce a themed link to popup about a topic:

$output = theme('advanced_help_topic', array(
  'module' => 'help_example',
  'topic' => 'about-php',
));
$output .= ' ' . t('Click the help icon!');

This produced the following output:

<a class="advanced-help-link" title="About PHP"
  onclick="var w=window.open(this.href, 'advanced_help_window',
  'width=500,height=500,scrollbars,resizable');
  w.focus(); return false;"
  href="/help/help_example/about-php?popup=1">
<span>Help</span>
</a>
 Click the help icon!
</div>

This produces a clickable help icon like the one shown below:

NOTE: In Drupal 9, the function theme() is deprecated. A valid example for Drupal 9 has to be created.

Inside your help file, you may link to other help topics using this format:

<a href="&topic:moduleshortname/moduletopic&">anchortext</a>
<a href="&topic:help_example/lorem&">Lorem ipsum</a>

The second line show how to link to a help page provided by the module with shortname help_example, with the topic lorem.

To reference items within the help directory, such as images you wish to embed within the help text, use:

<img src="&path&example.png"/>
<img src="&trans_path&example.png"/>

The trans_path keyword refers to a translated version of the image in the translation directory and may be used it differs from the original.

To reference any normal path in the site, use:

<a href="&base_url&admin/settings/site-configuration">anchor text</a>

Search

Note: This fearure is currently only available for Drupal 7. It need to be reimplemented for Drupal 9/10.

To enable advanced help search, navigate to Manage » Configuration » Search and metadata » Search pages. Scroll down to Search pages and choose “Advanced Help” from the pull-down menu. Click “Add search page”. Addd path and click “Save help”. The search form will appear on the top of the advanced help index pages.

If the core Search module is enabled, the contents of the advanced help framework will be indexed on cron. If you enable new modules or themes and wish to immediately index their help text, navigate to Manage » Configuration » System » Cron and click the button “Run cron”.