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

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

149 lines 4.7 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 (`openstation_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.os.registerTitleBarButton( … )` — the predicate, render,
14	* and onClick all live in the plugin's TypeScript / JavaScript.
15	*
16	* @package OpenStation
17	*/
18
19	defined( 'ABSPATH' ) \|\| exit;
20
21	/**
22	* Declare a WP-registered script handle as a title-bar button
23	* provider.
24	*
25	* Example:
26	*
27	* ```php
28	* add_action( 'admin_enqueue_scripts', function () {
29	* wp_register_script(
30	* 'my-plugin-titlebar',
31	* plugins_url( 'js/titlebar.js', __FILE__ ),
32	* array( 'openstation' ),
33	* '1.0.0',
34	* true
35	* );
36	* wp_enqueue_script( 'my-plugin-titlebar' );
37	* }, 5 ); // Before the shell harvests the payload at priority 10.
38	* openstation_register_titlebar_button_script( 'my-plugin-titlebar' );
39	* ```
40	*
41	* For live unregistration on deactivation, the plugin's JS should
42	* set `owner: 'my-plugin-titlebar'` on each `registerTitleBarButton`
43	* call. Otherwise the button stays until the next page reload —
44	* graceful backwards-compat.
45	*
46	* @param string $handle WP-registered script handle.
47	* @return true\|WP_Error `true` on success; `WP_Error` on validation failure.
48	*/
49	function openstation_register_titlebar_button_script( $handle ) {
50	$handle = (string) $handle;
51	if ( '' === $handle ) {
52	return openstation_registration_error(
53	'openstation_missing_handle',
54	__( 'Title-bar button script registration requires a non-empty script handle.', 'desktop-mode' )
55	);
56	}
57
58	openstation_desktop_titlebar_button_script_registry( $handle, true );
59
60	/**
61	* Fires after a desktop title-bar button script handle is registered.
62	*
63	* @param string $handle The registered script handle.
64	*/
65	do_action( 'openstation_titlebar_button_script_registered', $handle );
66
67	return true;
68	}
69
70	/**
71	* Internal module-level registry for title-bar button script handles.
72	*
73	* @internal
74	*
75	* @param string $handle Script handle to read or write.
76	* @param bool\|null $value Pass `true` to register; `null` to read only.
77	* @return array\|bool When called with no args returns the full store.
78	*/
79	function openstation_desktop_titlebar_button_script_registry( $handle = '', $value = null ) {
80	static $store = array();
81
82	if ( '__flush__' === (string) $handle ) {
83	$store = array();
84	return array();
85	}
86	if ( '' === (string) $handle ) {
87	return $store;
88	}
89	if ( null !== $value ) {
90	$store[ (string) $handle ] = (bool) $value;
91	}
92	return isset( $store[ (string) $handle ] ) ? $store[ (string) $handle ] : false;
93	}
94
95	/**
96	* Test-only: clear the registry between PHPUnit cases. See
97	* {@see openstation_flush_script_handle_registries()}.
98	*/
99	function openstation_flush_desktop_titlebar_button_script_registry() {
100	openstation_desktop_titlebar_button_script_registry( '__flush__' );
101	}
102
103	/**
104	* Build the script-handle payload fed to the shell. Handles that
105	* aren't currently enqueued resolve to an empty URL and are dropped.
106	*
107	* @return array[] List of `{ handle, scriptUrl, scriptBefore, scriptAfter, scriptL10n, scriptTranslations }` entries.
108	*/
109	function openstation_build_desktop_titlebar_button_scripts_payload() {
110	$registry = openstation_desktop_titlebar_button_script_registry();
111	if ( ! is_array( $registry ) \|\| empty( $registry ) ) {
112	return array();
113	}
114
115	$out = array();
116	$seen = array();
117	foreach ( $registry as $handle => $active ) {
118	if ( ! $active \|\| isset( $seen[ $handle ] ) ) {
119	continue;
120	}
121	$payload = openstation_resolve_script_payload( $handle );
122	if ( '' === $payload['url'] ) {
123	// Loud diagnostic — visible under WP_DEBUG. Plugin
124	// authors who pass a typo'd handle, or call our
125	// register helper before `wp_register_script()`, used
126	// to silently register nothing and stare at an empty
127	// title bar. Deduped by `openstation_warn_unresolvable_script_handle`
128	// so the notice fires exactly once per handle per
129	// request, not on every shell-config rebuild.
130	openstation_warn_unresolvable_script_handle(
131	'openstation_register_titlebar_button_script',
132	'Title-bar button',
133	(string) $handle
134	);
135	continue;
136	}
137	$out[] = array(
138	'handle' => (string) $handle,
139	'scriptUrl' => $payload['url'],
140	'scriptBefore' => $payload['before'],
141	'scriptAfter' => $payload['after'],
142	'scriptL10n' => $payload['l10n'],
143	'scriptTranslations' => $payload['translations'],
144	);
145	$seen[ $handle ] = true;
146	}
147	return $out;
148	}
149