| 1 |
<?php |
| 2 |
/** |
| 3 |
* Server-side opt-in for dock rail renderer scripts. |
| 4 |
* |
| 5 |
* Mirrors `includes/commands.php` exactly — a plugin enqueues a JS |
| 6 |
* bundle that registers a renderer with `wp.desktop.registerDockRailRenderer()`, |
| 7 |
* then calls `desktop_mode_register_dock_rail_renderer_script( $handle )` |
| 8 |
* to opt the script into the live-refresh payload. The shell loads |
| 9 |
* the script over the chromeless bridge on activation, the JS calls |
| 10 |
* `registerDockRailRenderer()`, and the OS Settings → Dock style picker |
| 11 |
* surfaces the new option immediately — no F5. |
| 12 |
* |
| 13 |
* On deactivation (handle disappears from the payload), every renderer |
| 14 |
* tagged with `owner: '<handle>'` is unregistered. The active id falls |
| 15 |
* back through the registry's chain (user pick → `default`) and the |
| 16 |
* dispatcher rebuilds the rails with whatever resolves. |
| 17 |
* |
| 18 |
* @since 0.6.0 |
| 19 |
* |
| 20 |
* @package WPDesktopMode |
| 21 |
*/ |
| 22 |
|
| 23 |
defined( 'ABSPATH' ) || exit; |
| 24 |
|
| 25 |
/** |
| 26 |
* Register a script handle that contributes a dock rail renderer. |
| 27 |
* |
| 28 |
* Example: |
| 29 |
* |
| 30 |
* ```php |
| 31 |
* add_action( 'desktop_mode_shell_assets', function () { |
| 32 |
* wp_register_script( |
| 33 |
* 'orbit-rail', |
| 34 |
* plugin_dir_url( __FILE__ ) . 'orbit-rail.js', |
| 35 |
* array( 'desktop-mode' ), |
| 36 |
* '1.0.0', |
| 37 |
* true |
| 38 |
* ); |
| 39 |
* wp_enqueue_script( 'orbit-rail' ); |
| 40 |
* } ); |
| 41 |
* desktop_mode_register_dock_rail_renderer_script( 'orbit-rail' ); |
| 42 |
* ``` |
| 43 |
* |
| 44 |
* The script's JS side calls `wp.desktop.registerDockRailRenderer( { … } )` |
| 45 |
* with `owner: 'orbit-rail'` (matching the handle) so deactivation |
| 46 |
* cleanly removes the renderer. |
| 47 |
* |
| 48 |
* @since 0.6.0 |
| 49 |
* |
| 50 |
* @param string $handle WP-registered script handle. |
| 51 |
* @return true|WP_Error `true` on success; `WP_Error` on validation failure. |
| 52 |
*/ |
| 53 |
function desktop_mode_register_dock_rail_renderer_script( $handle ) { |
| 54 |
$handle = (string) $handle; |
| 55 |
if ( '' === $handle ) { |
| 56 |
return desktop_mode_registration_error( |
| 57 |
'desktop_mode_missing_handle', |
| 58 |
__( 'Dock rail renderer script registration requires a non-empty script handle.', 'desktop-mode' ) |
| 59 |
); |
| 60 |
} |
| 61 |
|
| 62 |
desktop_mode_dock_rail_renderer_script_registry( $handle, true ); |
| 63 |
|
| 64 |
/** |
| 65 |
* Fires after a desktop dock rail renderer script handle is registered. |
| 66 |
* |
| 67 |
* @since 0.6.0 |
| 68 |
* |
| 69 |
* @param string $handle The registered script handle. |
| 70 |
*/ |
| 71 |
do_action( 'desktop_mode_dock_rail_renderer_script_registered', $handle ); |
| 72 |
|
| 73 |
return true; |
| 74 |
} |
| 75 |
|
| 76 |
/** |
| 77 |
* Internal module-level registry for dock rail renderer script handles. |
| 78 |
* Read by the payload builder, written by the registration API. |
| 79 |
* |
| 80 |
* @since 0.6.0 |
| 81 |
* @internal |
| 82 |
* |
| 83 |
* @param string $handle Script handle to read or write. |
| 84 |
* @param bool|null $value Pass `true` to register; `null` to read only. |
| 85 |
* @return array|bool When called with no args returns the full store. |
| 86 |
*/ |
| 87 |
function desktop_mode_dock_rail_renderer_script_registry( $handle = '', $value = null ) { |
| 88 |
static $store = array(); |
| 89 |
|
| 90 |
if ( '__flush__' === (string) $handle ) { |
| 91 |
$store = array(); |
| 92 |
return array(); |
| 93 |
} |
| 94 |
if ( '' === (string) $handle ) { |
| 95 |
return $store; |
| 96 |
} |
| 97 |
if ( null !== $value ) { |
| 98 |
$store[ (string) $handle ] = (bool) $value; |
| 99 |
} |
| 100 |
return isset( $store[ (string) $handle ] ) ? $store[ (string) $handle ] : false; |
| 101 |
} |
| 102 |
|
| 103 |
/** |
| 104 |
* Test-only: clear the registry between PHPUnit cases. See |
| 105 |
* {@see desktop_mode_flush_script_handle_registries()}. |
| 106 |
* |
| 107 |
* @since 0.6.0 |
| 108 |
*/ |
| 109 |
function desktop_mode_flush_dock_rail_renderer_script_registry() { |
| 110 |
desktop_mode_dock_rail_renderer_script_registry( '__flush__' ); |
| 111 |
} |
| 112 |
|
| 113 |
/** |
| 114 |
* Build the payload fed to the shell. Resolves each registered handle |
| 115 |
* to a full `{ handle, scriptUrl, scriptBefore, scriptAfter, scriptL10n, |
| 116 |
* scriptTranslations }` entry; handles that aren't currently enqueued |
| 117 |
* (plugin not active this request) resolve to an empty URL and are |
| 118 |
* dropped. |
| 119 |
* |
| 120 |
* @since 0.6.0 |
| 121 |
* |
| 122 |
* @return array[] |
| 123 |
*/ |
| 124 |
function desktop_mode_build_dock_rail_renderer_scripts_payload() { |
| 125 |
$registry = desktop_mode_dock_rail_renderer_script_registry(); |
| 126 |
if ( ! is_array( $registry ) || empty( $registry ) ) { |
| 127 |
return array(); |
| 128 |
} |
| 129 |
|
| 130 |
$out = array(); |
| 131 |
$seen = array(); |
| 132 |
foreach ( $registry as $handle => $active ) { |
| 133 |
if ( ! $active || isset( $seen[ $handle ] ) ) { |
| 134 |
continue; |
| 135 |
} |
| 136 |
$payload = desktop_mode_resolve_script_payload( $handle ); |
| 137 |
if ( '' === $payload['url'] ) { |
| 138 |
desktop_mode_warn_unresolvable_script_handle( |
| 139 |
'desktop_mode_register_dock_rail_renderer_script', |
| 140 |
'Dock rail renderer', |
| 141 |
(string) $handle |
| 142 |
); |
| 143 |
continue; |
| 144 |
} |
| 145 |
$out[] = array( |
| 146 |
'handle' => (string) $handle, |
| 147 |
'scriptUrl' => $payload['url'], |
| 148 |
'scriptBefore' => $payload['before'], |
| 149 |
'scriptAfter' => $payload['after'], |
| 150 |
'scriptL10n' => $payload['l10n'], |
| 151 |
'scriptTranslations' => $payload['translations'], |
| 152 |
); |
| 153 |
$seen[ $handle ] = true; |
| 154 |
} |
| 155 |
return $out; |
| 156 |
} |
| 157 |
|
