www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/advanced_help/help/using-advanced-help.html

   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 <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
   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 .= '&nbsp;' . 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 .= '&nbsp;' . t('Click the help icon!');
  60 </pre>
  61
  62 <p>This produces the following output:</p>
  63
  64 <pre>
  65 &lt;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"&gt;
  70 &lt;span&gt;Help&lt;/span&gt;
  71 &lt;/a&gt;
  72  Click the help icon!
  73 &lt;/div&gt;
  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 &lt;a href="&amp;topic:module/topic&amp;"&gt;topic&lt;/a&gt;
  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 wish to embed  within the help text, use:</p>
  90
  91 <pre>
  92 &lt;img src="&amp;path&amp;example.png"/&gt;
  93 &lt;img src="&amp;trans_path&amp;example.png"/&gt;
  94 </pre>
  95
  96 <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
  98 <p>To reference any normal path in the site, use:</p>
  99 <pre>
 100 &lt;a href="&amp;base_url&amp;admin/settings/site-configuration"&gt;anchor text&lt;/a&gt;
 101 </pre>
 102
 103 <p><strong>NOTE: </strong> In previous versions <strong>Advanced
 104 help</strong> did not require the &amp;'s to be wrapped around
 105 <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 version.  By adding the &amp;'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
 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 &rarr; 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
 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>
 125
 126 <pre>
 127 &lt;Files *\.html&gt;
 128 Order Allow,Deny
 129 Deny from all
 130 &lt;/Files&gt;
 131 </pre>
 132
 133 <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
 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>
 139
 140 <h2 id="search">Search</h2>
 141
 142 <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 <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 navigate to <em>Administration → Reports → Status report</em> and
 152 click the link “run cron manually”.</p>