Help text standards

Last updated on
23 November 2016

Where is help displayed?

Help and other explanatory texts of a module can be displayed to users of your site at four different places.

  1. Short description of what the module does. It is displayed on the Extend or Modules page (in Drupal 8 or 7). It is the only texts users will see if the module is not enabled yet.
  2. Description on links are displayed with the links on the Configuration and Structure pages and invite users to do something.
  3. Explanations on the administration pages. Ideally this should not be needed, but if they do they are short and do not duplicate the help page.
  4. Help page displayed by the Help module with three sections: What does the module do, what can users do with it, and a link to the online documentation here on drupal.org. This hook_help() text is in the my_module.module file.

1. Short Description

The short description is set in the description element of:

  • Drupal 8: my_module.info.yml file
  • Drupal 7: my_module.info file

This description is displayed in the list of available modules on the Extend (D8) or Modules (D7) page to tell site builders what the module does, before they enable it.
The description starts with a verb and should be short and concise.

Examples

  • Help Manages the display of online help.
  • Content Translation Allows users to translate content entities.
  • Datetime Defines datetime form elements and a datetime field type.
    description: Defines datetime form elements and a datetime field type.

2. Descriptions on links

The description on links is set in the description element of:

  • Drupal 8: my_module.links.menu.yml file

Descriptions on links are displayed on overview pages such as the Configuration and Structure pages of your site. They often invite the user to do certain tasks.
The description starts with a verb and should be short and concise.

Examples

  • Cron
    Manage automate site maintenance tasks.
  • Contact formats
    Create and manage contact forms.
    
    
    title: 'Contact forms' 
    description: 'Create and manage contact forms.'

3. Help text on administration pages

Modules can provide help text to users on individual paths (administration pages, such as setting pages, editing forms, etc.), indexed by the path to the page.
The text is displayed by implementing hook_help() in the my_module.module file.

Help text on administration pages is generally fairly brief. It is displayed either at the top of the page or in a block, depending on the version and/or theme.

You should follow the guidelines for user interface text in general: https://drupal.org/node/604342, and in particular:

  • Keep introductions as short as possible, and don’t describe options in detail. Ideally no introduction should be necessary because the screen and its behavior should be intuitive.
  • Do not describe default user interface usage/behavior (drag-and-drop etc.).

The format of the path where the help text is displayed - defined in the case element - is different between Drupal 7 and 8.
For Drupal 8, use the Drupal route as configured in my_module.routing.yml

Examples


// Drupal 7 
case 'node/%/revisions': 
  return '<p>' . t('Revisions allow you to track differences between multiple versions of your content, and revert back to older versions.') . '</p>'; 

//Drupal 8 
case 'node.revision_overview': 
  return '<p>' . t('Revisions allow you to track differences between multiple versions of your content, and revert back to older versions.') . '</p>'; 

4. Help page

Modules can also provide text for an overview help page by implementing hook_help() in the my_module.module file. A special path 'admin/help#modulename' (Drupal6,7) 'help.page.modulename' (Drupal8) should be used to define this page.
This help hook depends on the Help module to display the page.

See the code example for details of the function itself.

The overview help page should follow a standard structure.

  1. About section , giving a brief overview of what the module does, starting with text like "The Foo Bar module [verb]", and finishing with a standardized link to the module's online documentation.
  2. Uses section, giving details of module functionality and explaining what users can do, and links to the URLs where each specific functionality can be accessed.

You should follow the guidelines for user interface text in general: https://drupal.org/node/604342, and in particular:

  • Capitalize the name of the module, because module names are proper nouns.
  • Make sure that titles of links to administration pages and tabs are identical to the page and tab titles.
  • Do not refer to Drupal but rather to your website or similar, because the module might be used in other distributions and the user might not be aware that they are using Drupal.

Links in the help text use placeholders, and the url() function in D7and Drupal::url() in D8.

Example


t('In order to translate content, the website must have at least two <a href=":url">languages</a>. When that is the case, you can enable translation for the desired content entities on the <a href=":translation-entity">Content language</a> page. When enabling translation you can choose the default language for content and decide whether to show the language selection field on the content editing forms.', 
array(
  ':url' => \Drupal::url('entity.configurable_language.collection'),
  ':translation-entity' => \Drupal::url('language.content_settings_page'),
  ':language-help' => \Drupal::url('help.page', array('name' => 'language'))
)) 

