The Advanced help module provides a framework that allows module and theme developers integrate help texts in a Drupal site.

It provides a framework for creating and maintaing HTML help texts. It may also be used to display a module's or theme's README-file on the screen.

Enabling the module

When you enable the module, a new tab with the legend “Advanced help” will show up under “Help”:

ahelp_tab.png
Advanced help is found under a separate tab

Links to the help texts are under this tab.

Creating 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:

[advanced help settings]
navigation = FALSE
show readme = FALSE

[about-example]
title = About the help example
weight = -11

[lorem]
title = Lorem ipsum
weight = -10

[etiam]
title = Etiam ultricies
parent = lorem
line break = TRUE

This file defines some global settings as well as three help topics (inside the square brackets), and some settings for them. See: “Advanced help .ini file format” for the full list of settings.

Characters ?{}|&~!()^" should not be used anywhere in the title as they have a special meaning, unless the the string is quoted. An error message like the one below indicates that quotes should be used:

Warning: syntax error, unexpected '(' in example.help.ini …

Linking to help

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, there is a theme function theme_advanced_help_topic() accepting three named parameters passed in an array:

  1. 'module': The machine name of the module that owns this help topic.
  2. 'topic': The identifier for the topic.
  3. 'type': The type of link to create:

The following example shows how to link to a popup with the topic 'about-example' owned by the module 'help_example' using the question mark icon:

// Create the question mark icon.
$output = theme('advanced_help_topic', array(
  'module' => 'help_example',
  'topic' => 'about-example',
  'type' => 'icon',
));
// Append some explanatory text.
$output .= ' ' . t('Click the help icon!');

This produces the following output:

<a class="advanced-help-link" title="About the help example"
  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-example?popup=1">
<span>Help</span>
</a>
 Click the help icon!
</div>

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

clickable icon
Question mark help icon

You may link to other help topics inside your HTML help file using this format:

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

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 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 will be removed in a future version. By adding the &'s these tokens are now not limited to href="" and src="" parameters.

Hiding help files

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 allows the user to click trough to the actual help pages and popups.

By taking away thes permissions from a role, a site can “hide” the direct access to these topics and popup. Note that this does not restrict access, as the contents of an unprotected HTML-file on a Drupal website can be viewed by anyone who know (or is able to guess) its URL.

To protect these files, 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 site manager to make sure this type of protection is in place if the site 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.

To enable advanced help search, navigate to Administration » Configuration » Search and metadata » Search settings. Scroll down to Active search modules and tick the box to the left of “Advanced 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 Administration » Reports » Status report and click the link “run cron manually”.