desktop-mode / includes / solo-window.php

solo-window.php in OpenStation: Desktop Windows, Dock & Virtual Desktops for WP Admin 1.1.8, at includes/solo-window.php

100 lines 3.6 KB

Raw Download Zip

1	<?php
2	/**
3	* OpenStation — Solo window rendering mode.
4	*
5	* `?openstation_solo=<window-id>` boots the whole shell and then tells
6	* it to paint exactly one window: no dock, no taskbar, no wallpaper,
7	* no desk, no session restore.
8	*
9	* ## Why the framework has to come along
10	*
11	* OpenStation has two kinds of window. An iframe window is an
12	* admin page, and anything that wants to show one somewhere else can
13	* simply load its chromeless URL. A native window — the Files
14	* browser, the Games hub, a plugin's own canvas — has no URL at all;
15	* it is a render callback that paints into the shell's DOM. Handing
16	* one to a surface outside the desk is therefore not a matter of
17	* finding the right address: without the shell there is nothing to
18	* render into, and a native window without its framework is not a
19	* window, it is an unrendered callback.
20	*
21	* Solo mode is the answer: the same shell, the same registries, the
22	* same render callback, the same theme and title-bar buttons the
23	* plugin registered — with the desk removed from around it. What the
24	* user sees is the window they already had, not a lookalike.
25	*
26	* ## Who uses it
27	*
28	* Built for the native desktop host (the Electron adapter under
29	* `extensions/`), which uses it to give a native window to a real OS
30	* window. Nothing here knows about Electron, and nothing should: an
31	* embed, a kiosk screen, or a PWA shortcut can point at the same flag
32	* and get the same single-window shell.
33	*
34	* @package OpenStation
35	*/
36
37	defined( 'ABSPATH' ) \|\| exit;
38
39	/**
40	* Query var that boots the shell in solo mode.
41	*
42	* The VALUE is externally visible — it appears in URLs other software
43	* builds and users bookmark — so treat it as frozen.
44	*/
45	const OPENSTATION_SOLO_FLAG = 'openstation_solo';
46
47	/**
48	* The window id this request should boot solo, if any.
49	*
50	* Only meaningful when OpenStation is enabled for the user: the flag
51	* is a rendering mode, not an access grant. A logged-out or
52	* non-OpenStation request must not be reshaped by a query string, and
53	* every capability check on the underlying screen still applies
54	* exactly as it would anywhere else.
55	*
56	* @return string Window id, or '' when this is not a solo request.
57	*/
58	function openstation_solo_window_id() {
59	// `is_scalar` before unslashing, because a `?openstation_solo[]=x`
60	// would otherwise reach `sanitize_text_field()` as an array and
61	// warn on the way to being rejected anyway.
62	// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only rendering mode, no state change.
63	$raw = ( isset( $_GET[ OPENSTATION_SOLO_FLAG ] ) && is_scalar( $_GET[ OPENSTATION_SOLO_FLAG ] ) )
64	? sanitize_text_field( wp_unslash( $_GET[ OPENSTATION_SOLO_FLAG ] ) )
65	: '';
66	if ( '' === $raw ) {
67	return '';
68	}
69
70	if ( ! function_exists( 'openstation_is_enabled' ) \|\| ! openstation_is_enabled() ) {
71	return '';
72	}
73
74	// Window ids are shell-generated slugs (`edit-php`, `os-files`,
75	// plugin-registered native ids). `sanitize_key()` is the right
76	// shape and drops anything that could escape an attribute or a
77	// selector.
78	$id = sanitize_key( $raw );
79
80	/**
81	* Filter the window id booted in solo mode.
82	*
83	* Returning '' turns solo mode off for this request — the hook to
84	* use for gating single-window rendering by role or by window.
85	*
86	* @param string $id Key-sanitized window id, ready to use.
87	* @param string $raw The requested value before key-sanitization.
88	*/
89	return (string) apply_filters( 'openstation_solo_window_id', $id, $raw );
90	}
91
92	/**
93	* Whether this request is booting a single window in solo mode.
94	*
95	* @return bool True in solo mode.
96	*/
97	function openstation_is_solo_request() {
98	return '' !== openstation_solo_window_id();
99	}
100