Note: Some of these settings has
regressions when compared to the Drupal 7 version of this module. This
page also serves as a reminder about known regressions.
The name of the Advanced Help configuration file is the machine
name of the extension it provides help for, followed by
.help.yml
.
The configuration file starts with an optional section for global
settings that will be inherited by each help topic, followed by
sections with settings for each help topic.
Global settings may be put into a section named advanced help
settings
. This means that this name is reserved and it cannot
be a topic identifier. The following settings may be set in this
section, with the default value (if any) in brackets.
show readme
(false)
- For extensions that provide advanced help by means of help topics,
the default is to hide the README-file that comes with the
extension. Setting this true will show the extension's README along
with the topics. The weight for the READE will fixed at -99.
line break
(false)
- If set, the line break filter will be applied to all help topics
defined by this extension (unless overridden). When enabled (true),
the line break filter converts line breaks into
<br>
and <p>
tags. The default (false) is
to not convert line breaks into markup, so that formatting a
help topic with lines that have maximum 80 characters will not result
in a rendering of the topic with a forced line break after 80
characters.
navigation
(true)
- Navigation will be displayed at the end of each help page:
previous page, Up (parent), next page.
Setting this false turns this feature off.
hide
(false)
- This may be used to hide a extension in the list of extensions for
which help is available. This is particularly useful for extensions
thet insert their help topics into the hierarchy of another extension,
as might be done by those that extend Views or themes
that extend base themes like Zen. By setting this to
true the extension will not appear as its own entry.
Settings that need to be ported to work with the D9/10 version:
name
- May be set to override the extension's name given in
its
.info.yml
. It will be displayed on both the list of
extensions with help available and the extension's TOC page. Usually,
this is not set, but for some extensions you may want to use a more
friendly name than appears in the extension's .info.yml
file. [Regressions: Not sorted correctly on "Extensions with help
available" page. Not used in the title for the extension's TOC
page.]
css
- Specify a css file that will be used for all help topics (unless
overridden), including the .css extension. This .css file must reside
in the help directory along with the .html files, and will not be
affected by translation.
Each section after that will correspond to a single help topic. It
starts with the topic identifier not indented, followed with a list of
keys and values indented two spaces. The following keys may be set for
each topic, with the default value (if any) in brackets.
title
- The title of the topic, presented to the user and used in
links. If you have special characters in your title, be sure to
enclose it in quotes. (This setting is currently not optional.)
file
- The name of the file that contains the help text for the
topic. This is optional. If not specified, the topic identifier will
be the used, with the extension .html .md or .txt.
weight
(0)
- The weight, used for sorting help topics on the TOC page for the
extension. The default is 0 (zero) if unspecified. Topics with the
same weight are sorted alphabetically.
parent
- The topic identifier to use in a hierarchy; children will be
listed beneath parents in the TOC, and will have the parent in
their breadcrumb trail. You may parent this topic to a
topic in another extension by using
module%topic
or theme%topic
as the identifier,
where module
or theme
is the extension's short
name. For example if parent is set to, 'views%display
',
the topic will be regarded as a child of the
display
topic in the Views module.
[Regressions: No breadcrumb. Double bullets and parent also indented.]
line break
- Set the line break filter for this topic only (true or
false). This will override any global line break setting.
css
- Specify a css file that will be used for this file. This .css file
must reside in the help directory along with the .html files. This
will replace any .css file added in the global setting.
[Regression: Has no effect.]
popup width
(500)
- The width in pixels of the popup window.
[Regression: Requires theme function to work.]
popup height
(500)
- The height in pixels of the popup window.
[Regression: Requires theme function to work.]
For an example, examine the help_example.help.yml
file
that comes with the submodule Help Example.