wp_get_tooltip_helper() │ WP 7.1.0

Retrieves the markup for an accessible tooltip or toggletip.

Returns a button and either a hover/focus triggered tooltip popover or an action triggered toggle tip. Enqueue the wp-tooltip style and script where it is used. Tooltips are used to show the accessible name of a control. Toggletips are used for longer supporting text explaining context.

No Hooks.

Returns

string. Tooltip HTML markup, or an empty string when no content is provided.

Usage

wp_get_tooltip_helper( $content, $args );

$content(string) (required)

Plain-text tooltip content. An empty value returns an empty string.

$args(array)

Arguments for building the tooltip.

Default: array()

• id(string)
  Unique ID for the popover element.
  Default: generated unique ID

• button(string)
  Existing button or a markup. Used instead of generated button.
  Default: standard button HTML

• label(string)
  Accessible label for the toggle button. Ignored for tooltips.
  Default: 'Help', matching the default icon

• close_label(string)
  Accessible label for the close button.
  Default: 'Close'

• icon(string)
  Dashicons icon class for the toggle button. Should match the control's visible label.
  Default: 'dashicons-editor-help'

• class(string)
  Additional class(es) for the wrapping element.
  Default: ''

• type(string)
  Type of tooltip: either tooltip or toggletip.
  Default: 'tooltip'

Changelog

wp_get_tooltip_helper() wp get tooltip helper code ^{WP 7.1}

function wp_get_tooltip_helper( $content, $args = array() ) {
	$content = trim( (string) $content );

	if ( '' === $content ) {
		return '';
	}

	$defaults = array(
		'id'          => wp_unique_id( 'wp-tooltip-' ),
		'button'      => '<button type="button" aria-label="%3$s"><span class="dashicons %4$s" aria-hidden="true"></span></button>',
		'label'       => __( 'Help' ),
		'close_label' => __( 'Close' ),
		'icon'        => 'dashicons-editor-help',
		'class'       => '',
		'type'        => 'tooltip',
	);

	$args = wp_parse_args( $args, $defaults );

	$classes = ( 'tooltip' === $args['type'] ) ? 'wp-tooltip wp-is-tooltip' : 'wp-tooltip wp-is-toggletip';
	if ( '' !== $args['class'] ) {
		$classes .= ' ' . $args['class'];
	}

	$icon      = ( $args['icon'] ) ? trim( $args['icon'] ) : $defaults['icon'];
	$id        = ( $args['id'] ) ? $args['id'] : $defaults['id'];
	$button    = ( $args['button'] ) ? $args['button'] : $defaults['button'];
	$processed = false;
	$processor = new WP_HTML_Tag_Processor( $button );
	if ( true === $processor->next_tag( 'button' ) ) {
		$processor->add_class( 'wp-tooltip__toggle' );
		if ( 'tooltip' !== $args['type'] ) {
			$processor->set_attribute( 'popovertarget', '%2$s' );
			$processor->set_attribute( 'aria-haspopup', 'dialog' );
		}
		$button    = $processor->get_updated_html();
		$processed = true;
	} else {
		// Reset processor.
		$processor = new WP_HTML_Tag_Processor( $button );
		if ( true === $processor->next_tag( 'a' ) && 'tooltip' === $args['type'] ) {
			$processor->add_class( 'wp-tooltip__toggle' );
			$button    = $processor->get_updated_html();
			$processed = true;
		}
	}
	if ( ! $processed ) {
		// Button HTML passed was not valid.
		$processor = new WP_HTML_Tag_Processor( $defaults['button'] );
		$processor->add_class( 'wp-tooltip__toggle' );
		if ( 'tooltip' !== $args['type'] ) {
			$processor->set_attribute( 'popovertarget', '%2$s' );
			$processor->set_attribute( 'aria-haspopup', 'dialog' );
		}
		$button = $processor->get_updated_html();
	}

	/*
	 * The markup only uses phrasing content so it is valid when nested
	 * in a phrasing context. Sectioning content (e.g. `div`, `dialog`) will
	 * cause the parser to close an open `p`, creating an empty and breaking
	 * the layout. See #65660.
	 */
	if ( 'tooltip' === $args['type'] ) {
		// Tooltips are only used to visually display labels.
		$label  = wp_strip_all_tags( $content, true );
		$markup = sprintf(
			'<span class="%1$s">
				' . $button . '
				<span popover="hint" id="%2$s" class="wp-tooltip__bubble" role="tooltip">' .
					'<span id="%2$s-text" class="wp-tooltip__text">%5$s</span>' .
				'</span>' .
			'</span>',
			esc_attr( $classes ),
			esc_attr( $id ),
			esc_attr( $label ),
			esc_attr( $icon ),
			esc_html( $content ),
		);
	} else {
		/*
		 * A `span` with `role="dialog"` is used instead of a `dialog` element to keep the
		 * markup as phrasing content. The `aria-label`, `tabindex`, and `autofocus`
		 * attributes reproduce the accessible name and focus handling of the native element.
		 */
		$markup = sprintf(
			'<span class="%1$s">
				' . $button . '
				<span popover="auto" id="%2$s" class="wp-tooltip__bubble" role="dialog" aria-label="%3$s" tabindex="-1" autofocus>' .
					'<span id="%2$s-text" class="wp-tooltip__text">%5$s</span>' .
					'<button type="button" class="wp-tooltip__close" popovertarget="%2$s" popovertargetaction="hide" aria-label="%6$s">' .
						'<span class="dashicons dashicons-no-alt" aria-hidden="true"></span>' .
					'</button>' .
				'</span>' .
			'</span>',
			esc_attr( $classes ),
			esc_attr( $id ),
			esc_attr( $args['label'] ),
			esc_attr( $icon ),
			esc_html( $content ),
			esc_attr( $args['close_label'] ),
		);
	}

	return $markup;
}