using-advanced-help.html 7.05 KB
Newer Older
1 2
<p>The <strong>Advanced help</strong> module provides a framework that
allows module and theme developers integrate help texts in a Drupal
3 4 5 6 7 8 9 10 11 12 13
site.</p>

<p>It provides a framework for creating and maintaing HTML help texts.
It may also be used to display a module's or
theme's <code>README</code>-file on the screen.</p>

<h2 id="ah_enable">Enabling the module</h2>

<p>When you enable the module, a new tab with the legend “Advanced
help” will show up under “Help”:

14 15 16
<div class="help-imgpos-center" style="max-width:661px">
<img class="help-img" alt="ahelp_tab.png" title="The “Advanced help” tab" src="&path&ahelp_tab.png" width="661" />
<div class="help-img-caption" style="max-width:661px">Advanced help is found under a separate tab</div>
17 18 19 20 21
</div>

<p>Links to the help texts are under this tab.</p>

<h2 id="ah_crehlp">Creating help</h2>
22 23 24 25 26 27 28 29

<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>
30 31 32
[advanced help settings]
navigation = FALSE
show readme = FALSE
33

34 35 36
[about-example]
title = About the help example
weight = -11
37

38 39 40
[lorem]
title = Lorem ipsum
weight = -10
41

42 43 44 45
[etiam]
title = Etiam ultricies
parent = lorem
line break = TRUE
46 47
</pre>

48 49 50
<p>This file defines some global settings as well as three help topics
(inside the square brackets), and some settings for them.  See:
<a href="&topic:advanced_help/ini-file&">Advanced help .ini file
51
format</a>” for the full list of settings.</p>
52

53 54 55 56
<p>Characters <code>?{}|&~!()^"</code> should not be used anywhere in
the title as they have a special meaning, unless the the string is
quoted.  An error message like the one below indicates that quotes
should be used:</p>
57

58
<blockquote><p>Warning: syntax error, unexpected '(' in example.help.ini &hellip;</p></blockquote>
59

60 61 62 63 64 65 66 67 68 69
<h2 id="ah_lnkhlp">Linking to help</h2>

<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, there is a theme
function <code>theme_advanced_help_topic()</code> accepting three
named parameters passed in an array:</p>

<ol>  
<li><code>'module'</code>: The machine name of the module that owns this help topic.</li>
70 71
<li><code>'topic'</code>: The identifier for the topic (to link to topic) or <code>'toc'</code> (to link to index page).</li>
</ul></li>
72
<li><code>'type'</code>: The type of link to create:<ul>
73 74
  <li>'<code>icon'</code> to display the question mark icon.</li>
  <li>'<code>title'</code> to display the topic's title.</li>
75 76 77 78 79 80 81
  <li>any other text to display the text. Wrap it in <code>t()</code> to make it translatable.</li>
</ul></li>
</ol>  

<p>The following example shows how to link to a popup with the
topic <code>'about-example'</code> owned by the module
<code>'help_example'</code> using the question mark icon:</p>
82 83 84

<!-- D7 -->
<pre>
85
// Create the question mark icon.
86 87
$output = theme('advanced_help_topic', array(
  'module' => 'help_example',
88 89
  'topic' => 'about-example',
  'type' => 'icon',
90
));
91
// Append some explanatory text.
92 93 94 95 96 97
$output .= '&nbsp;' . t('Click the help icon!');
</pre>

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

<pre>
98
&lt;a class="advanced-help-link" title="About the help example"
99 100 101
  onclick="var w=window.open(this.href, 'advanced_help_window',
  'width=500,height=500,scrollbars,resizable');
  w.focus(); return false;"
102
  href="/help/help_example/about-example?popup=1"&gt;
103 104 105 106 107 108 109 110
&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>

111 112 113
<div class="help-imgpos-center" style="max-width:180px">
<img class="help-img" alt="clickable icon" title="The advanced help icon is a question mark" src="&path&click_icon.png" width="180" />
<div class="help-img-caption" style="max-width:180px">Question mark help icon</div>
114 115
</div>

116 117 118
<p>See the source code of demo module <strong>Advanced help
example</strong> for link examples.</p>

119 120 121
<p>You may link to other help topics inside your HTML help file using
this format:</p>

122 123 124 125
<pre>
&lt;a href="&amp;topic:module/topic&amp;"&gt;topic&lt;/a&gt;
</pre>

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

128 129 130 131 132
<pre>
&lt;img src="&amp;path&amp;example.png"/&gt;
&lt;img src="&amp;trans_path&amp;example.png"/&gt;
</pre>

133 134 135
<p>The <code>trans_path</code> keyword refers to a translated version
of the image in the translation directory and may be used if it
differs from the original.</p>
136 137 138 139 140 141 142 143

<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
144 145
<code>topic</code>, <code>path</code>, and <code>base_url</code>.
This is currently still supported, but will be removed in a future
146 147
version.  By adding the &amp;'s these tokens are now not limited
to <code>href=""</code> and <code>src=""</code> parameters.</p>
148

149
<h2 id="access-control">Hiding help files</h2>
150 151 152

<p>When this module is installed, users with the
<code>view advanced help index</code>
153 154 155
permission can access the advanced help index by navigating to
<span class="nav">Help » Advanced Help</span>.
Additional permissions
156
<code>view advanced help topic</code>  and
157 158 159
<code>view advanced help popup</code> allows the user to click
trough to the actual help pages and popups.</p>

160
<p>By taking away these permissions from a role, a site can “hide” the
161 162 163 164
direct access to these topics and popup.  Note that this does not
restrict <em>access</em>, as the contents of an unprotected HTML-file
on a Drupal website can be viewed by anyone who know (or is able to
guess) its URL.</p>
165

166 167 168

<p>To protect these files, place the following four lines in a file
named <code>.htaccess</code> in project's <code>help</code> directory:</p>
169

170
<pre>
171 172 173 174
&lt;Files *\.html&gt;
Order Allow,Deny
Deny from all
&lt;/Files&gt;
175 176
</pre>

177 178 179
<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>
180

181 182
<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>
183

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

186
<p>To enable advanced help search, navigate to
187
<span class="nav">Administration » Configuration » Search and metadata » Search settings</span>.
188
Scroll down to <em>Active search modules</em> and tick the box to the
189 190
left of “Advanced help”.  The search form will appear on the top of
the advanced help index pages.</p>
191

192 193 194
<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,
195 196
navigate to <span class="nav">Reports » Status report</span> and
click the link “run cron manually”.</p>
197