Club Drupal

<p>The <strong>Advanced help</strong> module provides a framework that

allows module and theme developers integrate help texts in a Drupal

site.  Although the <strong>Advanced help</strong> 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.</p>

<p>Modules and themes utilizing <strong>Advanced help</strong> should

create a subdirectory named <code>help</code> inside their own main

directory. Place the file

<em>MODULENAME</em>.help.ini (resp. <em>THEMENAME</em>.help.ini) in this subdirectory.

formatted similar to the following example:</p>

<pre>

[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

</pre>

<p>This file defines five help topics (inside the square brackets), and

some settings for them.

See: <a href="&topic:advanced_help/ini-file&">Advanced help .ini file format</a> for

a list of defined settings.</p>

<p>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:</p>

<!-- D6

<pre>

$output = theme('advanced_help_topic', 'help_example', 'about-php');

$output .= ' ' . t('Click the help icon!');

</pre>

-->

<!-- D7 -->

<pre>

$output = theme('advanced_help_topic', array(

  'module' => 'help_example',

  'topic' => 'about-php',

));

$output .= ' ' . t('Click the help icon!');

</pre>

<p>This produces the following output:</p>

<pre>

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

</pre>

<p>This produces a clickable help icon like the one shown below:</p>

<div class="ta-center">

<img class="help-img-center" alt="clickable icon" src="&path&click_icon.png" width="180" height="90" border="0" />

</div>

<p>Inside your help file, you may link to other help topics using this format:</p>

<pre>

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

</pre>

<p>This format will ensure the popup status remains consistent when

switching between links.</p>

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

<pre>

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

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

</pre>

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

<p>To reference any normal path in the site, use:</p>

<pre>

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

</pre>

<p><strong>NOTE: </strong> In previous versions <strong>Advanced

help</strong> did not require the &amp;'s to be wrapped around

<code>topic</code>, <code>path</code>, and <code>base_url</code>.

This is currently still supported, but will be removed in a future

version.  By adding the &'s these tokens are now not limited

to <code>href=""</code> and <code>src=""</code> parameters.</p>

<h2 id="access-control">Access control</h2>

<p>When this module is installed, users with the

<code>view advanced help index</code>

permission can access the advanced help index by going to

<em>Administer &rarr; Advanced Help</em>

(<code>admin/advanced_help</code>). Additional permissions

<code>view advanced help topic</code>  and

<code>view advanced help popup</code>

enable users to access the actual help pages and popups.</p>

<p>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

<code>.htaccess</code> in project's <code>help</code> directory:</p>

<pre>

<Files *\.html>

Order Allow,Deny

Deny from all

</Files>

</pre>

<p>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.</p>

<p>See also this tracker in the project's issue queue:  

<a href="https://www.drupal.org/node/1980936">#1980936 Typing complete path to .html help files in module bypasses user permissions</a>.</p>

<h2 id="search">Search</h2>

<p>To enable advanced help search, navigate to

<em>Administration → Configuration → Search and metadata → Search settings</em>.

Scroll down to <em>Active search modules</em> and tick the box to the

left of “Advanced help”.  The search form will appear on the top of

the advanced help index pages.</p>

<p>If the core <strong>Search</strong> 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 <em>Administration → Reports → Status report</em> and

click the link “run cron manually”.</p>