diff options
Diffstat (limited to 'sites/all/modules/advanced_help/help/using-advanced-help.html')
| -rw-r--r-- | sites/all/modules/advanced_help/help/using-advanced-help.html | 152 |
1 files changed, 152 insertions, 0 deletions
diff --git a/sites/all/modules/advanced_help/help/using-advanced-help.html b/sites/all/modules/advanced_help/help/using-advanced-help.html new file mode 100644 index 000000000..c47750bb4 --- /dev/null +++ b/sites/all/modules/advanced_help/help/using-advanced-help.html @@ -0,0 +1,152 @@ +<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 <strong>Advanced help</strong> 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'); +$output .= ' ' . t('Click the help icon!'); +</pre> +--> + +<!-- D7 --> +<pre> +$output = theme('advanced_help_topic', array( + 'module' => 'help_example', + 'topic' => 'about-php', +)); +$output .= ' ' . t('Click the help icon!'); +</pre> + +<p>This produces the following output:</p> + +<pre> +<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"> +<span>Help</span> +</a> + Click the help icon! +</div> +</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> +<a href="&topic:module/topic&">topic</a> +</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> +<img src="&path&example.png"/> +<img src="&trans_path&example.png"/> +</pre> + +<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> + +<p>To reference any normal path in the site, use:</p> +<pre> +<a href="&base_url&admin/settings/site-configuration">anchor text</a> +</pre> + +<p><strong>NOTE: </strong> In previous versions <strong>Advanced +help</strong> did not require the &'s to be wrapped around +<code>topic</code>, <code>path</code>, and <code>base_url</code>. +This is currently still supported, but will be removed in a future +version. By adding the &'s these tokens are now not limited +to <code>href=""</code> and <code>src=""</code> parameters.</p> + +<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 → 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> + +<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> + +<pre> +<Files *\.html> +Order Allow,Deny +Deny from all +</Files> +</pre> + +<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> + +<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> + +<h2 id="search">Search</h2> + +<p>To enable advanced help search, navigate to +<em>Administration → Configuration → Search and metadata → Search settings</em>. +Scroll down to <em>Active search modules</em> and tick the box to the +left of “Advanced help”. The search form will appear on the top of +the advanced help index pages.</p> + +<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> |