wp-guided-tour

Name: wp-guided-tour
Author: mralaminahamed

25stars3forks

How to install wp-guided-tour?

mralaminahamed/wp-dev-skills/wp-guided-tour

$npx -y skills add mralaminahamed/wp-dev-skills --skill wp-guided-tour

Installs into the current project.

Summary

Use when adding a guided onboarding or feature-discovery tour to a WordPress admin plugin using Driver.js v1 — setting up the IIFE bundle (window.driver.js.driver), PHP backend tour config arrays (autoStart, pages, steps, element, popover), JS scope detection from URL pathname +

Files · 1

View on GitHub

SKILL.md

1	# WordPress Admin Guided Tours (Driver.js)
2
3	> Model note: IIFE bundle setup and PHP config scaffolding are mechanical (`haiku`). JS scope detection from URL + hash, and debugging selector mismatches against live DOM, need `sonnet`.
4
5	## When to use
6
7	- "Add a guided tour to my plugin", "set up Driver.js in WordPress admin".
8	- "Wire up tour scopes by URL/hash", "detect which page the user is on for tour routing".
9	- "Track tour completion correctly", "fix tour firing on dismiss instead of Done".
10	- "Test tour selectors against live DOM".
11
12	Not for: Front-end-only SPAs or non-WordPress JS apps — requires WP admin backend context. Guided tours in themes — this skill targets plugin-owned admin pages only.
13
14	## Setup
15
16	### 1 — Vendor Driver.js
17
18	Download the Driver.js v1 IIFE build (NOT the ESM build):
19	- `driver.js.iife.js` → `assets/admin/js/driverjs/driver.js.iife.js`
20	- `driver.css` → `assets/admin/js/driverjs/driver.css`
21
22	The IIFE build exposes `window.driver.js.driver` (double namespace). Always call it as:
23	```js
24	window.driver.js.driver({ ... })
25	```
26
27	### 2 — Enqueue in Asset.php
28
29	```php
30	// Enqueue on all admin pages (is_admin() block)
31	$this->enqueue_script(
32	'shopflow_guided_tour_driverjs',
33	SHOPFLOW_ASSETS_URL . 'admin/js/driverjs/driver.js.iife.js',
34	array()
35	);
36	$this->enqueue_style(
37	'shopflow_guided_tour_driverjs',
38	SHOPFLOW_ASSETS_URL . 'admin/js/driverjs/driver.css',
39	array()
40	);
41	$this->enqueue_script(
42	'shopflow_guided_tour',
43	SHOPFLOW_ASSETS_URL . 'admin/js/guided-tour.js',
44	array( 'shopflow_guided_tour_driverjs' )
45	);
46
47	// Add tour configs to the main localized object
48	$localized['tours'] = shopflow_get_tour_configs();
49	```
50
51	The `$localized` array must be passed to `localize_script()` on the main SPA script (not the tour script) so `window.SHOPFLOW.tours` is available before `guided-tour.js` runs.
52
53	---
54
55	## PHP Tour Config (`functions.php`)
56
57	```php
58	function shopflow_get_tour_configs() {
59	return apply_filters( 'shopflow_tour_configs', array(
60
61	'dashboard' => array(
62	'autoStart' => true, // only one scope should be true
63	'pages' => array( 'shopflow' ),
64	'steps' => array(
65	array(
66	// Centered popover — no element key
67	'popover' => array(
68	'title' => __( 'Welcome!', 'my-plugin' ),
69	'description' => __( 'Quick intro text.', 'my-plugin' ),
70	'side' => 'bottom',
71	),
72	),
73	array(
74	// Element-targeted step
75	'element' => '#my-stable-id',
76	'popover' => array(
77	'title' => __( 'Step Title', 'my-plugin' ),
78	'description' => __( 'Step description.', 'my-plugin' ),
79	'side' => 'right',
80	),
81	),
82	),
83	),
84
85	) );
86	}
87	```
88
89	Rules:
90	- Only one scope should have `autoStart: true` (the primary onboarding page)
91	- Always use `__()` on title and description — run `makepot` after adding new steps
92	- `side` values: `top`, `bottom`, `left`, `right`
93	- Do NOT set `align: 'start'` — it's the default; explicit is noise
94	- `pages` array is metadata only; actual detection is done by JS `getCurrentScope()`
95
96	---
97
98	## JS Scope Detection (`guided-tour.js`)
99
100	```js
101	function getCurrentScope() {
102	const urlParams = new URLSearchParams(window.location.search);
103	const page = urlParams.get('page');
104
105	if (!page \|\| !page.startsWith('myprefix')) return null;
106
107	// Non-SPA pages (full page reloads)
108	if (page === 'mypre

People who liked this also viewed

6 picks

Type

wp-guided-tour

25stars3forks

View on GitHub

How to install wp-guided-tour?

mralaminahamed/wp-dev-skills/wp-guided-tour

$npx -y skills add mralaminahamed/wp-dev-skills --skill wp-guided-tour

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# WordPress Admin Guided Tours (Driver.js)
2
3	> Model note: IIFE bundle setup and PHP config scaffolding are mechanical (`haiku`). JS scope detection from URL + hash, and debugging selector mismatches against live DOM, need `sonnet`.
4
5	## When to use
6
7	- "Add a guided tour to my plugin", "set up Driver.js in WordPress admin".
8	- "Wire up tour scopes by URL/hash", "detect which page the user is on for tour routing".
9	- "Track tour completion correctly", "fix tour firing on dismiss instead of Done".
10	- "Test tour selectors against live DOM".
11
12	Not for: Front-end-only SPAs or non-WordPress JS apps — requires WP admin backend context. Guided tours in themes — this skill targets plugin-owned admin pages only.
13
14	## Setup
15
16	### 1 — Vendor Driver.js
17
18	Download the Driver.js v1 IIFE build (NOT the ESM build):
19	- `driver.js.iife.js` → `assets/admin/js/driverjs/driver.js.iife.js`
20	- `driver.css` → `assets/admin/js/driverjs/driver.css`
21
22	The IIFE build exposes `window.driver.js.driver` (double namespace). Always call it as:
23	```js
24	window.driver.js.driver({ ... })
25	```
26
27	### 2 — Enqueue in Asset.php
28
29	```php
30	// Enqueue on all admin pages (is_admin() block)
31	$this->enqueue_script(
32	'shopflow_guided_tour_driverjs',
33	SHOPFLOW_ASSETS_URL . 'admin/js/driverjs/driver.js.iife.js',
34	array()
35	);
36	$this->enqueue_style(
37	'shopflow_guided_tour_driverjs',
38	SHOPFLOW_ASSETS_URL . 'admin/js/driverjs/driver.css',
39	array()
40	);
41	$this->enqueue_script(
42	'shopflow_guided_tour',
43	SHOPFLOW_ASSETS_URL . 'admin/js/guided-tour.js',
44	array( 'shopflow_guided_tour_driverjs' )
45	);
46
47	// Add tour configs to the main localized object
48	$localized['tours'] = shopflow_get_tour_configs();
49	```
50
51	The `$localized` array must be passed to `localize_script()` on the main SPA script (not the tour script) so `window.SHOPFLOW.tours` is available before `guided-tour.js` runs.
52
53	---
54
55	## PHP Tour Config (`functions.php`)
56
57	```php
58	function shopflow_get_tour_configs() {
59	return apply_filters( 'shopflow_tour_configs', array(
60
61	'dashboard' => array(
62	'autoStart' => true, // only one scope should be true
63	'pages' => array( 'shopflow' ),
64	'steps' => array(
65	array(
66	// Centered popover — no element key
67	'popover' => array(
68	'title' => __( 'Welcome!', 'my-plugin' ),
69	'description' => __( 'Quick intro text.', 'my-plugin' ),
70	'side' => 'bottom',
71	),
72	),
73	array(
74	// Element-targeted step
75	'element' => '#my-stable-id',
76	'popover' => array(
77	'title' => __( 'Step Title', 'my-plugin' ),
78	'description' => __( 'Step description.', 'my-plugin' ),
79	'side' => 'right',
80	),
81	),
82	),
83	),
84
85	) );
86	}
87	```
88
89	Rules:
90	- Only one scope should have `autoStart: true` (the primary onboarding page)
91	- Always use `__()` on title and description — run `makepot` after adding new steps
92	- `side` values: `top`, `bottom`, `left`, `right`
93	- Do NOT set `align: 'start'` — it's the default; explicit is noise
94	- `pages` array is metadata only; actual detection is done by JS `getCurrentScope()`
95
96	---
97
98	## JS Scope Detection (`guided-tour.js`)
99
100	```js
101	function getCurrentScope() {
102	const urlParams = new URLSearchParams(window.location.search);
103	const page = urlParams.get('page');
104
105	if (!page \|\| !page.startsWith('myprefix')) return null;
106
107	// Non-SPA pages (full page reloads)
108	if (page === 'mypre

People who liked this also viewed

6 picks

Type