1 |
00c2605a
|
Assos Assos
|
<p>The <strong>Advanced help</strong> module provides a framework that
|
2 |
|
|
allows module and theme developers integrate help texts in a Drupal
|
3 |
6e9292aa
|
Assos Assos
|
site. Although the <strong>Advanced help</strong> does not provide
|
4 |
|
|
general help by itself, it provides a powerful and easy framework that
|
5 |
|
|
modules and themes may use to provide their own help.</p>
|
6 |
85ad3d82
|
Assos Assos
|
|
7 |
00c2605a
|
Assos Assos
|
<p>Modules and themes utilizing <strong>Advanced help</strong> should
|
8 |
|
|
create a subdirectory named <code>help</code> inside their own main
|
9 |
|
|
directory. Place the file
|
10 |
|
|
<em>MODULENAME</em>.help.ini (resp. <em>THEMENAME</em>.help.ini) in this subdirectory.
|
11 |
|
|
formatted similar to the following example:</p>
|
12 |
|
|
|
13 |
|
|
<pre>
|
14 |
|
|
[about-php]
|
15 |
|
|
title = About PHP
|
16 |
|
|
file = about-php
|
17 |
|
|
weight = -10
|
18 |
|
|
|
19 |
|
|
[history]
|
20 |
|
|
title = History of PHP
|
21 |
|
|
parent = about-php
|
22 |
|
|
|
23 |
|
|
[usage]
|
24 |
|
|
title = Usage of PHP
|
25 |
|
|
weight = 1
|
26 |
|
|
|
27 |
|
|
[security]
|
28 |
|
|
title = Security of PHP
|
29 |
|
|
weight = 2
|
30 |
|
|
|
31 |
|
|
[syntax]
|
32 |
|
|
title = PHP syntax
|
33 |
|
|
parent = usage
|
34 |
|
|
</pre>
|
35 |
|
|
|
36 |
6e9292aa
|
Assos Assos
|
<p>This file defines five help topics (inside the square brackets), and
|
37 |
00c2605a
|
Assos Assos
|
some settings for them.
|
38 |
|
|
See: <a href="&topic:advanced_help/ini-file&">Advanced help .ini file format</a> for
|
39 |
|
|
a list of defined settings.</p>
|
40 |
|
|
|
41 |
|
|
|
42 |
|
|
<p>All topics are addressed by the module or theme providing the
|
43 |
|
|
topic, and by the topic id. To produce a themed link to popup
|
44 |
|
|
about a topic, use the a format similar to the following example:</p>
|
45 |
|
|
|
46 |
|
|
|
47 |
|
|
|
48 |
|
|
|
49 |
|
|
|
50 |
|
|
|
51 |
|
|
|
52 |
|
|
|
53 |
|
|
|
54 |
|
|
<pre>
|
55 |
|
|
$output = theme('advanced_help_topic', array(
|
56 |
|
|
'module' => 'help_example',
|
57 |
|
|
'topic' => 'about-php',
|
58 |
|
|
));
|
59 |
|
|
$output .= ' ' . t('Click the help icon!');
|
60 |
|
|
</pre>
|
61 |
|
|
|
62 |
|
|
<p>This produces the following output:</p>
|
63 |
|
|
|
64 |
|
|
<pre>
|
65 |
|
|
<a class="advanced-help-link" title="About PHP"
|
66 |
|
|
onclick="var w=window.open(this.href, 'advanced_help_window',
|
67 |
|
|
'width=500,height=500,scrollbars,resizable');
|
68 |
|
|
w.focus(); return false;"
|
69 |
|
|
href="/help/help_example/about-php?popup=1">
|
70 |
|
|
<span>Help</span>
|
71 |
|
|
</a>
|
72 |
|
|
Click the help icon!
|
73 |
|
|
</div>
|
74 |
|
|
</pre>
|
75 |
|
|
|
76 |
|
|
<p>This produces a clickable help icon like the one shown below:</p>
|
77 |
|
|
|
78 |
|
|
<div class="ta-center">
|
79 |
|
|
<img class="help-img-center" alt="clickable icon" src="&path&click_icon.png" width="180" height="90" border="0" />
|
80 |
|
|
</div>
|
81 |
|
|
|
82 |
|
|
<p>Inside your help file, you may link to other help topics using this format:</p>
|
83 |
|
|
<pre>
|
84 |
|
|
<a href="&topic:module/topic&">topic</a>
|
85 |
|
|
</pre>
|
86 |
|
|
<p>This format will ensure the popup status remains consistent when
|
87 |
|
|
switching between links.</p>
|
88 |
|
|
|
89 |
6e9292aa
|
Assos Assos
|
<p>To reference items within the help directory, such as images you wish to embed within the help text, use:</p>
|
90 |
|
|
|
91 |
85ad3d82
|
Assos Assos
|
<pre>
|
92 |
00c2605a
|
Assos Assos
|
<img src="&path&example.png"/>
|
93 |
|
|
<img src="&trans_path&example.png"/>
|
94 |
|
|
</pre>
|
95 |
|
|
|
96 |
6e9292aa
|
Assos Assos
|
<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>
|
97 |
85ad3d82
|
Assos Assos
|
|
98 |
00c2605a
|
Assos Assos
|
<p>To reference any normal path in the site, use:</p>
|
99 |
|
|
<pre>
|
100 |
|
|
<a href="&base_url&admin/settings/site-configuration">anchor text</a>
|
101 |
85ad3d82
|
Assos Assos
|
</pre>
|
102 |
|
|
|
103 |
00c2605a
|
Assos Assos
|
<p><strong>NOTE: </strong> In previous versions <strong>Advanced
|
104 |
|
|
help</strong> did not require the &'s to be wrapped around
|
105 |
6e9292aa
|
Assos Assos
|
<code>topic</code>, <code>path</code>, and <code>base_url</code>.
|
106 |
|
|
This is currently still supported, but will be removed in a future
|
107 |
00c2605a
|
Assos Assos
|
version. By adding the &'s these tokens are now not limited
|
108 |
|
|
to <code>href=""</code> and <code>src=""</code> parameters.</p>
|
109 |
|
|
|
110 |
|
|
<h2 id="access-control">Access control</h2>
|
111 |
85ad3d82
|
Assos Assos
|
|
112 |
00c2605a
|
Assos Assos
|
<p>When this module is installed, users with the
|
113 |
|
|
<code>view advanced help index</code>
|
114 |
|
|
permission can access the advanced help index by going to
|
115 |
|
|
<em>Administer → Advanced Help</em>
|
116 |
|
|
(<code>admin/advanced_help</code>). Additional permissions
|
117 |
|
|
<code>view advanced help topic</code> and
|
118 |
|
|
<code>view advanced help popup</code>
|
119 |
|
|
enable users to access the actual help pages and popups.</p>
|
120 |
85ad3d82
|
Assos Assos
|
|
121 |
00c2605a
|
Assos Assos
|
<p>The help texts are stored as plain .html-files and can, unless
|
122 |
|
|
protected, be accessed by anyone who knows their URL. To protect
|
123 |
|
|
them, place the following four lines in a file named
|
124 |
|
|
<code>.htaccess</code> in project's <code>help</code> directory:</p>
|
125 |
85ad3d82
|
Assos Assos
|
|
126 |
00c2605a
|
Assos Assos
|
<pre>
|
127 |
|
|
<Files *\.html>
|
128 |
|
|
Order Allow,Deny
|
129 |
|
|
Deny from all
|
130 |
|
|
</Files>
|
131 |
|
|
</pre>
|
132 |
85ad3d82
|
Assos Assos
|
|
133 |
6e9292aa
|
Assos Assos
|
<p>It as the responsibility of the site manager to make sure this type
|
134 |
|
|
of protection is in place if the site has help files that merits
|
135 |
|
|
protection from direct access.</p>
|
136 |
85ad3d82
|
Assos Assos
|
|
137 |
00c2605a
|
Assos Assos
|
<p>See also this tracker in the project's issue queue:
|
138 |
|
|
<a href="https://www.drupal.org/node/1980936">#1980936 Typing complete path to .html help files in module bypasses user permissions</a>.</p>
|
139 |
85ad3d82
|
Assos Assos
|
|
140 |
00c2605a
|
Assos Assos
|
<h2 id="search">Search</h2>
|
141 |
85ad3d82
|
Assos Assos
|
|
142 |
6e9292aa
|
Assos Assos
|
<p>To enable advanced help search, navigate to
|
143 |
|
|
<em>Administration → Configuration → Search and metadata → Search settings</em>.
|
144 |
|
|
Scroll down to <em>Active search modules</em> and tick the box to the
|
145 |
|
|
left of “Advanced help”. The search form will appear on the top of
|
146 |
|
|
the advanced help index pages.</p>
|
147 |
|
|
|
148 |
00c2605a
|
Assos Assos
|
<p>If the core <strong>Search</strong> module is enabled, the contents
|
149 |
|
|
of the advanced help framework will be indexed on cron. If you enable
|
150 |
|
|
new modules or themes and wish to immediately index their help text,
|
151 |
6e9292aa
|
Assos Assos
|
navigate to <em>Administration → Reports → Status report</em> and
|
152 |
|
|
click the link “run cron manually”.</p> |