desktop-mode / includes / title-bar-buttons.php

title-bar-buttons.php in OpenStation: Desktop Windows, Dock & Virtual Desktops for WP Admin 0.9.5, at includes/title-bar-buttons.php

159 lines 4.8 KB

Raw Download Zip

1	<?php
2	/**
3	* Desktop title-bar button registration API.
4	*
5	* Mirrors the command-script / settings-tab-script registration
6	* pattern: minimum-ceremony PHP opt-in (`desktop_mode_register_titlebar_button_script`)
7	* tells the shell which enqueued scripts contribute title-bar
8	* buttons. The shell injects the script URL into the live-refresh
9	* payload so a plugin activated mid-session paints its button
10	* immediately, no F5 needed.
11	*
12	* Buttons themselves are declared JS-side via
13	* `wp.desktop.registerTitleBarButton( … )` — the predicate, render,
14	* and onClick all live in the plugin's TypeScript / JavaScript.
15	*
16	* @since 0.5.2
17	* @package WPDesktopMode
18	*/
19
20	defined( 'ABSPATH' ) \|\| exit;
21
22	/**
23	* Declare a WP-registered script handle as a title-bar button
24	* provider.
25	*
26	* Example:
27	*
28	* ```php
29	* add_action( 'admin_enqueue_scripts', function () {
30	* wp_register_script(
31	* 'my-plugin-titlebar',
32	* plugins_url( 'js/titlebar.js', __FILE__ ),
33	* array( 'desktop-mode' ),
34	* '1.0.0',
35	* true
36	* );
37	* wp_enqueue_script( 'my-plugin-titlebar' );
38	* } );
39	* desktop_mode_register_titlebar_button_script( 'my-plugin-titlebar' );
40	* ```
41	*
42	* For live unregistration on deactivation, the plugin's JS should
43	* set `owner: 'my-plugin-titlebar'` on each `registerTitleBarButton`
44	* call. Otherwise the button stays until the next page reload —
45	* graceful backwards-compat.
46	*
47	* @since 0.5.2
48	*
49	* @param string $handle WP-registered script handle.
50	* @return true\|WP_Error `true` on success; `WP_Error` on validation failure.
51	*/
52	function desktop_mode_register_titlebar_button_script( $handle ) {
53	$handle = (string) $handle;
54	if ( '' === $handle ) {
55	return desktop_mode_registration_error(
56	'desktop_mode_missing_handle',
57	__( 'Title-bar button script registration requires a non-empty script handle.', 'desktop-mode' )
58	);
59	}
60
61	desktop_mode_desktop_titlebar_button_script_registry( $handle, true );
62
63	/**
64	* Fires after a desktop title-bar button script handle is registered.
65	*
66	* @since 0.5.2
67	*
68	* @param string $handle The registered script handle.
69	*/
70	do_action( 'desktop_mode_titlebar_button_script_registered', $handle );
71
72	return true;
73	}
74
75	/**
76	* Internal module-level registry for title-bar button script handles.
77	*
78	* @since 0.5.2
79	* @internal
80	*
81	* @param string $handle Script handle to read or write.
82	* @param bool\|null $value Pass `true` to register; `null` to read only.
83	* @return array\|bool When called with no args returns the full store.
84	*/
85	function desktop_mode_desktop_titlebar_button_script_registry( $handle = '', $value = null ) {
86	static $store = array();
87
88	if ( '__flush__' === (string) $handle ) {
89	$store = array();
90	return array();
91	}
92	if ( '' === (string) $handle ) {
93	return $store;
94	}
95	if ( null !== $value ) {
96	$store[ (string) $handle ] = (bool) $value;
97	}
98	return isset( $store[ (string) $handle ] ) ? $store[ (string) $handle ] : false;
99	}
100
101	/**
102	* Test-only: clear the registry between PHPUnit cases. See
103	* {@see desktop_mode_flush_script_handle_registries()}.
104	*
105	* @since 0.5.2
106	*/
107	function desktop_mode_flush_desktop_titlebar_button_script_registry() {
108	desktop_mode_desktop_titlebar_button_script_registry( '__flush__' );
109	}
110
111	/**
112	* Build the script-handle payload fed to the shell. Handles that
113	* aren't currently enqueued resolve to an empty URL and are dropped.
114	*
115	* @since 0.5.2
116	*
117	* @return array[] List of `{ handle, scriptUrl, scriptBefore, scriptAfter, scriptL10n, scriptTranslations }` entries.
118	*/
119	function desktop_mode_build_desktop_titlebar_button_scripts_payload() {
120	$registry = desktop_mode_desktop_titlebar_button_script_registry();
121	if ( ! is_array( $registry ) \|\| empty( $registry ) ) {
122	return array();
123	}
124
125	$out = array();
126	$seen = array();
127	foreach ( $registry as $handle => $active ) {
128	if ( ! $active \|\| isset( $seen[ $handle ] ) ) {
129	continue;
130	}
131	$payload = desktop_mode_resolve_script_payload( $handle );
132	if ( '' === $payload['url'] ) {
133	// Loud diagnostic — visible under WP_DEBUG. Plugin
134	// authors who pass a typo'd handle, or call our
135	// register helper before `wp_register_script()`, used
136	// to silently register nothing and stare at an empty
137	// title bar. Deduped by `desktop_mode_warn_unresolvable_script_handle`
138	// so the notice fires exactly once per handle per
139	// request, not on every shell-config rebuild.
140	desktop_mode_warn_unresolvable_script_handle(
141	'desktop_mode_register_titlebar_button_script',
142	'Title-bar button',
143	(string) $handle
144	);
145	continue;
146	}
147	$out[] = array(
148	'handle' => (string) $handle,
149	'scriptUrl' => $payload['url'],
150	'scriptBefore' => $payload['before'],
151	'scriptAfter' => $payload['after'],
152	'scriptL10n' => $payload['l10n'],
153	'scriptTranslations' => $payload['translations'],
154	);
155	$seen[ $handle ] = true;
156	}
157	return $out;
158	}
159