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.

Хуков нет.

Возвращает

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

Использование

wp_get_tooltip_helper( $content, $args );

$content(строка) (обязательный)

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

$args(массив)

Arguments for building the tooltip.

По умолчанию: array()

• id(строка)
  Unique ID for the popover element.
  По умолчанию: generated unique ID

• button(строка)
  Existing button or a markup. Used instead of generated button.
  По умолчанию: empty string

• label(строка)
  Accessible label for the toggle button. Ignored for tooltips.
  По умолчанию: 'Help', matching the default icon

• close_label(строка)
  Accessible label for the close button.
  По умолчанию: 'Close'

• icon(строка)
  Dashicons icon class for the toggle button. Should match the control's visible label.
  По умолчанию: 'dashicons-editor-help'

• class(строка)
  Additional class(es) for the wrapping element.
  По умолчанию: ''

• type(строка)
  Type of tooltip: either tooltip or toggletip.
  По умолчанию: 'tooltip'

Список изменений

Код wp_get_tooltip_helper() wp get tooltip helper ^{WP 7.1.4}

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

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

	$defaults = array(
		'id'          => wp_unique_id( 'wp-tooltip-' ),
		'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'];

	// Tooltips use the content as the accessible name; toggletips use the label.
	$label = ( 'tooltip' === $args['type'] ) ? wp_strip_all_tags( $content, true ) : $args['label'];

	/*
	 * The generated button is a plain skeleton. Every dynamic attribute is
	 * added through the tag processor below, so caller-supplied markup is
	 * never scanned or substituted and a percent sign in custom markup,
	 * such as a percent-encoded URL, is never treated as a conversion
	 * specification.
	 */
	$default_button = '<button type="button"><span></span></button>';

	$is_default = ! $args['button'];
	$button     = ( $args['button'] ) ? $args['button'] : $default_button;

	// The accepted root element is a `button`, or an `a` for tooltips.
	$tag       = false;
	$processor = new WP_HTML_Tag_Processor( $button );
	if ( true === $processor->next_tag( 'button' ) ) {
		$tag = 'button';
	} else {
		$processor = new WP_HTML_Tag_Processor( $button );
		if ( 'tooltip' === $args['type'] && true === $processor->next_tag( 'a' ) ) {
			$tag = 'a';
		}
	}

	if ( false === $tag ) {
		// Button HTML passed was not valid. Reset to default.
		$is_default = true;
		$button     = $default_button;
		$processor  = new WP_HTML_Tag_Processor( $button );
		$processor->next_tag( 'button' );
		$tag = 'button';
	}

	/*
	 * Attributes that apply to every accepted button are added in one pass.
	 * Attributes that name the control are only added when the caller's
	 * markup did not already provide them.
	 */
	if ( null === $processor->get_attribute( 'aria-label' ) ) {
		$processor->set_attribute( 'aria-label', $label );
	}
	$processor->add_class( 'wp-tooltip__toggle' );
	if ( 'button' === $tag && 'tooltip' !== $args['type'] ) {
		$processor->set_attribute( 'popovertarget', $id );
		$processor->set_attribute( 'aria-haspopup', 'dialog' );
	}

	// The generated button also carries the dashicon on its inner span.
	if ( $is_default && true === $processor->next_tag( 'span' ) ) {
		$processor->set_attribute( 'class', 'dashicons ' . $icon );
		$processor->set_attribute( 'aria-hidden', 'true' );
	}

	$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'] ) {
		$markup = sprintf(
			'<span class="%1$s">
				%6$s
				<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 ),
			$button,
		);
	} 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">
				%7$s
				<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( $label ),
			esc_attr( $icon ),
			esc_html( $content ),
			esc_attr( $args['close_label'] ),
			$button,
		);
	}

	return $markup;
}