theme_html_tag() was renamed to theme_head_tag() and repurposed in the early days of Backdrop (see #452 and the respective change record).

The function theme_html_tag() has been renamed theme_head_tag(), and as such, should only be used for adding HTML tags within the <head> tag on the page.

Our brethren in Drupal 7 are also trying to get rid of that theme function, but instead of simply renaming/deprecating it, they are trying to backport the '#type' => 'html_tag' functionality from Drupal 8: https://www.drupal.org/project/drupal/issues/2981726 (draft change record).

The intention is to be able to do something like this:

  $form['some_html_element'] = array(
    '#type' => 'html_tag',
    '#tag' => 'label',
    '#value' => t('Some awesome label goes here'),
    '#attributes' => array(
      'id' => 'my-label',
      'for' => 'some-input'
      'data-attribute' => t('Some data-* attribute'),
    ),
  );

...instead of having to resort to something like this:

  $form['some_html_element'] = array(
    '#type' => 'markup',
    '#prefix' => '<label id="my-label" for="some-input" data-attribute="Some data-* attribute">',
    '#markup' => t('Some awesome label goes here'),
    '#suffix' => '</label>',
  );

Benefits: - the HTML tag can easily be overridden with something like $form['some_html_element']['#tag'] = 'p';, instead of having to override $form['some_html_element']['#prefix'] and $form['some_html_element']['#suffix']. - you can easily override individual attributes, as opposed to using '#prefix' which "hardcodes" the attributes, and forces you to parse and re-write the entire $form['some_html_element']['#prefix']. - it'd be backwards-compatible with what is (will be) in D7, or at least will require less effort to convert things to Backdrop (change '#theme' => 'html_tag', to '#type' => 'html_tag',) - will allow nested elements, once support for 'child' => array() has been backported.

Original report

This is the respective issue for https://www.drupal.org/project/drupal/issues/2981726 in the D7 core queue:

One year ago, the Drupal 8 html_tag has been updated and it's now able to render nested tags, see the CR here #2887146.

I (@drupol) backported the functionality to Drupal 7 so now, we can render this render array properly, including the children.

To test the functionality, run this code before and after applying the patch in /devel/php:

$render_array = array(
  '#type' => 'html_tag',
  '#tag' => 'h1',
  '#attributes' => array('class' => 'title'),
  'children' => array(
    array(
      '#type' => 'link',
      '#title' => 'Link title',
      '#href' => '/',
      '#attributes' => array('class' => 'inner'),
    ),
    array(
      '#theme' => 'link',
      '#text' => 'Link title',
      '#path' => '/',
      '#options' => array(
        'attributes' => array(),
        'html' => FALSE,
      )
    ),
  )
);

$html = render($render_array);

debug($html);

Without the patch:

  <h1 class="title" />

With the patch:

<h1 class="title">
  <a href="/" class="inner">Link title</a>
  <a href="/">Link title</a>
</h1>`

Another example:

$render_array = array(
  '#type' => 'html_tag',
  '#tag' => 'h1',
  '#attributes' => array('class' => 'title'),
  '#value' => 'value',
  'children' => array(
    array(
      '#type' => 'link',
      '#title' => 'Link title',
      '#href' => '/',
      '#attributes' => array('class' => 'inner'),
    ),
    array(
      '#theme' => 'link',
      '#text' => 'Link title',
      '#path' => '/',
      '#options' => array(
        'attributes' => array(),
        'html' => FALSE,
      )
    ),
  )
);

$html = render($render_array);

debug($html);

Without the patch:

  <h1 class="title">value</h1>`

With the patch:

<h1 class="title">
  value
  <a href="/" class="inner">Link title</a>
  <a href="/">Link title</a>
</h1>

Change record

Proposed change record: https://www.drupal.org/node/2982025

GitHub Link: 
https://github.com/backdrop/backdrop-issues/issues/3892
GitHub Issue #: 
3892