Remove theme_more_help_link() and replace with a #type link render array

giving it a whirl

Looked for the More Help link on the Forum setting page (forum#overlay=admin/structure/forum).

Found it and the link worked.

+++ b/core/modules/forum/forum.moduleundefined
@@ -44,7 +44,19 @@ function forum_help($path, $arg) {
+        '#children' =>  drupal_render($more_help_link),

Extra space between => and drupal_render().

Otherwise looks good I think :)

Thanks for testing @ericrdb!

This issue was RTBC and passing tests on July 1, the beginning of API freeze.

Committed/pushed to 8.x, thanks!

follow-up: #2043649: Make all #type 'link' arrays 100% renderable, use #theme_wrappers if necessary

I am going to write the API change notification.

• Removes theme_more_help_link() from theme.inc.
• Removes theme() call on 'more_help_link' in forum_help() from forum.module.
• Adds a render array to forum_help()
• Removes theme_more_help_link() from Docblock of the 'more-help-link' class declaration in system.theme.css

core/includes/theme.inc

Before:

function theme_item_list($variables) {
 }

 /**
 * Returns HTML for a "more help" link.
 *
 * @param $variables
 *   An associative array containing:
 *   url: The URL for the link.
 */
function theme_more_help_link($variables) {
  return '<div class="more-help-link">' . l(t('More help'), $variables['url']) . '</div>';
}

/**
  * Returns HTML for a feed icon.
  *
  * @param $variables
  */
function drupal_common_theme() {
  'item_list' => array(
    'variables' => array('items' => array(), 'title' => '', 'list_type' => 'ul', 'attributes' => array()),
      ),
    'more_help_link' => array(
      'variables' => array('url' => NULL),
        ),
    'feed_icon' => array(
      'variables' => array('url' => NULL, 'title' => NULL),
        ),

After:

function theme_item_list($variables) {
 }

 /**
  * Returns HTML for a feed icon.
  *
  * @param $variables
  */
function drupal_common_theme() {
  'item_list' => array(
    'variables' => array('items' => array(), 'title' => '', 'list_type' => 'ul', 'attributes' => array()),
    ),
  'feed_icon' => array(
    'variables' => array('url' => NULL, 'title' => NULL),
    ),

core/modules/forum/forum.module

Before:

function forum_help($path, $arg) {
       return $output;
     case 'admin/structure/forum':
       $output = '<p>' . t('Forums contain forum topics. Use containers to group related forums.') . '</p>';
     $output .= theme('more_help_link', array('url' => 'admin/help/forum'));
       return $output;
     case 'admin/structure/forum/add/container':
       return '<p>' . t('Use containers to group related forums.') . '</p>';

After:

function forum_help($path, $arg) {
  return $output;
  case 'admin/structure/forum':
  $output = '<p>' . t('Forums contain forum topics. Use containers to group related forums.') . '</p>';

  $more_help_link = array(
    '#type' => 'link',
    '#href' => 'admin/help/forum',
    '#title' => t('More help'),
  );
  $container = array(
    '#theme' => 'container',
    '#children' => drupal_render($more_help_link),
    '#attributes' => array(
      'class' => array('more-help-link'),
    ),
  );
  $output = drupal_render($container);
  return $output;
  case 'admin/structure/forum/add/container':
  return '<p>' . t('Use containers to group related forums.') . '</p>';

core/modules/system/css/system.theme.css

Before:

abbr.form-required,
abbr.tabledrag-changed,
abbr.ajax-changed {
}

/**
* Markup generated by theme_more_help_link().
*/
.more-help-link {
  text-align: right; /* LTR */

After:

abbr.form-required,
abbr.tabledrag-changed,
abbr.ajax-changed {
 }

/**
* More help link style.
*/
.more-help-link {
  text-align: right; /* LTR */<?php

That's quite thorough @rabellamy! I'm thinking we should slim it down and focus on what a module or theme developer previously using this theme hook will need to know. If someone wants every last detail they can always come back to this issue, read the comments, and look at the patch.

Here are a couple examples of theme function removal change notices, they are not exactly the same as this case but good to look at to get an idea of what this could look like.

https://drupal.org/node/2019739
https://drupal.org/node/1987618

Thanks for working on this, looking forward to seeing the next draft!

• Removes theme_more_help_link() from theme.inc.
• Removes theme() call on 'more_help_link' and adds a #type link render array to forum_help() in forum.module.

core/includes/theme.inc
Before (D7)

 /**
 * Returns HTML for a "more help" link.
 *
 * @param $variables
 *   An associative array containing:
 *   url: The URL for the link.
 */
function theme_more_help_link($variables) {
  return '<div class="more-help-link">' . l(t('More help'), $variables['url']) . '</div>';
}

/**
  * Returns HTML for a feed icon.
  *
  * @param $variables
  */
function drupal_common_theme() {
  'item_list' => array(
    'variables' => array('items' => array(), 'title' => '', 'list_type' => 'ul', 'attributes' => array()),
      ),
    'more_help_link' => array(
      'variables' => array('url' => NULL),
        ),
    'feed_icon' => array(
      'variables' => array('url' => NULL, 'title' => NULL),
        ),

After (D8)

function theme_item_list($variables) {
 }

 /**
  * Returns HTML for a feed icon.
  *
  * @param $variables
  */
function drupal_common_theme() {
  'item_list' => array(
    'variables' => array('items' => array(), 'title' => '', 'list_type' => 'ul', 'attributes' => array()),
    ),
  'feed_icon' => array(
    'variables' => array('url' => NULL, 'title' => NULL),
    ),

core/modules/forum/forum.module
Before (D7)

function forum_help($path, $arg) {
       return $output;
     case 'admin/structure/forum':
       $output = '<p>' . t('Forums contain forum topics. Use containers to group related forums.') . '</p>';
     $output .= theme('more_help_link', array('url' => 'admin/help/forum'));
       return $output;
     case 'admin/structure/forum/add/container':
       return '<p>' . t('Use containers to group related forums.') . '</p>';

After (D8)

function forum_help($path, $arg) {
  return $output;
  case 'admin/structure/forum':
  $output = '<p>' . t('Forums contain forum topics. Use containers to group related forums.') . '</p>';

  $more_help_link = array(
    '#type' => 'link',
    '#href' => 'admin/help/forum',
    '#title' => t('More help'),
  );
  $container = array(
    '#theme' => 'container',
    '#children' => drupal_render($more_help_link),
    '#attributes' => array(
      'class' => array('more-help-link'),
    ),
  );
  $output = drupal_render($container);
  return $output;
  case 'admin/structure/forum/add/container':
  return '<p>' . t('Use containers to group related forums.') . '</p>';

Impacts:
Module developers
Themers

(This should still be critical since the change notice is not up yet…)

@rabellamy, thanks for your continued work and patience. Can we just boil this down to the before/after of actually using this theme function? The rest is not necessary. Shorter is usually better for change notices :)

So the summary part is fine, you don't really need to say what files were changed though. Here is my suggestion for the change notice based off of your work above, feel free to post this and/or tweak as you see fit:

Summary:

theme_more_help_link() has been removed from core and replaced with a #type link render array. This theme function was only used once in core, in the forum module.

Before (D7):

  // Direct theme() call:
  theme('more_help_link', array('url' => 'admin/help/forum'));

  // Render array:
  $more_help_link = array(
    '#theme' => 'more_help_link',
    '#url' => 'admin/help/forum',
  );
  drupal_render($more_help_link);

After (D8):

  $more_help_link = array(
    '#type' => 'link',
    '#href' => 'admin/help/forum',
    '#title' => t('More help'),
  );
  $container = array(
    '#theme' => 'container',
    '#children' => drupal_render($more_help_link),
    '#attributes' => array(
      'class' => array('more-help-link'),
    ),
  );
  $output = drupal_render($container);

I have created the change record.
https://drupal.org/node/2076373