See below for a explanations about links and a detailed example of a help page for Drupal 8 and 7.

Drupal 8 note about url() and routing

Note: In Drupal 8, the placeholder now needs to start with a : instead of !

Converting url() in D7 to Drupal::url() in D8

The url() function is deprecated in Drupal 8 so changes are required when porting a module from Drupal 7.

  1. For full URLs, such as https://drupal.org/documentation/module/my_module -- nothing changes.
  2. For URLs to other modules' help files, replace
    
    
    // Drupal 7 
    url('admin/help/foo_module')

    with

    
    
    // Drupal 8 
    \Drupal::url('help.page', array('name' => 'foo_module'))
  3. For URLs to other admin pages, you need to know the "route machine name" of the URL to use it in the Drupal::url() function.
    For instance, if you have a link to this Views admin page in your Drupal 7 module,
    
    
    // Drupal 7 
    url('admin/structure/views')

    then you find the route machine name in Drupal 8 in the Views UI views_ui.routing.yml file.

    
    
    entity.view.collection: 
      path: '/admin/structure/views'

    This defines the machine name for the path admin/structure/views page as "entity.view.collection", so you can convert the url() function call in your Drupal 8 as

    // Drupal 8 
    \Drupal::url('entity.view.collection')

Linking to help pages

Why is there a difference between linking to admin/help/module and admin/structure/views URLs?
The route entry in help.routing.yml for the admin/help/(module_name) pages is:

help.page: 
  pattern: 'admin/help/{name}' 

If you want to make a URL for the Field module help, you need to set "{name}" to "field", which is the machine name of the Field module:


\Drupal::url('help.page', array('name' => 'field')) 

If you need to make a link to a similar path that has variables in the "pattern" line, you can follow the same rules.
For instance, from views_ui.routing.yml again:


views_ui.edit: 
  pattern: '/admin/structure/views/view/{view}' 

This means that the URL call for admin/structure/views/view/my_view_name is:


\Drupal::url('views_ui.edit', array('view' => 'my_view_name')) 

Example for a Help page

Here is an example of an overview page from the Content Translation module in Drupal 7 and 8, only showing the first two Uses here.

1. Code

This is the hook_help() section in the content_translation.module file.

1.1 Code in Drupal 8


// Drupal 8 
case 'help.page.content_translation':
  $output = ''; 
  $output .= '<h3>' . t('About') . '</h3>';
  $output .= '<p>' . t('The Content Translation module allows you to translate content, comments, custom blocks, taxonomy terms, users and other <a href=":field_help" title="Field module help, with background on content entities">content entities</a>. Together with the modules <a href=":language">Language</a>, <a href=":config-trans">Configuration Translation</a>, and <a href=":locale">Interface Translation</a>, it allows you to build multilingual websites. For more information, see the <a href=":translation-entity">online documentation for the Content Translation module</a>.', 
    array(
      ':locale' => (\Drupal::moduleHandler()->moduleExists('locale')) ? \Drupal::url('help.page', array('name' => 'locale')) : '#',
      ':config-trans' => (\Drupal::moduleHandler()->moduleExists('config_translation')) ? \Drupal::url('help.page', array('name' => 'config_translation')) : '#',
      ':language' => \Drupal::url('help.page', array('name' => 'language')), 
      ':translation-entity' => 'https://www.drupal.org/documentation/modules/translation',
      ':field_help' => \Drupal::url('help.page', array('name' => 'field'))
    )) 
    . '</p>';
  $output .= '<h3>' . t('Uses') . '</h3>';
  $output .= '<dl>';
  $output .= '<dt>' . t('Enabling translation') . '</dt>';
  $output .= '<dd>' . t('In order to translate content, the website must have at least two <a href=":url">languages</a>. When that is the case, you can enable translation for the desired content entities on the <a href=":translation-entity">Content language</a> page. When enabling translation you can choose the default language for content and decide whether to show the language selection field on the content editing forms.', 
    array(
      ':url' => \Drupal::url('entity.configurable_language.collection'),
      ':translation-entity' => \Drupal::url('language.content_settings_page'),
      ':language-help' => \Drupal::url('help.page', array('name' => 'language'))
    ))
    . '</dd>';
  $output .= '<dt>' . t('Enabling field translation') . '</dt>';
  $output .= '<dd>' . t('You can define which fields of a content entity can be translated. For example, you might want to translate the title and body field while leaving the image field untranslated. If you exclude a field from being translated, it will still show up in the content editing form, but any changes made to that field will be applied to <em>all</em> translations of that content.') . '</dd>';
  $output .= '</dl>'; 
  return $output; 

1.2 Code in Drupal 7


// Drupal 7:
case 'admin/help#translation':

  $output = '';
  $output .= '<h3>' . t('About') . '</h3>';
  $output .= '<p>' . t('The Content Translation module allows content to be translated into different languages. Working with the <a href="!locale">Locale module</a> (which manages enabled languages and provides translation for the site interface), the Content Translation module is key to creating and maintaining translated site content. For more information, see the <a href="!translation">online documentation for the Content Translation module</a>.',
    array(
      '!locale' => \Drupal::url('help.page', array('name' => 'locale')),
      '!translation' => 'https://drupal.org/documentation/modules/translation/'
    ))
  . '</p>';
  $output .= '<h3>' . t('Uses') . '</h3>'; 
  $output .= '<dl>';
  $output .= '<dt>' . t('Configuring content types for translation') . '</dt>';
  $output .= '<dd>' . t('To configure a particular content type for translation, visit the <a href="!content-types">Content types</a> page, and click the <em>edit</em> link for the content type. In the <em>Publishing options</em> section, select <em>Enabled, with translation</em> under <em>Multilingual support</em>.',
    array(
      '!content-types' => \Drupal::url('node.overview_types')
    ))
  . '</dd>';
  $output .= '<dt>' . t('Assigning a language to content') . '</dt>';
  $output .= '<dd>' . t('Use the <em>Language</em> drop down to select the appropriate language when creating or editing content.') . '</dd>'; 
  $output .= '</dl>'; 
  return $output; 

2. HTML

The code above is converted to this HTML.


<h3>About</h3> 
<p>
The Content Translation module allows you to translate content, comments, custom blocks, taxonomy terms, users and other <a href="/admin/help/field" title="Field module help, with background on content entities">content entities</a>. Together with the modules <a href="/admin/help/language">Language</a>, <a href="#">Configuration Translation</a>, and <a href="#">Interface Translation</a>, it allows you to build multilingual websites. For more information, see the <a href="https://www.drupal.org/documentation/modules/translation">online documentation for the Content Translation module</a>.
</p>
<h3>Uses</h3>
<dl>
  <dt>Enabling translation</dt>
  <dd>In order to translate content, the website must have at least two <a href="/admin/config/regional/language">languages</a>. When that is the case, you can enable translation for the desired content entities on the <a href="/admin/config/regional/content-language">Content language</a> page. When enabling translation you can choose the default language for content and decide whether to show the language selection field on the content editing forms.</dd>
 <dt>Enabling field translation</dt>
 <dd>You can define which fields of a content entity can be translated. For example, you might want to translate the title and body field while leaving the image field untranslated. If you exclude a field from being translated, it will still show up in the content editing form, but any changes made to that field will be applied to <em>all</em> translations of that content.
  </dd>
</dl> 

3. Display

The HTML is then rendered like this, and links to the administration pages of the module are added automatically.
NOTE: Internal links shown here are what you would see on a site. Please do not edit the output below. The links are NOT MEANT TO WORK here!

About

The Content Translation module allows you to translate content, comments, custom blocks, taxonomy terms, users and other content entities. Together with the modules Language, Configuration Translation, and Interface Translation, it allows you to build multilingual websites. For more information, see the online documentation for the Content Translation module.

Uses

Enabling translation

In order to translate content, the website must have at least two languages. When that is the case, you can enable translation for the desired content entities on the Content language page. When enabling translation you can choose the default language for content and decide whether to show the language selection field on the content editing forms.

Enabling field translation

You can define which fields of a content entity can be translated. For example, you might want to translate the title and body field while leaving the image field untranslated. If you exclude a field from being translated, it will still show up in the content editing form, but any changes made to that field will be applied to all translations of that content.

Content Translation administration pages