Guides and tours for your own screens

Since version 2.9.0 you can explain your own screens with a card on the first visit and a tour along the parts of the screen.

A module implements AddoBack\Modules\ProvidesGuides (guides(): array). A plugin or theme without a module uses the adba_guides filter:

add_filter( 'adba_guides', static function ( array $guides ) {
	$guides[] = array(
		'id'      => 'myplugin-intro',          // Stable; the seen state per user is keyed on it.
		'version' => 1,                         // Raise it to show the guide again, marked New.
		'screens' => array( 'toplevel_page_myplugin' ), // Screen ids or bases, 'post_type:slug' or '*'.
		'title'   => __( 'My plugin', 'myplugin' ),
		'body'    => '<p>' . esc_html__( 'Two or three sentences.', 'myplugin' ) . '</p>', // wp_kses_post.
		'steps'   => array(
			array( 'target' => '#myplugin-box', 'title' => __( 'The box', 'myplugin' ), 'body' => __( 'What it does.', 'myplugin' ), 'placement' => 'bottom' ),
		),
	);
	return $guides;
} );

Fields

• id is stable. The seen state of each user is stored under it.
• version is a number. Raise it to show the guide again; it is then marked New.
• screens lists the screens: screen ids or bases, post_type:slug or *.
• body goes through wp_kses_post.
• Each step has a target (a CSS selector), a title, a body and a placement.
• A step can name a menu to open first with open, for example 'open' => '#wp-admin-bar-my-account' for an item in the account menu. The tour closes it again on the next step.
• Steps whose target is not on the page are skipped.

Switching guides on and off

Users switch guides off in the account menu. The site sets guide_mode (auto or on_demand); the filter adba_guide_mode changes it in code.

To show every guide again, run:

wp adba guides reset <id|login>
wp adba guides reset --all

Events

The JavaScript events guide:open ({ id, type }, with type card or tour) and guide:done ({ id, completed }) tell you when a guide opened and closed. completed is true when every tour step was seen. See the JavaScript API.

Related

• Shell, admin bar and preferences hooks