Smarter Help display

[jproctor]

In my test environment, I didn’t have the A11yFormat plugin in the toolbar, which means its help text was about functionality that my users could never see.

So I had the idea to provide only the help sections relevant to the current toolbar. I started with this change to src/Plugin/CKEditorPlugin/A11yFirstHelp.php:

  function getConfig(Editor $editor) {
    $settings = $editor->getSettings();

    $buttons = $this->whichButtons($settings);
    $topic_data = [
      'A11yFirstHelp' => ['label' => 'aboutA11yFirst', 'option' => 'aboutA11yFirst'],
      'BlockFormat' => ['label' => 'blockFormatHelp', 'option' => 'BlockFormatHelp'],
      'Heading' => ['label' => 'headingHelp', 'option' => 'HeadingHelp'],
      'InlineStyle' => ['label' => 'inlineStyleHelp', 'option' => 'InlineStyleHelp'],
      'Link' => ['label' => 'linkHelp', 'option' => 'LinkHelp'],
    ];
    $help_topics = [];
    foreach ($buttons as $button) {
      $data = $topic_data[$button];
      $help_topics[$data['label']] = ['option' => $data['option']];
    }

    // The plugin code is expecting this data structure.
    $config = ['a11yFirstHelpTopics' => $help_topics];
    if (isset($settings['plugins']['a11yfirsthelp'])) {
      $config['a11yfirst'] = $settings['plugins']['a11yfirsthelp'];
    }
    return $config;
  }

  /**
   * Identifies which of the other A11yFirst buttons are currently active.
   *
   * @param array $settings
   *   The "styles" setting.
   * @return array
   *   An array containing the enabled A11yFirst buttons.
   */
  protected function whichButtons(array $settings) {
    $a11yfirst = ['A11yFirstHelp', 'BlockFormat', 'Heading', 'InlineStyle'];
    $buttons = [];
    foreach ($settings['toolbar']['rows'] as $row_number => $row) {
      foreach ($row as $group) {
        foreach ($group['items'] as $button_name) {
          if (in_array($button_name, $a11yfirst)) {
            $buttons[] = $button_name;
          }
        }
      }
    }
    return $buttons;
  }

(Yes, if you look carefully, Link would always be excluded. I don’t know whether CKEditor’s native Link is what’s described by the Link section of the help, but it definitely didn’t match DrupalLink’s UI. I have other thoughts about DrupalLink, but I am not likely to fix that any time soon.)

That succeeded in changing the items in the A11yFirst Help button, but not the dialog itself. Worse, it broke the dialog: all of the help was presented as one long document, and the buttons didn’t work. None of the changes I tried in js/plugins/a11yfirsthelp/dialogs/a11first-help.js, including completely commenting out the stuff I was intending to skip, fixed it.

It made me wonder if there’s some value in something more like an API model here: the various plugins register their own help text when they’re active, rather than centralizing it. Or some hybrid approach, where the text is still centralized (it’s good text!), but BlockFormatHelp and LinkHelp are buried a layer deeper or something like that. Either way that’s a huge change to propose on code I don’t maintain (or, arguably, understand), so I’m creating this issue as a way to offload thinking about it until later. :)