1
|
<p>The <strong>Advanced Help</strong> module provides a framework that
|
2
|
allows module and theme developers integrate help texts in a Drupal
|
3
|
site.</p>
|
4
|
|
5
|
<p>It provides a framework for creating and maintaing HTML help texts.
|
6
|
It may also be used to display a module's or
|
7
|
theme's <code>README</code>-file on the screen.</p>
|
8
|
|
9
|
<h2 id="ah_enable">Enabling the module</h2>
|
10
|
|
11
|
<p>When you enable the module, a new tab with the legend “Advanced
|
12
|
help” will show up under “Help”:
|
13
|
|
14
|
<div class="help-imgpos-center" style="max-width:661px">
|
15
|
<img class="help-img" alt="ahelp_tab.png" title="The “Advanced help” tab" src="&path&ahelp_tab.png" width="661" />
|
16
|
<div class="help-img-caption" style="max-width:661px">Advanced help is found under a separate tab</div>
|
17
|
</div>
|
18
|
|
19
|
<p>Links to the help texts are under this tab.</p>
|
20
|
|
21
|
<h2 id="ah_crehlp">Creating help</h2>
|
22
|
|
23
|
<p>Modules and themes utilizing <strong>Advanced Help</strong> should
|
24
|
create a subdirectory named <code>help</code> inside their own main
|
25
|
directory. Place the file
|
26
|
<em>MODULENAME</em>.help.ini (resp. <em>THEMENAME</em>.help.ini) in this subdirectory.
|
27
|
formatted similar to the following example:</p>
|
28
|
|
29
|
<pre>
|
30
|
[advanced help settings]
|
31
|
navigation = FALSE
|
32
|
show readme = FALSE
|
33
|
|
34
|
[about-example]
|
35
|
title = About the help example
|
36
|
weight = -11
|
37
|
|
38
|
[lorem]
|
39
|
title = Lorem ipsum
|
40
|
weight = -10
|
41
|
|
42
|
[etiam]
|
43
|
title = Etiam ultricies
|
44
|
parent = lorem
|
45
|
line break = TRUE
|
46
|
</pre>
|
47
|
|
48
|
<p>This file defines some global settings as well as three help topics
|
49
|
(inside the square brackets), and some settings for them. See:
|
50
|
“<a href="&topic:advanced_help/ini-file&">Advanced help .ini file
|
51
|
format</a>” for the full list of settings.</p>
|
52
|
|
53
|
<p>Characters <code>?{}|&~!()^"</code> should not be used anywhere in
|
54
|
the title as they have a special meaning, unless the the string is
|
55
|
quoted. An error message like the one below indicates that quotes
|
56
|
should be used:</p>
|
57
|
|
58
|
<blockquote><p>Warning: syntax error, unexpected '(' in example.help.ini …</p></blockquote>
|
59
|
|
60
|
<h2 id="ah_lnkhlp">Linking to help</h2>
|
61
|
|
62
|
<p>All topics are addressed by the module or theme providing the
|
63
|
topic, and by the topic id. To produce a themed link to popup about a
|
64
|
topic, there is a theme
|
65
|
function <code>theme_advanced_help_topic()</code> accepting three
|
66
|
named parameters passed in an array:</p>
|
67
|
|
68
|
<ol>
|
69
|
<li><code>'module'</code>: The machine name of the module that owns this help topic.</li>
|
70
|
<li><code>'topic'</code>: The identifier for the topic (to link to topic) or <code>'toc'</code> (to link to index page).</li>
|
71
|
</ul></li>
|
72
|
<li><code>'type'</code>: The type of link to create:<ul>
|
73
|
<li>'<code>icon'</code> to display the question mark icon.</li>
|
74
|
<li>'<code>title'</code> to display the topic's title.</li>
|
75
|
<li>any other text to display the text. Wrap it in <code>t()</code> to make it translatable.</li>
|
76
|
</ul></li>
|
77
|
</ol>
|
78
|
|
79
|
<p>The following example shows how to link to a popup with the
|
80
|
topic <code>'about-example'</code> owned by the module
|
81
|
<code>'help_example'</code> using the question mark icon:</p>
|
82
|
|
83
|
|
84
|
<pre>
|
85
|
// Create the question mark icon.
|
86
|
$output = theme('advanced_help_topic', array(
|
87
|
'module' => 'help_example',
|
88
|
'topic' => 'about-example',
|
89
|
'type' => 'icon',
|
90
|
));
|
91
|
// Append some explanatory text.
|
92
|
$output .= ' ' . t('Click the help icon!');
|
93
|
</pre>
|
94
|
|
95
|
<p>This produces the following output:</p>
|
96
|
|
97
|
<pre>
|
98
|
<a class="advanced-help-link" title="About the help example"
|
99
|
onclick="var w=window.open(this.href, 'advanced_help_window',
|
100
|
'width=500,height=500,scrollbars,resizable');
|
101
|
w.focus(); return false;"
|
102
|
href="/help/help_example/about-example?popup=1">
|
103
|
<span>Help</span>
|
104
|
</a>
|
105
|
Click the help icon!
|
106
|
</div>
|
107
|
</pre>
|
108
|
|
109
|
<p>This produces a clickable help icon like the one shown below:</p>
|
110
|
|
111
|
<div class="help-imgpos-center" style="max-width:180px">
|
112
|
<img class="help-img" alt="clickable icon" title="The advanced help icon is a question mark" src="&path&click_icon.png" width="180" />
|
113
|
<div class="help-img-caption" style="max-width:180px">Question mark help icon</div>
|
114
|
</div>
|
115
|
|
116
|
<p>See the source code of demo module <strong>Advanced Help
|
117
|
Example</strong> for link examples.</p>
|
118
|
|
119
|
<p>You may link to other help topics inside your HTML help file using
|
120
|
this format:</p>
|
121
|
|
122
|
<pre>
|
123
|
<a href="&topic:moduleshortname/moduletopic&">anchortext</a>
|
124
|
<a href="&topic:help_example/lorem&">Lorem ipsum</a>
|
125
|
</pre>
|
126
|
|
127
|
<p>The second line show how to link to a help page provided by the
|
128
|
module with shortname <code>help_example</code>, with the
|
129
|
topic <code>lorem</code>.</p>
|
130
|
|
131
|
<p>To reference items within the help directory, such as images you wish to embed within the help text, use:</p>
|
132
|
|
133
|
<pre>
|
134
|
<img src="&path&example.png"/>
|
135
|
<img src="&trans_path&example.png"/>
|
136
|
</pre>
|
137
|
|
138
|
<p>The <code>trans_path</code> keyword refers to a translated version
|
139
|
of the image in the translation directory and may be used if it
|
140
|
differs from the original.</p>
|
141
|
|
142
|
<p>To reference any normal path in the site, use:</p>
|
143
|
<pre>
|
144
|
<a href="&base_url&admin/settings/site-configuration">anchor text</a>
|
145
|
</pre>
|
146
|
|
147
|
<p><strong>NOTE: </strong> In previous versions <strong>Advanced
|
148
|
help</strong> did not require the &'s to be wrapped around
|
149
|
<code>topic</code>, <code>path</code>, and <code>base_url</code>.
|
150
|
This is currently still supported, but will be removed in a future
|
151
|
version. By adding the &'s these tokens are now not limited
|
152
|
to <code>href=""</code> and <code>src=""</code> parameters.</p>
|
153
|
|
154
|
<h2 id="access-control">Hiding help files</h2>
|
155
|
|
156
|
<p>When this module is installed, users with the
|
157
|
<code>view advanced help index</code>
|
158
|
permission can access the advanced help index by navigating to
|
159
|
<span class="nav">Help » Advanced Help</span>.
|
160
|
Additional permissions
|
161
|
<code>view advanced help topic</code> and
|
162
|
<code>view advanced help popup</code> allows the user to click
|
163
|
trough to the actual help pages and popups.</p>
|
164
|
|
165
|
<p>By taking away these permissions from a role, a site can “hide” the
|
166
|
direct access to these topics and popup. Note that this does not
|
167
|
restrict <em>access</em>, as the contents of an unprotected HTML-file
|
168
|
on a Drupal website can be viewed by anyone who know (or is able to
|
169
|
guess) its URL.</p>
|
170
|
|
171
|
|
172
|
<p>To protect these files, place the following four lines in a file
|
173
|
named <code>.htaccess</code> in project's <code>help</code> directory:</p>
|
174
|
|
175
|
<pre>
|
176
|
<Files *\.html>
|
177
|
Order Allow,Deny
|
178
|
Deny from all
|
179
|
</Files>
|
180
|
</pre>
|
181
|
|
182
|
<p>It as the responsibility of the site manager to make sure this type
|
183
|
of protection is in place if the site has help files that merits
|
184
|
protection from direct access.</p>
|
185
|
|
186
|
<p>See also this tracker in the project's issue queue:
|
187
|
<a href="https://www.drupal.org/node/1980936">#1980936 Typing complete path to .html help files in module bypasses user permissions</a>.</p>
|
188
|
|
189
|
<h2 id="search">Search</h2>
|
190
|
|
191
|
<p>To enable advanced help search, navigate to
|
192
|
<span class="nav">Administration » Configuration » Search and metadata » Search settings</span>.
|
193
|
Scroll down to <em>Active search modules</em> and tick the box to the
|
194
|
left of “Advanced help”. The search form will appear on the top of
|
195
|
the advanced help index pages.</p>
|
196
|
|
197
|
<p>If the core <strong>Search</strong> module is enabled, the contents
|
198
|
of the advanced help framework will be indexed on cron. If you enable
|
199
|
new modules or themes and wish to immediately index their help text,
|
200
|
navigate to <span class="nav">Reports » Status report</span> and
|
201
|
click the link “run cron manually”.</p>
|
202
|
|