desktop-mode / includes / widgets / widget-starter.php

widget-starter.php in OpenStation: Desktop Windows, Dock & Virtual Desktops for WP Admin 1.1.2, at includes/widgets/widget-starter.php

180 lines 8.5 KB

Raw Download Zip

1	<?php
2	/**
3	* =============================================================================
4	* OpenStation — Starter Widget PHP registration
5	* =============================================================================
6	*
7	* WHAT THIS FILE DOES
8	* -------------------
9	* This is the PHP side of a OpenStation widget. It has three jobs:
10	*
11	* 1. Register the JS bundle and CSS with WordPress so they can be loaded.
12	* 2. Enqueue the CSS eagerly on shell pages (prevents flash of unstyled content).
13	* 3. Announce the widget to OpenStation via openstation_register_widget()
14	* so it appears in the widget picker.
15	*
16	* The PHP side does NOT contain any widget logic. All the rendering, data
17	* fetching, and interactivity lives in the JS file (index.ts). PHP just
18	* tells the system "this widget exists, here is its metadata, here is its
19	* script handle."
20	*
21	* HOW TO USE THIS AS A TEMPLATE
22	* ------------------------------
23	* 1. Copy this file to includes/widgets/widget-my.php
24	* 2. Replace every "starter" in function names with your widget name
25	* e.g. openstation_register_starter_* → openstation_register_my_*
26	* 3. Replace "widget-starter" in asset filenames with "widget-my"
27	* 4. Replace 'desktop-mode/starter' with your widget id — must match
28	* the WIDGET_ID constant in your JS file exactly
29	* 5. Update label, description, icon, and size constraints
30	* 6. Add a require_once line for this file in desktop-mode.php
31	*
32	* Requires: OpenStation 0.18.0+ (openstation_register_widget).
33	*
34	* @package OpenStation
35	*/
36
37	defined( 'ABSPATH' ) \|\| exit;
38
39	/**
40	* Register the JS bundle and CSS stylesheet handles.
41	*
42	* WHY wp_register_script AND NOT wp_enqueue_script?
43	* The shell's server-sync loads widget scripts lazily — only when the
44	* picker opens or a widget that needs this script is about to mount.
45	* wp_register_script() makes the handle known to WordPress without
46	* actually outputting a <script> tag. The shell requests the script
47	* via its own enqueue path at the right moment. Using wp_enqueue_script()
48	* here would output the tag unconditionally on every admin page, wasting
49	* bandwidth for users who never open the widget picker.
50	*
51	* WHY IS THE CSS REGISTERED HERE BUT ENQUEUED SEPARATELY?
52	* Styles do not have a lazy-load mechanism equivalent to scripts. If we
53	* registered the CSS but never enqueued it, the widget would flash as
54	* unstyled on first mount while the stylesheet is fetched. So we register
55	* both the JS and the CSS here, then eagerly enqueue just the CSS in a
56	* separate function below that only runs on shell pages.
57	*
58	* SCRIPT_DEBUG CONVENTION
59	* When SCRIPT_DEBUG is true WordPress loads the unminified development
60	* build (widget-starter.js). In production it loads the minified build
61	* (widget-starter.min.js). Both are produced by `npm run build:widget-starter`.
62	*
63	* VERSION STRINGS
64	* Using filemtime() as the version means the browser cache is busted
65	* automatically whenever the file changes on disk — no manual version bumping.
66	* Falls back to OPENSTATION_VERSION if the file does not exist yet (e.g.
67	* during development before the first build).
68	*/
69	function openstation_register_starter_widget_assets() {
70	$suffix = openstation_asset_suffix();
71	$version = defined( 'OPENSTATION_VERSION' ) ? OPENSTATION_VERSION : '0';
72
73	$js_path = OPENSTATION_DIR . 'assets/js/widget-starter' . $suffix . '.js';
74	$css_path = OPENSTATION_DIR . 'assets/js/widget-starter' . $suffix . '.css';
75
76	wp_register_style(
77	'os-starter-widget', // Handle name — referenced in wp_enqueue_style() below.
78	OPENSTATION_URL . 'assets/js/widget-starter' . $suffix . '.css',
79	array(), // No CSS dependencies.
80	file_exists( $css_path ) ? (string) filemtime( $css_path ) : $version
81	);
82
83	wp_register_script(
84	'os-starter-widget', // Handle name — passed as 'script' to openstation_register_widget().
85	OPENSTATION_URL . 'assets/js/widget-starter' . $suffix . '.js',
86	array( 'wp-api-fetch' ), // List WordPress script handles your widget depends on.
87	// 'wp-api-fetch' is available on every admin page and handles
88	// REST nonces automatically. Remove it if your widget does
89	// not make REST API calls.
90	file_exists( $js_path ) ? (string) filemtime( $js_path ) : $version,
91	true // Load in the footer — always true for widget scripts.
92	);
93	}
94	add_action( 'init', 'openstation_register_starter_widget_assets', 5 );
95	// Priority 5 — must run before openstation_register_starter_widget() at priority 6
96	// so the script handle exists when register_widget() looks it up.
97
98	/**
99	* Eagerly enqueue the CSS on OpenStation shell pages.
100	*
101	* The JS loads lazily (server-sync handles it). The CSS must load early
102	* so it is in the DOM before the widget's first render — otherwise there
103	* is a visible flash of unstyled content while the browser fetches the
104	* stylesheet after mount.
105	*
106	* The two guards below prevent the stylesheet loading on pages where
107	* OpenStation is not active:
108	* openstation_is_enabled() — user has OpenStation turned on
109	* openstation_is_chromeless_request() — not an iframe content request
110	*/
111	function openstation_enqueue_starter_widget_styles() {
112	if ( function_exists( 'openstation_is_enabled' ) && ! openstation_is_enabled() ) {
113	return;
114	}
115	if ( function_exists( 'openstation_is_chromeless_request' ) && openstation_is_chromeless_request() ) {
116	return;
117	}
118	wp_enqueue_style( 'os-starter-widget' );
119	}
120	add_action( 'admin_enqueue_scripts', 'openstation_enqueue_starter_widget_styles', 20 );
121
122	/**
123	* Announce the widget to OpenStation.
124	*
125	* This call stores the widget's metadata in OpenStation's registry so
126	* it appears in the widget picker. The shell reads this registry at boot
127	* and on every session refresh — adding or removing a widget definition
128	* takes effect without a browser reload.
129	*
130	* AVAILABLE ARGUMENTS
131	* -------------------
132	* label string Human-readable name shown in the picker. Required.
133	* description string One-line subtitle shown beneath the label.
134	* icon string Any dashicons class, e.g. 'dashicons-chart-bar'.
135	* Full list: https://developer.wordpress.org/resource/dashicons/
136	* script string The wp_register_script() handle from above.
137	* movable bool true = user can drag the widget off the right column
138	* and float it anywhere on the desktop.
139	* false = widget stays in the column (default).
140	* resizable bool true = user can resize the widget card.
141	* Requires movable: true for all 8 handles.
142	* Column-docked widgets only get a bottom handle.
143	* min_width int Smallest width the user can drag the card to (px).
144	* min_height int Smallest height the user can drag the card to (px).
145	* max_width int Optional ceiling on user-driven width resize (px).
146	* max_height int Optional ceiling on user-driven height resize (px).
147	* default_width int Starting width when first added as a floating widget.
148	* default_height int Starting height when first added as a floating widget.
149	* capabilities array Optional. ALL listed capabilities must be held by the
150	* current user or the widget will not register for them.
151	* e.g. array( 'edit_posts', 'publish_posts' )
152	*/
153	function openstation_register_starter_widget() {
154	if ( ! function_exists( 'openstation_register_widget' ) ) {
155	// OpenStation is not active — bail gracefully.
156	return;
157	}
158
159	openstation_register_widget(
160	// First argument: widget id.
161	// Must exactly match the WIDGET_ID constant in your JS file and the
162	// key used in window.openStationWidgets[ id ] at the bottom of index.ts.
163	'desktop-mode/starter',
164	array(
165	'label' => __( 'Starter Widget', 'desktop-mode' ),
166	'description' => __( 'A skeleton widget — copy this to build your own.', 'desktop-mode' ),
167	'icon' => 'dashicons-welcome-widgets-menus',
168	'script' => 'os-starter-widget',
169	'movable' => true,
170	'resizable' => true,
171	'min_width' => 200,
172	'min_height' => 140,
173	'default_width' => 280,
174	'default_height' => 200,
175	)
176	);
177	}
178	add_action( 'init', 'openstation_register_starter_widget', 6 );
179	// Priority 6 — runs after the asset registration at priority 5.
180