Using advanced help

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.

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

[about-php]
title = About PHP
file = 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 (inside the square brackets, and some settings for them. See: Advanced help .ini file format for a list of defined settings.

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

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

This produces 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:

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

<a href="&topic:module/topic&">topic</a>

This format will ensure the popup status remains consistent when switching between links.

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 latter is to refer to a translated version of the image if 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>

NOTE: In previous versions Advanced help did not require the &'s to be wrapped around topic:, path, and base_url. This is currently still supported, but may be removed in a future version. By adding the &'s these tokens are now not limited to href="" and src="" parameters.

Access control

When this module is installed, users with the view advanced help index permission can access the advanced help index by going to Administer → Advanced Help (admin/advanced_help). Additional permissions view advanced help topic and view advanced help popup enable users to access the actual help pages and popups.

The help texts are stored as plain .html-files and can, unless protected, be accessed by anyone who knows their URL. To protect them, place the following four lines in a file named .htaccess in project's help directory:

<Files *\.html>
Order Allow,Deny
Deny from all
</Files>

It as the responsibility of the project author to make sure this type of protection is in place if the project's author has help files that merits protection from direct access.

See also this tracker in the project's issue queue: #1980936 Typing complete path to .html help files in module bypasses user permissions.

Search

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 Administration → Reports → Status report and click the link “run cron manually”.