Skip to content

GitLab

Commit fc02514a authored by gisle's avatar gisle
Browse files

Issue #1280514 by gisle: Added feature to theme a link to the index page

parent c266542e
Hide whitespace changes
Inline Side-by-side
Showing with 438 additions and 128 deletions
README.txt
View file @ fc02514a
......@@ -14,7 +14,8 @@ Introduction
------------
The **Advanced help** module provides a framework that allows module
and theme developers integrate help texts in a Drupal site.
and theme developers to provide contextual in-line help within a
Drupal site.
For more documentation, please visit: /admin/help/ah/advanced_help
after enabling the module.
......@@ -22,7 +23,7 @@ after enabling the module.
Requirements
------------
This module has no required dependencies outside of Drupal core.
This module has no dependencies outside of Drupal core.
Recommended modules
......@@ -40,39 +41,24 @@ Installation
Install the Advanced Help module as you would normally install a
contributed Drupal module. See
https://drupal.org/documentation/install/modules-themes/modules-7 for
further information.
https://drupal.org/documentation/install/modules-themes/modules-7
for further information.
Configuration
-------------
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.
There is no configuration in the Drupal administrative GUI.
Read the sections titled “Using advanced help” and “Advanced help .ini
file format” (part of the in-line help files that comes with this
module) to learn how to create and configure help files.
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.
Please see section titled “Support status” on project page:
https://www.drupal.org/project/advanced_help
Maintainers
-----------
......
advanced-help-popup.tpl.php
View file @ fc02514a
......@@ -4,10 +4,7 @@
* Default theme implementation to display a help popup.
*/
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php print $language->language ?>" lang="<?php print $language->language ?>" dir="<?php print $language->dir ?>">
<!DOCTYPE html>
<head>
<title><?php print $head_title; ?></title>
<?php print $head; ?>
......
advanced_help.module
View file @ fc02514a
......@@ -49,6 +49,18 @@ function advanced_help_help($path, $arg) {
}
}
/**
* Implements hook_admin_paths().
*
* Force help pages for this modile to be rendered in admin theme.
*/
function advanced_help_admin_paths() {
$paths = array(
'help/advanced_help/*' => TRUE,
);
return $paths;
}
/**
* Implements hook_menu().
*
......@@ -466,11 +478,13 @@ function advanced_help_get_module_name($module) {
* Page callback to view a help topic.
*/
function advanced_help_topic_page($module, $topic) {
if ('toc' == $topic) {
return advanced_help_index_page($module);
}
$info = advanced_help_get_topic($module, $topic);
if (!$info) {
return drupal_not_found();
}
$popup = !empty($_GET['popup']) && user_access('view advanced help popup');
drupal_set_title($info['title']);
......@@ -556,9 +570,18 @@ function theme_advanced_help_topic($variables) {
$topic = $variables['topic'];
$type = $variables['type'];
$info = advanced_help_get_topic($module, $topic);
if (!$info) {
return;
if ('toc' == $topic) {
$info = array(
'title' => 'Index page',
'popup width' => 500,
'popup height' => 500,
);
}
else {
$info = advanced_help_get_topic($module, $topic);
if (!$info) {
return;
}
}
switch ($type) {
......@@ -669,7 +692,7 @@ function advanced_help_view_topic($module, $topic, $popup = FALSE) {
$info = advanced_help_get_topic($module, $topic);
$file = "./$file_info[path]/$file_info[file]";
// Fix invalid byte sequences (Issue #1330056).
// Fix invalid byte sequences (https://www.drupal.org/node/2659746).
$output = file_get_contents($file);
mb_substitute_character(0xfffd);
$output = mb_convert_encoding($output, 'UTF-8', 'UTF-8');
......@@ -1171,8 +1194,9 @@ function template_preprocess_advanced_help_popup(&$variables) {
}
// Closure should be filled last.
// There has never been a theme hook for closure (going back to
// first release 2008-04-17). Unable to figure out its purpose.
// $variables['closure'] = theme('closure');
// first release 2008-04-17), so it is always 0 bytes.
// Unable to figure out its purpose - commenting out.
// $variables['closure'] = theme('closure');
}
/**
......
help.css
View file @ fc02514a
.advanced-help-topic pre {
background: #f1f1f1;
border: 1px solid #ccc;
display: block;
margin: 1em;
padding: .4em;
}
.advanced-help-topic p.bob {
background: #f1f1f1;
border: 1px solid #ccc;
display: block;
margin: 1em;
padding: .4em;
}
.advanced-help-topic pre.readme {
background: white;
border: none;
margin: 0em;
padding: .4em;
}
/* #content h2 has higher specifity */
.advanced-help-topic h1 {font-size: 2em;}
#content .advanced-help-topic > h2 {font-size: 1.75em}
......@@ -46,78 +23,134 @@
font-weight: normal;
}
.attribution {
font-size: 0.8em;
color: #aaa;
}
.help-left {
.advanced-help-topic pre {
background: #f1f1f1;
border: 1px solid #ccc;
display: block;
float: left; /* LTR */
text-align: left;
width: 42%;
margin: 1em;
padding: .4em;
}
.help-leftalign {
text-align: left;
.advanced-help-topic pre.readme {
background: white;
border: none;
margin: 0em;
padding: .4em;
}
.help-up {
display: block;
float: left; /* LTR */
margin: 0 5%;
text-align: center;
width: 10%;
#content .advanced-help-topic {
margin: auto;
max-width: 750px;
}
.help-up-noleft {
.advanced-help-topic p.bob {
border-width: 4px 0 4px 0;
border-style: solid;
border-color: #ccc;
display: block;
float: left; /* LTR */
margin: 0 5%;
text-align: right;
width: 42%;
margin: 1.5em;
padding: .5em;
}
.help-right {
display: block;
float: right;
text-align: right;
width: 42%;
.attribution {
font-size: 0.8em;
color: #aaa;
}
/* Class used by Views */
.help-box {
margin: .5em;
}
.help-block {
/* Style images */
.help-imgpos-left {
display: block;
clear: both;
padding: 2px;
margin: 0 1.25em 0.5em 0;
float: left;
border: solid 1px #ccc;
}
.help-img-left {
margin-right: 1.5em;
.help-imgpos-right {
display: block;
padding: 2px;
margin: 0 0 0.5em 1.25em;
float: right;
border: solid 1px #ccc;
}
.ta-center {
margin: 1em;
text-align: center;
.help-imgpos-center {
margin: 1em auto 1em auto;
padding: 2px;
border: solid 1px #ccc;
}
.help-img-center {
.help-img {
margin-left: auto;
margin-right: auto;
border: solid 1px #ccc;
}
.help-img-caption {
text-align: center;
background: #f6f6f6;
margin-left: auto;
margin-right: auto;
font-size: 0.9em;
}
/* Style navigation */
.advanced-help-topic > .item-list {
margin-top: 2em;
border-top: 1px dotted #ccc;
}
.help-navigation {
padding-top: 0.5em;
border-top: 1px dotted #ccc;
}
.help-previous {
.help-left {
display: block;
float: left;
text-align: left;
width: 35%;
}
.help-next {
.help-up {
display: block;
float: left;
margin-left: 10%;
text-align: center;
width: 10%;
}
.help-up-noleft {
display: block;
float: left; /* LTR */
margin: 0;
text-align: right;
width: 50%;
}
.help-right {
display: block;
float: right;
text-align: right;
width: 35%;
}
/* Media */
@media print {
#toolbar,
.add-shortcut,
.breadcrumb,
.help-navigation {
display: none;
}
}
/* End */
\ No newline at end of file
help/ini-file.html
View file @ fc02514a
......@@ -83,7 +83,7 @@ name. For example if parent is set to, '<code>views%display</code>',
the topic will be regarded as a child of the
<code>display</code> topic in the <strong>Views</strong> module.</dd>
<dt><code>line break</code> (FALSE)</dt>
<dt><code>line break</code></dt>
<dd>Set the line break filter for this topic. Set to FALSE to disable
the line break filter if this has been turned on in the global
settings.</dd>
......@@ -100,5 +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>Take a look at the .ini-file for this project to see an
<p>Take a look at the .ini-file for this project to see an ini-file
example.</p>
help/introduction.html
View file @ fc02514a
......@@ -8,14 +8,21 @@ 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 marked up with standard HTML. The help pages
will be rendered using your site's administrative theme. Having a
simple simple one-column, tableless, fluid width administration theme
(e.g. <strong>Seven</strong>) is strongly recommended.</p>
<p>You may attach custom css to a project that uses <strong>Advanced
help</strong> to provide help.</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>
top-down navigation, or programmatically placed in popups that can be
added to a page with plain text links or themed icon links.</p>
<p>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>Cross-linking book-sections,using fragment identifiers, works as
one would expect.</p>
......@@ -38,8 +45,11 @@ module
<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>
This example also shows how to make use of some of the css classes
provided.</p>
<p>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/using-advanced-help.html
View file @ fc02514a
......@@ -11,8 +11,9 @@ theme's <code>README</code>-file on the screen.</p>
<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 class="help-imgpos-center" style="max-width:661px">
<img class="help-img" alt="ahelp_tab.png" title="The “Advanced help” tab" src="&path&ahelp_tab.png" width="661" />
<div class="help-img-caption" style="max-width:661px">Advanced help is found under a separate tab</div>
</div>
<p>Links to the help texts are under this tab.</p>
......@@ -47,7 +48,7 @@ line break = TRUE
<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>
format</a>” for the full list of 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
......@@ -106,8 +107,9 @@ $output .= '&nbsp;' . t('Click the help icon!');
<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 class="help-imgpos-center" style="max-width:180px">
<img class="help-img" alt="clickable icon" title="The advanced help icon is a question mark" src="&path&click_icon.png" width="180" />
<div class="help-img-caption" style="max-width:180px">Question mark help icon</div>
</div>
<p>You may link to other help topics inside your HTML help file using
......
help_example/help/help_example.help.ini
View file @ fc02514a
......@@ -14,3 +14,7 @@ weight = -10
title = Etiam ultricies
parent = lorem
line break = TRUE
[images]
title = Image examples
weight = -9
help_example/help/images.html 0 → 100644
View file @ fc02514a
<p>Curabitur quis sollicitudin libero. Duis ligula lacus, luctus vitae
imperdiet quis, vestibulum semper dui. In in finibus ipsum. Nullam
quis dapibus metus.</p>
<div class="help-imgpos-center" style="max-width:400px">
<img class="help-img" alt="kitten03_400_200.jpg" title="Photographer: super-mapio" src="&path&kitten03_400_200.jpg" width="400" />
<div class="help-img-caption" style="max-width:400px">Photo: super-mapio. License: CC0</div>
</div>
<p>Ante vestibulum dui in orci commodo varius. Pellentesque
accumsan urna nulla, et dictum risus pulvinar et. Mauris accumsan enim
porta justo elementum molestie non at elit. Morbi suscipit id purus
nec efficitur.</p>
<div class="help-imgpos-left">
<img class="help-img" alt="kitten01_200_200.jpg" title="Photographer: Ty Swartz" src="&path&kitten01_200_200.jpg" width="200" />
<div class="help-img-caption" style="max-width:200px">Photo: Ty Swartz. License: CC0</div>
</div>
<p>Nunc at mauris eleifend, scelerisque justo nec, gravida sem. Donec
ultrices ligula vitae sem tempus, ac eleifend turpis consequat. Morbi
auctor placerat tellus, eu porta velit laoreet sit amet. Etiam
consequat dui a libero dignissim tempor.</p>
<p>Sed ac fringilla mi, eu
placerat ipsum. Vestibulum ante ipsum primis in faucibus orci luctus
et ultrices posuere cubilia Curae; Curabitur nisl lectus, rutrum et
dui id, rhoncus vehicula enim. Aenean non aliquet augue. Curabitur
orci orci, aliquam sit amet magna sit amet, feugiat porta ante. Aenean
iaculis semper interdum. Aliquam tristique non est eget tempus.</p>
<div class="help-imgpos-right">
<img class="help-img" alt="kitten02_200_200.jpg" title="Photographer: Ilona Ilyés" src="&path&kitten02_200_200.jpg" width="200" />
<div class="help-img-caption" style="max-width:200px">Photo: Ilona Ilyés. License: CC0</div>
</div>
<p>Donec rutrum nisl in nibh imperdiet laoreet. Vestibulum non posuere
augue, vitae tristique erat. Nunc ornare fermentum sapien id
tristique. In hac habitasse platea dictumst. Curabitur suscipit a quam
sit amet feugiat. Suspendisse eu tristique neque, ac malesuada
ipsum. Donec lacinia libero ligula, quis tempor orci ultricies
vel. Maecenas lobortis vehicula placerat.</p>
<p>Proin in urna enim. Etiam purus purus, vulputate non sollicitudin
sodales, faucibus eu quam. Pellentesque id mattis justo. Curabitur ac
rhoncus velit. Duis mollis, turpis vitae elementum sagittis, felis
augue blandit elit, a porttitor magna massa quis odio. Nulla ornare
nibh mi, a efficitur leo vulputate a.</p>
<p>Fusce euismod purus dui, vel porttitor neque pellentesque at. Morbi
consectetur purus neque. Integer efficitur dignissim nulla at
molestie. Sed ut velit et erat venenatis dictum vel ac enim. Quisque
eu nisi at elit fermentum aliquam. Interdum et malesuada fames ac ante
ipsum primis in faucibus.</p>
<p class="attribution">The images used on this page is downloaded from
<a href="https://pixabay.com">PixaBay.com</a> and used here under a CC0 (public domain) license.<br />
Links to the original images:
<a href="https://pixabay.com/en/cat-kitten-cute-sleeping-asleep-1941089/">super-mapio</a>,
<a href="https://pixabay.com/en/kitty-cat-kitten-pet-animal-cute-551554/">Ty Swartz</a>,
<a href="https://pixabay.com/en/kitty-cat-kitten-domestic-cat-2948404/">Ilona Ilyés</a>.
</p>
help_example/help/lorem.html
View file @ fc02514a
......@@ -3,11 +3,21 @@ dolor ligula. Suspendisse sollicitudin purus eget erat eleifend
faucibus. Mauris urna quam, tincidunt ut varius ac, fermentum
fermentum urna. Suspendisse potenti.</p>
<p>Donec ac sapien et metus rutrum scelerisque posuere eu
augue. Vivamus libero ipsum, imperdiet sed sollicitudin ut, suscipit
volutpat sapien. Nullam at massa non odio sodales pretium. In hac
habitasse platea dictumst. Nam accumsan suscipit ultrices. Fusce nec
dui auctor nisl pellentesque pellentesque. Fusce consequat lacus quis
tincidunt commodo. In mattis enim nec lorem blandit eleifend. In
semper, ante eget gravida porttitor, eros mauris pharetra massa, et
accumsan risus purus non arcu.</p>
<p>Breakout-box (<code>bob</code>) example:</p>
<pre>
&lt;p class="bob"&gt;Donec &hellip;&lt;/p&gt;
</pre>
<p>Renders as:</p>
<p class="bob">Donec ac sapien et metus rutrum scelerisque posuere eu
augue. Vivamus libero ipsum, imperdiet sed sollic tu din, suscipit
volutpat sapien.</p>
<p>Nullam at massa non odio sodales pretium. In hac habitasse platea
dictumst. Nam accumsan suscipit ultrices. Fusce nec dui auctor nisl
pellentesque pellentesque. Fusce consequat lacus quis tincidunt
commodo. In mattis enim nec lorem blandit eleifend. In semper, ante
eget gravida porttitor, eros mauris pharetra massa, et accumsan risus
purus non arcu.</p>
help_example/help_example.module
View file @ fc02514a
......@@ -4,6 +4,18 @@
* Provide example help for the advanced help module.
*/
/**
* Implements hook_admin_paths().
*
* Force help pages for this modile to be rendered in admin theme.
*/
function help_example_admin_paths() {
$paths = array(
'help/help_example/*' => TRUE,
);
return $paths;
}
/**
* Implements hook_menu().
*/
......@@ -22,13 +34,60 @@ function help_example_menu() {
* Topic index callback.
*/
function help_example_index_page() {
// Create the question mark icon.
$output = theme('advanced_help_topic', array(
$output = '<p>' . t('Read the source code of the module <strong>Help example</strong> to learn how to create themed and plain links to help topics, and how to render help in the adminstrative theme.') . '</p>';
$output .= '<p>' . t('Two popup examples:') . '<br />';
// Create the question mark icon for the topic.
$toc_qm = theme('advanced_help_topic', array(
'module' => 'help_example',
'topic' => 'toc',
'type' => 'icon',
));
// Append some explanatory text.
$output .= $toc_qm . '&nbsp;' . t('Click the help icon on the left to view a popup of the example module index page.');
$output .= '<br />';
$topic_qm = theme('advanced_help_topic', array(
'module' => 'help_example',
'topic' => 'about-example',
'type' => 'icon',
));
$output .= $topic_qm . '&nbsp;' . t('Click the help icon on the left to view a popup of the first help topic.');
// Create the question mark icon for the topic.
$toc_qm = theme('advanced_help_topic', array(
'module' => 'help_example',
'topic' => 'toc',
'type' => 'icon',
));
// Append some explanatory text.
$output .= '&nbsp;' . t('Click the help icon on the left to view a popup help page.');
$output .= '</p>';
$output .= '</p>';
$topic_title = theme('advanced_help_topic', array(
'module' => 'help_example',
'topic' => 'lorem',
'type' => 'title',
));
$output .= t('Link to a popup of the topic with the title: ') . $topic_title . '.';
$output .= '</p>';
$output .= '</p>';
$topic_title = theme('advanced_help_topic', array(
'module' => 'help_example',
'topic' => 'etiam',
'type' => 'anchor text',
));
$output .= t('Link to a popup of the third topic with user defined ') . $topic_title . '.';
$output .= '</p>';
$output .= '<p>' . t('Examples of unthemed links to help pages:') . '<br />';
$output .= t('Link to <a href="@url">the example module index page</a>.<br />', array('@url' => '/admin/help/ah/help_example'));
$output .= t('Link to the <a href="@url">first help topic</a>.', array('@url' => '/help/help_example/about-example'));
$output .= '</p>';
return $output;
}