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', array( 'module' => 'help_example', 'topic' => '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:
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
This is currently still supported, but may be removed in a future
version. By adding the &'s these tokens are now not limited
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
<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.
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”.