Commit c266542e authored by gisle's avatar gisle
Browse files

Issue #2832269 by gisle: Added display of README along with HTML

parent 50986e7c
---
# Define an alias for screendumps.
aliases:
hide: TRUE
title: ALIASES
block:
- &screendumps
type: asset
approved: allowed license
license: CC0
rights: https://creativecommons.org/publicdomain/zero/1.0/
source: Gisle Hannemyr
help.png:
title: help.png
type: asset
approved: allowed license
license: CC0
rights: https://creativecommons.org/publicdomain/zero/1.0/
source: unknown origin
hide: TRUE
help/ahelp_tab.png:
title: ahelp_tab.png
hide: TRUE
a: *screendumps
help/click_icon.png:
title: click_icon.png
hide: TRUE
a: *screendumps
......@@ -6,6 +6,7 @@ CONTENTS OF THIS FILE
* Recommended modules
* Installation
* Configuration
* Support status
* Maintainers
......@@ -31,8 +32,7 @@ Advanced help hint:
https://www.drupal.org/project/advanced_help_hint
If Advanced help is not enabled, this module will generate a hint
string that can be used in the project's hook_help to hint that
Advanced help should be
enabled.
Advanced help should be enabled.
Installation
......@@ -47,11 +47,31 @@ further information.
Configuration
-------------
By itself, this module doesn't do much. The Advanced help assists
other modules and themes in showing help texts. Nothing will show up
until you enable at least one other module that makes use of the
Advanced help framework or comes with a file named README.md or
README.txt.
There is no configuration.
When you enable the module, you will have access to on-screen help,
including README-files, created to tie in with the **Advanced help**
framework.
Support status
--------------
Reported bugs for the Drupal 7 branch will be fixed in a timely
manner. Older versions are no longer supported.
Community support in the form of patches are very welcome for both
Drupal 7 and Drupal 8 versions. For QA, the project needs community
support in the form of reviews of patches, development versions and
releases.
The primary goal of the module is to remain light-weight and simple.
This means that not all feature requests will be implemented, even if
they are a good idea. Feature requests accompanied by patches are
more likely to make it into a release.
The maintainer hopes that the community is willing to help out by
answering & closing support requests.
Maintainers
......@@ -64,4 +84,4 @@ amitgoyal (5 commits)
gisle (current maintainer, D7)
gnuget (current maintainer, D8)
This project has been sponsored by:Hannemyr Nye Medier AS
This project has been sponsored by: Hannemyr Nye Medier AS
......@@ -32,10 +32,27 @@
* links.)
*/
/**
* Implements hook_help().
*/
function advanced_help_help($path, $arg) {
if ($path == 'admin/help#advanced_help') {
$output = '<p>' . t('This module provides extended help and documentation.') . '</p>';
if (function_exists('advanced_help_hint_docs')) {
$output .= '<p>' . advanced_help_hint_docs('advanced_help', 'https://www.drupal.org/docs/7/modules/advanced-help', TRUE) . '</p>';
}
else {
$output .= t('If you install and enable the module <strong>!url</strong>, you will get more help for <strong>Advanced help</strong>.',
array('!url' => l('Advanced help hint', 'https://www.drupal.org/project/advanced_help_hint')));
}
return $output;
}
}
/**
* Implements hook_menu().
*
* Strings in hook_help() should not be run through t().
* Strings in hook_menu() should not be run through t().
*/
function advanced_help_menu() {
$help_exists = module_exists('help') ? TRUE : FALSE;
......@@ -590,7 +607,7 @@ function theme_advanced_help_topic($variables) {
function advanced_help_get_topic_filename($module, $topic) {
$info = advanced_help_get_topic_file_info($module, $topic);
if ($info) {
return "./$info[path]/$info[file]";
return "$info[path]/$info[file]";
}
}
......@@ -605,6 +622,9 @@ function _advanced_help_get_module_type($module) {
/**
* Load and render a help topic.
*
* The strategy is first to see if a translated file for the current
* active language exists. If not found, look for the default.
*/
function advanced_help_get_topic_file_info($module, $topic) {
global $language;
......@@ -617,16 +637,14 @@ function advanced_help_get_topic_file_info($module, $topic) {
// Search paths:
$module_type = _advanced_help_get_module_type($module);
$paths = array(
// Allow theme override.
path_to_theme() . '/help',
// Translations.
// First see if a translation exists.
drupal_get_path($module_type, $module) . "/translations/help/$language->language",
// In same directory as .inc file.
$info['path'],
);
foreach ($paths as $path) {
if (file_exists("./$path/$info[file]")) {
if (file_exists("$path/$info[file]")) {
return array('path' => $path, 'file' => $info['file']);
}
}
......@@ -824,36 +842,43 @@ function advanced_help_get_settings() {
function _advanced_help_parse_ini() {
global $language;
static $ini = NULL;
if (!isset($ini)) {
$cache = cache_get('advanced_help_ini:' . $language->language);
if ($cache) {
$ini = $cache->data;
}
}
if (!isset($ini)) {
// No cached list of topics - create it.
$ini = array('topics' => array(), 'settings' => array());
foreach (array_merge(module_list(), list_themes()) as $plugin) {
$module = is_string($plugin) ? $plugin : $plugin->name;
$module_path = drupal_get_path(is_string($plugin) ? 'module' : 'theme', $module);
$info = array();
// Parse ini-file if it exists
if (file_exists("$module_path/help/$module.help.ini")) {
$path = "$module_path/help";
$path_html = "$module_path/help";
$info = parse_ini_file("./$module_path/help/$module.help.ini", TRUE);
if (!$info) {
drupal_set_message(t('There is a syntax error in the default .ini-file. Unable to display topics.'), 'error');
}
}
else {
$info = array();
}
elseif (!file_exists("$module_path/help")) {
if (empty($info) || !empty($info['advanced help settings']['show readme'])) {
// Look for one or more README files.
$files = file_scan_directory("./$module_path",
'/^(readme).*\.(txt|md)$/i', array('recurse' => FALSE));
$path = "./$module_path";
$path_readme = "$module_path";
foreach ($files as $name => $fileinfo) {
$info[$fileinfo->filename] = array(
'line break' => TRUE,
'readme file' => TRUE,
'file' => $fileinfo->filename,
'title' => $fileinfo->name,
'weight' => -99,
);
}
}
......@@ -863,6 +888,9 @@ function _advanced_help_parse_ini() {
$translation = array();
if (file_exists("$module_path/translations/help/$language->language/$module.help.ini")) {
$translation = parse_ini_file("$module_path/translations/help/$language->language/$module.help.ini", TRUE);
if (!$translation) {
drupal_set_message(t('There is a syntax error in the translated .ini-file.'), 'error');
}
}
$ini['settings'][$module] = array();
......@@ -895,9 +923,10 @@ function _advanced_help_parse_ini() {
// Require extension.
'file' => isset($topic['readme file']) ? $file : $file . '.html',
// Not in .ini file.
'path' => $path,
'path' => isset($topic['readme file']) ? $path_readme : $path_html,
'line break' => isset($topic['line break']) ? $topic['line break'] : (isset($ini['settings'][$module]['line break']) ? $ini['settings'][$module]['line break'] : FALSE),
'navigation' => isset($topic['navigation']) ? $topic['navigation'] : (isset($ini['settings'][$module]['navigation']) ? $ini['settings'][$module]['navigation'] : TRUE),
'show readme' => isset($topic['show readme']) ? $topic['show readme'] : (isset($ini['settings'][$module]['show readme']) ? $ini['settings'][$module]['show readme'] : FALSE),
'css' => isset($topic['css']) ? $topic['css'] : (isset($ini['settings'][$module]['css']) ? $ini['settings'][$module]['css'] : NULL),
'readme file' => isset($topic['readme file']) ? $topic['readme file'] : FALSE,
);
......
[readme]
title = README
[advanced help settings]
show readme = TRUE
[introduction]
title = Introduction
weight = -11
[using-advanced-help]
......
......@@ -35,19 +35,26 @@ use a more friendly name than appears in the project's .info file.</dd>
module/theme index. It overrides the <code>name</code> setting above,
as well as the project's name in its .info file.</dd>
<dt><code>show readme</code> (FALSE)</dt>
<dd>For projects that comes with a set of HTML-files, the default is
to hide the project's <code>README</code>-file. Setting this TRUE will
show the README along with the HTML-files.</dd>
<dt><code>hide</code> (FALSE)</dt>
<dd>This may be used to hide a module or theme in the module/theme
index. This is particularly useful for modules who insert their help
files into the hierarchy of another module or theme, as might be done
by modules that extend <strong>Views</strong> or derived themes that
extend base themes like <strong>Zen</strong>. By setting this to TRUE
the project will not appear as its own entry.</dd>
files into the hierarchy of another module or theme. By setting this
to TRUE the project will not appear as its own entry.</dd>
</dl>
<p>Each section after that will correspond to a single help file for a
single topic. It starts with the topic name in square brackets
(e.g. <code>[ini-file]</code>). The following settings may be set for
each file/topic, with the default value (if any) in brackets.</p>
single topic. It starts with the topic machine name in square
brackets (e.g. <code>[introduction]</code>). The file containing the
documentation for that topic will have the same machine name with the
extension <code>html</code> (e.g. <code>introduction.html</code>) The
following settings may be set for each file/topic, with the default
value (if any) in brackets.</p>
<dl>
<dt><code>title</code></dt>
......@@ -68,8 +75,8 @@ are sorted alphabetically.</dd>
<dt><code>parent</code></dt>
<dd>The topic ID to use in a hierarchy; children will be listed
beneath parents in the topic list, and will have the parent in their
breadcrumb trail. You may parent this topic to a topic in another
module or theme by using <code>module%topic</code>
breadcrumb trail. You may parent this topic to a topic
in <em>another</em> module or theme by using <code>module%topic</code>
or <code>theme%topic</code> as the identifier,
where <code>module</code> or <code>theme</code> is the project's short
name. For example if parent is set to, '<code>views%display</code>',
......@@ -93,25 +100,5 @@ will override any .css file added by the global settings.</dd>
<dd>The height in pixels of the popup window.</dd>
</dl>
<p>For example, here is a version of the <code>advanced_help.help.ini</code> file:</p>
<pre>
[readme]
title = README
weight = -11
[using-advanced-help]
title = Using advanced help
weight = -10
[translation]
title = Translating advanced help
[ini-file]
title = Help .ini file format
line break = FALSE
[why-advanced-help]
title = Why advanced help?
line break = TRUE
</pre>
<p>Take a look at the .ini-file for this project to see an
example.</p>
<p>The <strong>Advanced help</strong> module provides a framework that
allows help texts to be viewed as integrated into a Drupal
website.</p>
<p>These help texts are stored in ordinary <code>.html</code>-files
that lives in the file system (as opposed to the database). These
files are distributed from the project Drupal.org repo in the same
package as the module or theme, and placed in a subdirectory named
<code>help</code> in the project or theme directory.</p>
<p>The help texts can be marked up with standard HTML. They will be
rendered using your site's theme, but you may provide custom css. If
there is a <code>README.md</code> or <code>README.txt</code> in the
package, the content of that file may be shown as well.</p>
<p>The help texts can be placed in an hierarchical book, allowing for
top-down navigation, or placed in popups that can be added to a page
with plain text links or themed icon links.</p>
<p>Cross-linking book-sections,using fragment identifiers, works as
one would expect.</p>
<p>The help texts may be made searchable, but are not so by default (see
<a href="&topic:advanced_help/using-advanced-help#search&">Using advanced help</a>
for details). If search is enabled, all help texts are fully
indexed. This means that the entire contents of the advanced help set
of pages can be searched for keywords.</p>
<p>Modules and themes can even insert help texts into another
project's hierarchy.</p>
<p>May be integrated into <code>hook_help()</code> using companion
module
<a href="https://www.drupal.org/project/advanced_help_hint"><strong>Advanced help hint</strong></a>.</p>
<h2 id="demo">Demonstrations</h2>
<p>The project comes with a small demo module named
<strong>Advanced help example</strong> to demonstrate how it works.
For an example of a project that makes extensive use of the advanced
help features, see the <strong>Views</strong> project.</p>
<p>For an example of translation of help text, see the
directory <code>translations/help/nb</code> in the <strong>Advanced
help example</strong> submodule. For translation instructions, see the
section named “<a href="&topic:advanced_help/translation&">Translating
advanced help</a>”.</p>
<h2 id="project-description">Synopsis</h2>
<p>The <strong>Advanced help</strong> module provides a framework that allows
module and theme developers integrate help texts in a Drupal site.</p>
<p>These help texts are stored in ordinary <code>.html</code>-files
that lives in the file system (as opposed to the database). These
files are distributed from the project Drupal.org repo in the same
package as the module or theme, and placed in a subdirectory named
<code>help</code> in the project or theme directory. This means that
the help texts can be easily kept in sync with the project they
provide help texts for, but also that read access to these files
are not managed by any content access restrictions imposed by Drupal.</p>
<p>The help texts can be marked up with standard HTML. They will be
rendered using your site's theme.</p>
<p>If the module or theme author does not make use of the
<em>Advanced help</em> HTML-framework, but if there is a
<code>README.md</code> or <code>README.txt</code> in the package,
the content of that file will be shown instead.</p>
<p>The help texts may appear in a popup or not as the project prefers.
By taking away access to view the popups, a site can hide popups from
users.</p>
<p>The help texts can be placed in a hierarchy, allowing for top down
navigation of help.</p>
<p>The help texts may be made searchable. If advanced help search is
enabled, all help texts are fully indexed. This means that the entire
contents of the advanced help set of pages can be searched for
keywords.</p>
<h2 id="use">Using the module</h2>
<p>When you enable the module, a new tab with the legend “Advanced
help” will show up under “Help”:
<div class="ta-center">
<img class="help-img-center" alt="ahelp_tab.png" src="&path&ahelp_tab.png" width="661" height="225" border="1" />
</div>
<p>By itself, this module doesn't do much. The <strong>Advanced
help</strong> assists other modules and themes in showing help texts.
Nothing will show up until you enable at least one other module that
makes use of the advanced help framework or comes with a file
named <code>README.md</code> or <code>README.txt</code>. However, it
comes with a small companion demo module named
<strong>Advanced help example</strong> to demonstrate how it works.
For more extensive example of use of the advanced help features, see
the <strong>Views</strong> project.</p>
<!--
<h2 id="project-recommended">Recommended modules</h2>
<ul>
<li><a href="https://www.drupal.org/project/markdown">Markdown filter</a>:<br>
When this module is enabled, display of any <code>README.md</code> the
module shows will be rendered with markdown.</li>
<li><a href="https://www.drupal.org/project/attributions">Attributions</a>:<br>
When this module is enabled, attributions of third party content used
by the project (i.e. some text from Wikipedia) will be available in an
attribution block and on an attribution page.</li>
</ul>
-->
<h2 id="support-status">Support status</h2>
<p>Reported bugs for the Drupal 7 branch will be fixed in a timely
manner. Bugs in the issue queue for the Drupal 6 branch will only be
fixed if accompanied with a patch, after the patch has been reviewed
and tested by the community. No Drupal 8 version is currently under
development. Post a message in
the <a href="https://www.drupal.org/node/1928218">issue queue</a> if
you're interested in managing a port of the project to to Drupal
8. Older versions are no longer supported.</p>
<p>Community support in the form of patches are very welcome for both
Drupal 6 and Drupal 7 versions, and will be given priority. For QA,
the project needs community support in the form of reviews of patches,
development versions and releases.</p>
<p>The primary goal of the module is to remain <strong>light-weight
and simple</strong>. This means that not all feature requests will be
implemented, even if they are a good idea. Feature requests
accompanied by patches are more likely to make it into a release.</p>
<p>The maintainer hopes that the community is willing to help out by
answering &amp; closing support requests.</p>
<!--
<h2 id="project-problems">Known problems</h2>
-->
<h2 id="project-maintainers">Credits</h2>
<ul>
<li><a href="https://www.drupal.org/u/merlinofchaos">merlinofchaos</a> (52 commits, original creator)</li>
<li><a href="https://www.drupal.org/u/redndahead">redndahead</a> (8 commits)</li>
<li><a href="https://www.drupal.org/u/dmitrig01">dmitrig01</a> (3 commits)</li>
<li><a href="https://www.drupal.org/u/amitgoyal">amitgoyal </a> (5 commits)</li>
<li><a href="https://www.drupal.org/u/gisle">gisle</a> (current maintainer, D7)</li>
<li><a href="https://www.drupal.org/u/gnuget">gnuget</a> (current maintainer, D8)</li>
</ul>
<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>
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”:
<div class="ta-center">
<img class="help-img-center" alt="ahelp_tab.png" src="&path&ahelp_tab.png" width="661" height="225" border="1" />
</div>
<p>Links to the help texts are under this tab.</p>
<h2 id="ah_crehlp">Creating help</h2>
<p>Modules and themes utilizing <strong>Advanced help</strong> should
create a subdirectory named <code>help</code> inside their own main
......@@ -11,62 +26,78 @@ directory. Place the file
formatted similar to the following example:</p>
<pre>
[about-php]
title = About PHP
file = about-php
weight = -10
[advanced help settings]
navigation = FALSE
show readme = FALSE
[history]
title = History of PHP
parent = about-php
[about-example]
title = About the help example
weight = -11
[usage]
title = Usage of PHP
weight = 1
[security]
title = Security of PHP
weight = 2
[lorem]
title = Lorem ipsum
weight = -10
[syntax]
title = PHP syntax
parent = usage
[etiam]
title = Etiam ultricies
parent = lorem
line break = TRUE
</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>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
format</a>” for a list of defined settings.</p>
<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>
<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>
<blockquote><p>Warning: syntax error, unexpected '(' in example.help.ini &hellip;</p></blockquote>
<!-- D6
<pre>
$output = theme('advanced_help_topic', 'help_example', 'about-php');
$output .= '&nbsp;' . t('Click the help icon!');
</pre>
-->
<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>
<li><code>'topic'</code>: The identifier for the topic.</li>
<li><code>'type'</code>: The type of link to create:<ul>
<li>'<code>icon'</code> to display the question mark icon</li>
<li>'<code>title'</code> to display the topic's title</li>
<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>
<!-- D7 -->
<pre>
// Create the question mark icon.
$output = theme('advanced_help_topic', array(
'module' => 'help_example',
'topic' => 'about-php',
'topic' => 'about-example',
'type' => 'icon',
));
// Append some explanatory text.
$output .= '&nbsp;' . t('Click the help icon!');
</pre>
<p>This produces the following output:</p>
<pre>
&lt;a class="advanced-help-link" title="About PHP"
&lt;a class="advanced-help-link" title="About the help example"
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"&gt;
href="/help/help_example/about-example?popup=1"&gt;
&lt;span&gt;Help&lt;/span&gt;
&lt;/a&gt;
Click the help icon!
......@@ -79,12 +110,12 @@ $output .= '&nbsp;' . t('Click the help icon!');
<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>
<p>You may link to other help topics inside your HTML help file using
this format:</p>
<pre>
&lt;a href="&amp;topic:module/topic&amp;"&gt;topic&lt;/a&gt;
</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>
......@@ -93,7 +124,9 @@ switching between links.</p>
&lt;img src="&amp;trans_path&amp;example.png"/&gt;
</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>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>
<p>To reference any normal path in the site, use:</p>