using-advanced-help.html 4.73 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
<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 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.</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');
gisle's avatar
gisle committed
49
$output .= '&nbsp;' . t('Click the help icon!');
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
</pre>
-->

<!-- D7 -->
<pre>
$output = theme('advanced_help_topic', array(
  'module' => 'help_example',
  'topic' => 'about-php',
));
$output .= '&nbsp;' . t('Click the help icon!');
</pre>

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

<pre>
&lt;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"&gt;
&lt;span&gt;Help&lt;/span&gt;
&lt;/a&gt;
 Click the help icon!
&lt;/div&gt;
</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>
&lt;a href="&amp;topic:module/topic&amp;"&gt;topic&lt;/a&gt;
</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>
&lt;img src="&amp;path&amp;example.png"/&gt;
&lt;img src="&amp;trans_path&amp;example.png"/&gt;
</pre>

<p>The latter is to refer to a translated version of the image if it differs from the original.</p>

<p>To reference any normal path in the site, use:</p>
<pre>
&lt;a href="&amp;base_url&amp;admin/settings/site-configuration"&gt;anchor text&lt;/a&gt;
</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 may be removed in a future
version.  By adding the &amp;'s these tokens are now not limited
to <code>href=""</code> and <code>src=""</code> parameters.</p>
109

110
111
112
113
114
115
116
117
118
119
120
<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>

121
122
123
124
<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>
125

126
<pre>
127
128
129
130
&lt;Files *\.html&gt;
Order Allow,Deny
Deny from all
&lt;/Files&gt;
131
132
</pre>

133
134
135
<p>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.</p>
136

137
138
<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>
139

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

142
143
144
145
146
<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>