+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:
++<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 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> ++ +
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.
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 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â.