Révision 00c2605a
Ajouté par Assos Assos il y a environ 9 ans
drupal7/sites/all/modules/advanced_help/help/using-advanced-help.html | ||
---|---|---|
1 |
<p>The <em>Advanced help</em> system is a pluggable system that provides advanced help facilities for Drupal and its modules. Although the advanced help does not provide general help by itself, it provides a powerful and easy framework that modules may use to provide their own help. |
|
2 |
</p> |
|
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. Although the advanced help does not provide general help by |
|
4 |
itself, it provides a powerful and easy framework that modules and |
|
5 |
themes may use to provide their own help.</p> |
|
3 | 6 |
|
4 |
<p> |
|
5 |
Modules utilizing <em>Advanced help</em> should create a 'help' subdirectory inside their |
|
6 |
module's directory. Place the file MODULENAME.help.ini in this subdirectory, formatted |
|
7 |
similar to the following example: |
|
8 |
</p> |
|
7 |
<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 |
<p>This file defines five help topics (inside the square brackets, and |
|
37 |
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 |
<!-- D6 |
|
47 |
<pre> |
|
48 |
$output = theme('advanced_help_topic', 'help_example', 'about-php'); |
|
49 |
$output .= ' ' . t('Click the help icon!'); |
|
50 |
</pre> |
|
51 |
--> |
|
52 |
|
|
53 |
<!-- D7 --> |
|
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 |
<p>To reference items within the help directory, such as images you |
|
90 |
wish to embed within the help text, use:</p> |
|
9 | 91 |
<pre> |
10 |
[buses] |
|
11 |
title = "How buses are tied into the system" |
|
12 |
file = buses |
|
92 |
<img src="&path&example.png"/> |
|
93 |
<img src="&trans_path&example.png"/> |
|
94 |
</pre> |
|
95 |
|
|
96 |
<p>The latter is to refer to a translated version of the image if it differs from the original.</p> |
|
13 | 97 |
|
14 |
[TOPIC_ID] |
|
15 |
title = "Title of topic". |
|
16 |
file = filename of topic, without the .html extension. |
|
17 |
weight = How important the topic is on the index page. |
|
18 |
parent = The optional topic parent to use in the breadcrumb, |
|
19 |
either topic or module%topic. |
|
98 |
<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> |
|
20 | 101 |
</pre> |
21 | 102 |
|
22 |
<p> |
|
23 |
All topics are addressed by the module providing the topic, and by the topic |
|
24 |
id. To embed links, use the following format: |
|
25 |
</p> |
|
26 |
<code> |
|
27 |
$output .= theme('advanced_help_topic', $module, $topic); |
|
28 |
</code> |
|
103 |
<p><strong>NOTE: </strong> In previous versions <strong>Advanced |
|
104 |
help</strong> did not require the &'s to be wrapped around |
|
105 |
<code>topic:</code>, <code>path</code>, and <code>base_url</code>. |
|
106 |
This is currently still supported, but may be removed in a future |
|
107 |
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> |
|
29 | 111 |
|
30 |
<p>Inside your help file, link to other topics using the format <strong><a href="&topic:module/topic&"></strong>. This |
|
31 |
format will ensure the popup status remains consistent when switching between links.</p> |
|
112 |
<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> |
|
32 | 120 |
|
33 |
<p>Use <strong><a href="&path&example.jpg"></strong> to reference items |
|
34 |
within the help directory, such as images you wish to embed within the help text.</p> |
|
121 |
<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> |
|
35 | 125 |
|
36 |
<p>Use <strong><a href="&base_url&admin/settings/site-configuration"></strong> to reference any normal path in the site.</p> |
|
126 |
<pre> |
|
127 |
<Files *\.html> |
|
128 |
Order Allow,Deny |
|
129 |
Deny from all |
|
130 |
</Files> |
|
131 |
</pre> |
|
37 | 132 |
|
38 |
<p>If the search module is enabled, the contents of help system will be indexed on cron. If you enable new modules and wish to immediately index its help text, visit the "Administration -> Reports -> Status report" and click the "Run cron manually" link.</p> |
|
133 |
<p>It as the responsibility of the project author to make sure this |
|
134 |
type of protection is in place if the project's author has help files |
|
135 |
that merits protection from direct access.</p> |
|
39 | 136 |
|
40 |
<p>Example: <a href="&path&nowhere.jpg">Don't click this!</a></p> |
|
137 |
<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> |
|
41 | 139 |
|
42 |
<p>See: <a href="&topic:advanced_help/ini-file&">ini file format</a></p>
|
|
140 |
<h2 id="search">Search</h2>
|
|
43 | 141 |
|
44 |
<p><strong>NOTE: </strong> In previous versions Advanced Help did not require the &'s wrapped around the topic:, path:, and base_url: links. This |
|
45 |
is currently still supported, but may be removed in a future version. By adding the &'s these tokens are now not limited to href="" and src="" paramaters.</p> |
|
142 |
<p>If the core <strong>Search</strong> module is enabled, the contents |
|
143 |
of the advanced help framework will be indexed on cron. If you enable |
|
144 |
new modules or themes and wish to immediately index their help text, |
|
145 |
navigate to <em>Administration → Reports → Status report</em> and click the link |
|
146 |
“run cron manually”.</p> |
Formats disponibles : Unified diff
Weekly update of contrib modules