desktop-mode / includes / first-run / shell-tour.php

shell-tour.php in OpenStation: Desktop Windows, Dock & Virtual Desktops for WP Admin 1.1.12, at includes/first-run/shell-tour.php

127 lines 4.6 KB

Raw Download Zip

1	<?php
2	/**
3	* OpenStation — the shell tour's server-side gate.
4	*
5	* The tour itself is JavaScript (`src/shell-tour/`), five coachmarks
6	* on a user's first boot: where the menus are, how to change the
7	* layout, then open a window, snap it, press ⌘K. The
8	* server decides two things about it: whether this site offers it at
9	* all (the `openstation_show_shell_tour` filter), and whether this
10	* user has already had it — the latter through the seen-intros
11	* registry under the slug below, which is what gives the tour per-user
12	* persistence across browsers, the "Reset what's-new dialogs" button
13	* and the `os-intros-reset` event for free.
14	*
15	* Existing users do not get the tour on update: migration 10 marks the
16	* slug seen for everyone who used the shell before it shipped. Reset
17	* brings it back for anyone who wants it.
18	*
19	* A user who skips it gets a desktop icon to take it later, until they
20	* walk a run to the end.
21	*
22	* @package OpenStation
23	*/
24
25	defined( 'ABSPATH' ) \|\| exit;
26
27	/** Slug stored in `desktop_mode_seen_intros` once the tour has run. */
28	const OPENSTATION_SHELL_TOUR_INTRO_SLUG = 'shell-tour';
29
30	/** Recorded when a run ends before the last card: Skip or Escape. */
31	const OPENSTATION_SHELL_TOUR_SKIPPED_SLUG = 'shell-tour-skipped';
32
33	/** Recorded when a run reaches the last card and the user clicks Done. */
34	const OPENSTATION_SHELL_TOUR_DONE_SLUG = 'shell-tour-done';
35
36	/** The desktop icon that relaunches an unfinished tour. */
37	const OPENSTATION_SHELL_TOUR_ICON_ID = 'openstation-shell-tour';
38
39	/**
40	* Whether the shell should offer this user the tour on boot.
41	*
42	* The seen-state is deliberately NOT folded in here: the shell reads
43	* `config.seenIntros` for that, and keeps reading it after a reset so
44	* an instant replay works without a new boot payload. This answers
45	* the site-level question only.
46	*
47	* @param int $user_id User ID. Defaults to the current user.
48	* @return bool
49	*/
50	function openstation_should_offer_shell_tour( $user_id = 0 ) {
51	$user_id = (int) $user_id;
52	if ( $user_id <= 0 ) {
53	$user_id = get_current_user_id();
54	}
55
56	/**
57	* Filters whether the first-boot shell tour is offered to a user.
58	*
59	* Return `false` to suppress the tour site-wide (a managed host
60	* with its own onboarding) or for a role. A user who already took
61	* or skipped it is excluded by the seen-intros registry before
62	* this filter matters.
63	*
64	* @param bool $offer Whether to offer the tour. Default true.
65	* @param int $user_id The user booting the shell.
66	*/
67	return (bool) apply_filters( 'openstation_show_shell_tour', true, $user_id );
68	}
69
70	/**
71	* Whether this user left the tour unfinished: they skipped it, by the
72	* button or by Escape, and have not walked a run to the end since.
73	*
74	* Existing users are not unfinished. Migration 10 records them as
75	* having SEEN the tour, never as having skipped it, so an update does
76	* not put the icon on a veteran's desk.
77	*
78	* @param int $user_id User ID. Defaults to the current user.
79	* @return bool
80	*/
81	function openstation_shell_tour_is_unfinished( $user_id = 0 ) {
82	$user_id = (int) $user_id;
83	if ( $user_id <= 0 ) {
84	$user_id = get_current_user_id();
85	}
86	if ( $user_id <= 0 ) {
87	return false;
88	}
89	return openstation_has_seen_intro( $user_id, OPENSTATION_SHELL_TOUR_SKIPPED_SLUG )
90	&& ! openstation_has_seen_intro( $user_id, OPENSTATION_SHELL_TOUR_DONE_SLUG );
91	}
92
93	/**
94	* Put the relaunch icon on the desk of a user who left the tour unfinished.
95	*
96	* Added through `openstation_icons` rather than `openstation_register_icon()`,
97	* and on purpose: the registry requires a window or a URL to open, and this
98	* icon has neither. A click on it IS the request, caught by the shell on
99	* `os.os-icon.clicked`; the client opens no target for an entry that has
100	* none. The filter is the documented way to inject a virtual entry, and it
101	* is keyed by id because that is what the placement store reads.
102	*
103	* Like any other desktop icon, right-click offers "Hide from desktop".
104	*
105	* @param array $registry Desktop icon entries, keyed by id.
106	* @return array
107	*/
108	function openstation_shell_tour_relaunch_icon( $registry ) {
109	if ( ! is_array( $registry ) ) {
110	return $registry;
111	}
112	if ( ! openstation_should_offer_shell_tour() \|\| ! openstation_shell_tour_is_unfinished() ) {
113	return $registry;
114	}
115	$registry[ OPENSTATION_SHELL_TOUR_ICON_ID ] = array(
116	'id' => OPENSTATION_SHELL_TOUR_ICON_ID,
117	'title' => __( 'Take the tour', 'desktop-mode' ),
118	'icon' => 'dashicons-welcome-learn-more',
119	'window' => '',
120	'url' => '',
121	'position' => 100,
122	'pinned' => false,
123	);
124	return $registry;
125	}
126	add_filter( 'openstation_icons', 'openstation_shell_tour_relaunch_icon' );
127