admin_toolbar-8.x-2.x-dev/admin_toolbar_search/admin_toolbar_search.module

<?php

/**
 * @file
 * Integration of a JS autocomplete search text field in the admin toolbar.
 */

use Drupal\admin_toolbar_search\Constants\AdminToolbarSearchConstants;
use Drupal\Core\Url;

/**
 * Implements hook_help().
 */
function admin_toolbar_search_help($route_name) {
  switch ($route_name) {
    // Main user documentation page for the Admin Toolbar Search module.
    case 'help.page.admin_toolbar_search':
      $output = '';
      $output .= '<h3>' . t('About') . '</h3>';
      $output .= '<p>' . t('Type text to quickly search for menu links in the Admin Toolbar!<br/>') . '</p>';
      $output .= '<p>' . t('The Admin Toolbar Search module adds an easy-to-use JS autocomplete filter of the links in the Administration menu.<br/>It is very convenient for finding quickly an administration configuration page without knowing where its menu link could be in the Administration dropdown menu or the organization of the site.') . '</p>';

      return $output;
  }
}

/**
 * Implements hook_toolbar().
 *
 * Inject the admin toolbar search JS autocomplete text field in the Toolbar,
 * either directly or as a toolbar item tab with a tray ('display_menu_item').
 * Add the necessary CSS classes, HTML IDs and load required JS libraries and
 * settings.
 *
 * Provide support for mobile devices by adding a mobile search tab that
 * displays the search field in a custom tray when the toolbar width is below
 * 769px.
 * Note the display styles for mobile devices is still different depending on
 * whether the 'display_menu_item' setting is enabled or not.
 */
function admin_toolbar_search_toolbar() {
  // Load the admin toolbar search only if the user has the required permission.
  if (!\Drupal::currentUser()->hasPermission('use admin toolbar search')) {
    return [];
  }
  // Check if the Admin Toolbar Tools module is enabled to load extra links.
  $admin_toolbar_tools_enabled = \Drupal::service('module_handler')
    ->moduleExists('admin_toolbar_tools');

  // Load the Admin Toolbar Search settings from the configuration.
  $admin_toolbar_search_settings = \Drupal::config('admin_toolbar_search.settings');
  // Get the 'display_menu_item' setting to determine if the search field is
  // displayed directly in the toolbar or in a tray under a menu item tab.
  $display_menu_item = $admin_toolbar_search_settings->get('display_menu_item');
  // Admin Toolbar Search field default label, title and placeholder text.
  $search_field_title = t('Search');
  $search_field_placeholder = t('Search for menu links');
  $search_field_title_attribute = t('Type text to search for menu links in the admin toolbar.');

  // Render array of properties for the admin search tab menu link, when it is
  // *not* displayed directly in the toolbar or as a fallback for mobile search.
  $administration_search_tab_link = [
    '#type' => 'link',
    '#title' => $search_field_title,
    // Since the search field is handled with JS, the tab does not need a link.
    '#url' => Url::fromRoute('<nolink>'),
    '#attributes' => [
      'class' => [
        'toolbar-icon',
      ],
    ],
  ];
  // Render array of properties for the admin toolbar search JS autocomplete
  // input text field.
  $administration_search_field = [
    'search' => [
      // Define a form element of type 'search' to get HTML5 features.
      '#type' => 'search',
      // Set field HTML attributes: ID, label, title, placeholder text and size.
      '#id' => AdminToolbarSearchConstants::ADMIN_TOOLBAR_SEARCH_HTML_IDS['search_input'],
      '#title' => $search_field_title,
      '#placeholder' => $search_field_placeholder,
      '#attributes' => [
        'title' => $search_field_title_attribute,
      ],
      // Default size of the search input field when displayed in the tray.
      // The size is reduced when displayed directly in the toolbar.
      '#size' => 60,
    ],
  ];

  // Add the admin toolbar search as a toolbar item render array.
  $items['administration_search'] = [
    '#type' => 'toolbar_item',
    // Set the ID of the HTML element wrapping the toolbar item.
    '#wrapper_attributes' => [
      'id' => AdminToolbarSearchConstants::ADMIN_TOOLBAR_SEARCH_HTML_IDS['search_tab'],
    ],
    // Load the required JS library and settings by default.
    '#attached' => [
      'library' => [
        'admin_toolbar_search/search',
      ],
      // Add a setting to determine if extra links should be loaded via AJAX.
      'drupalSettings' => [
        'adminToolbarSearch' => [
          'loadExtraLinks' => $admin_toolbar_tools_enabled,
        ],
      ],
    ],
    // Ensure the toolbar item is rebuilt when the user permissions or module's
    // settings change and keep this render array cached.
    '#cache' => [
      'contexts' => [
        'user.permissions',
      ],
      'tags' => [
        'config:admin_toolbar_search.settings',
      ],
    ],
  ];

  // Add the keyboard shortcut library if enabled ('enable_keyboard_shortcut').
  if ($admin_toolbar_search_settings->get('enable_keyboard_shortcut')) {
    $items['administration_search']['#attached']['library'][] = 'admin_toolbar_search/search.keyboard_shortcut';
    // The display menu item setting is used to determine if the search input
    // should be displayed as a menu item or directly in the toolbar.
    $items['administration_search']['#attached']['drupalSettings']['adminToolbarSearch']['displayMenuItem'] = $display_menu_item;

    // Add the keyboard shortcut label to the search field placeholder and
    // title attributes.
    $search_keyboard_shortcut_label = t('Alt + a');
    $administration_search_field['search']['#placeholder'] .= ' (' . $search_keyboard_shortcut_label . ')';
    $administration_search_field['search']['#attributes']['title'] = t('Keyboard shortcut: @shortcut_label', [
      '@shortcut_label' => $search_keyboard_shortcut_label,
    ]);
  }

  // Build the toolbar item depending on the whether it is displayed as a menu
  // item with a tray or directly in the toolbar ('display_menu_item' setting).
  if ($display_menu_item) {
    // The search field is displayed in a specific Tray under the Search Tab.
    $items['administration_search'] += [
      'tab' => $administration_search_tab_link,
      'tray' => $administration_search_field,
    ];
  }
  else {
    // Reduce the size and hide the label of the search input field.
    $administration_search_field['search']['#title_display'] = 'invisible';
    $administration_search_field['search']['#size'] = 30;

    // The search field is displayed directly in the Toolbar without a tray.
    $items['administration_search'] += [
      '#weight' => 110,
      'tab' => $administration_search_field,
    ];

    // Add toolbar item render array for the mobile search tab that displays the
    // search field in a custom tray, see module's CSS for styling. The display
    // of the mobile search tab is toggled with a CSS breakpoint at 769px.
    $items['administration_mobile_search'] = [
      '#type' => 'toolbar_item',
      'tab' => $administration_search_tab_link,
      // It is important the mobile search tab is displayed *before* the search
      // toolbar item otherwise module's CSS rules will not work.
      '#weight' => $items['administration_search']['#weight'] - 1,
      // Set the ID of the HTML element wrapping the toolbar item.
      '#wrapper_attributes' => [
        'id' => AdminToolbarSearchConstants::ADMIN_TOOLBAR_SEARCH_HTML_IDS['search_tab_mobile'],
      ],
    ];
  }

  return $items;

}