Commit 92787ef8 authored by webchick's avatar webchick

Issue #2897272 by tedbow, Wim Leers, Jo Fitzgerald, Adita, xjm: Fix module...

Issue #2897272 by tedbow, Wim Leers, Jo Fitzgerald, Adita, xjm: Fix module description, hook_help(), and document module scope in *.api.php file
parent c1df3d2b
......@@ -10,9 +10,28 @@
* @{
* Settings Tray API
* @section sec_overview Overview and terminology
* The Settings Tray module allows blocks to be configured in a sidebar form
* without leaving the page. For example:
* - For every block, one can configure whether to display the block title or
* not, and optionally override it (block configuration).
* - For menu blocks, one can configure which menu levels to display (block
* configuration) but also the menu itself (menu configuration).
* - For the site branding block, one can change which branding elements to
* display (block configuration), but also the site name and slogan (simple
* configuration).
* Block visibility conditions are not included the sidebar form.
* @section sec_api The API: the form in the Settings Tray
* By default, every block will show its built-in form in the Settings Tray.
* By default, the Settings Tray shows any block's built-in form in the
* off-canvas dialog.
* @see core/misc/dialog/off-canvas.es6.js
* However, many blocks would benefit from a tailored form which either:
* - limits the form items displayed in the Settings Tray to only items that
* affect the content of the rendered block
......@@ -32,19 +51,19 @@
* @endcode
* In some cases, a block's content is not configurable (for example, the title,
* main content, and help blocks). Such blocks can opt out of providing an
* off-canvas form:
* main content, and help blocks). Such blocks can opt out of providing a
* settings_tray form:
* @code
* forms = {
* "settings_tray" = FALSE,
* },
* @endcode
* Finally, blocks that do not specify an off-canvas form using the annotation
* Finally, blocks that do not specify a settings_tray form using the annotation
* above will automatically have it set to their plugin class. For example, the
* "Powered by Drupal" block plugin
* (\Drupal\system\Plugin\Block\SystemPoweredByBlock) automatically gets
* this added to its annotation:
* (\Drupal\system\Plugin\Block\SystemPoweredByBlock) automatically gets this
* added to its annotation:
* @code
* forms = {
* "settings_tray" = "\Drupal\system\Plugin\Block\SystemPoweredByBlock",
name: 'Settings Tray'
type: module
description: 'Provides the ability to change the most common configuration from the Drupal front-end.'
description: 'Provides a sidebar to configure blocks on the page.'
package: Core (Experimental)
version: VERSION
core: 8.x
......@@ -7,6 +7,7 @@
use Drupal\Core\Asset\AttachedAssetsInterface;
use Drupal\Core\Routing\RouteMatchInterface;
use Drupal\Core\Url;
use Drupal\settings_tray\Block\BlockEntityOffCanvasForm;
use Drupal\settings_tray\Form\SystemBrandingOffCanvasForm;
use Drupal\settings_tray\Form\SystemMenuOffCanvasForm;
......@@ -18,10 +19,15 @@ function settings_tray_help($route_name, RouteMatchInterface $route_match) {
switch ($route_name) {
case '':
$output = '<h3>' . t('About') . '</h3>';
$output .= '<p>' . t('The Settings Tray module provides an \'edit mode\' in which clicking on a block opens a slide-out tray which allows configuration to be altered without leaving the page.For more information, see the <a href=":settings-tray-documentation">online documentation for the Settings Tray module</a>.', [':settings-tray-documentation' => '']) . '</p>';
$output .= '<p>' . t('The Settings Tray module allows users with the <a href=":administer_block_permission">Administer blocks</a> and <a href=":contextual_permission">Use contextual links</a> permissions to edit blocks without visiting a separate page. For more information, see the <a href=":handbook_url">online documentation for the Settings Tray module</a>.', [':handbook_url' => '', ':administer_block_permission' => \Drupal::url('user.admin_permissions', [], ['fragment' => 'module-block']), ':contextual_permission' => \Drupal::url('user.admin_permissions', [], ['fragment' => 'module-contextual'])]) . '</p>';
$output .= '<h3>' . t('Uses') . '</h3>';
$output .= '<dl>';
$output .= '<dt>' . t('Editing blocks on the same page in the slide-out tray') . '</dt>';
$output .= '<dt>' . t('Editing blocks in place') . '</dt>';
$output .= '<dd>';
$output .= '<p>' . t('To edit blocks in place, either click the <strong>Edit</strong> button in the toolbar and then click on the block, or choose "Quick edit" from the block\'s contextual link. (See the <a href=":contextual">Contextual Links module help</a> for more information about how to use contextual links.)', [':contextual' => \Drupal::url('', ['name' => 'contextual'])]) . '</p>';
$output .= '<p>' . t('The Settings Tray for the block will open in a sidebar, with a compact form for configuring what the block shows.') . '</p>';
$output .= '<p>' . t('Save the form and the changes will be immediately visible on the page.') . '</p>';
$output .= '</dd>';
$output .= '</dl>';
return ['#markup' => $output];
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment