| 1 |
<?php |
| 2 |
/** |
| 3 |
* Settings functions used for Speculative Loading. |
| 4 |
* |
| 5 |
* @package speculation-rules |
| 6 |
* @since 1.0.0 |
| 7 |
*/ |
| 8 |
|
| 9 |
// Exit if accessed directly. |
| 10 |
if ( ! defined( 'ABSPATH' ) ) { |
| 11 |
exit; |
| 12 |
} |
| 13 |
|
| 14 |
/** |
| 15 |
* Returns the available options for the Speculative Loading mode and their labels. |
| 16 |
* |
| 17 |
* @since 1.0.0 |
| 18 |
* |
| 19 |
* @return array<string, string> Associative array of `$mode => $label` pairs. |
| 20 |
*/ |
| 21 |
function plsr_get_mode_labels(): array { |
| 22 |
return array( |
| 23 |
'prefetch' => _x( 'Prefetch', 'setting label', 'speculation-rules' ), |
| 24 |
'prerender' => _x( 'Prerender', 'setting label', 'speculation-rules' ), |
| 25 |
); |
| 26 |
} |
| 27 |
|
| 28 |
/** |
| 29 |
* Returns the available options for the Speculative Loading eagerness and their labels. |
| 30 |
* |
| 31 |
* @since 1.0.0 |
| 32 |
* |
| 33 |
* @return array<string, string> Associative array of `$eagerness => $label` pairs. |
| 34 |
*/ |
| 35 |
function plsr_get_eagerness_labels(): array { |
| 36 |
return array( |
| 37 |
'conservative' => _x( 'Conservative (typically on click)', 'setting label', 'speculation-rules' ), |
| 38 |
'moderate' => _x( 'Moderate (typically on hover)', 'setting label', 'speculation-rules' ), |
| 39 |
'eager' => _x( 'Eager (on slightest suggestion)', 'setting label', 'speculation-rules' ), |
| 40 |
); |
| 41 |
} |
| 42 |
|
| 43 |
/** |
| 44 |
* Returns the default setting value for Speculative Loading configuration. |
| 45 |
* |
| 46 |
* @since 1.0.0 |
| 47 |
* |
| 48 |
* @return array<string, string> { |
| 49 |
* Default setting value. |
| 50 |
* |
| 51 |
* @type string $mode Mode. |
| 52 |
* @type string $eagerness Eagerness. |
| 53 |
* } |
| 54 |
*/ |
| 55 |
function plsr_get_setting_default(): array { |
| 56 |
return array( |
| 57 |
'mode' => 'prerender', |
| 58 |
'eagerness' => 'moderate', |
| 59 |
); |
| 60 |
} |
| 61 |
|
| 62 |
/** |
| 63 |
* Sanitizes the setting for Speculative Loading configuration. |
| 64 |
* |
| 65 |
* @since 1.0.0 |
| 66 |
* |
| 67 |
* @param mixed $input Setting to sanitize. |
| 68 |
* @return array<string, string> { |
| 69 |
* Sanitized setting. |
| 70 |
* |
| 71 |
* @type string $mode Mode. |
| 72 |
* @type string $eagerness Eagerness. |
| 73 |
* } |
| 74 |
*/ |
| 75 |
function plsr_sanitize_setting( $input ): array { |
| 76 |
$default_value = plsr_get_setting_default(); |
| 77 |
|
| 78 |
if ( ! is_array( $input ) ) { |
| 79 |
return $default_value; |
| 80 |
} |
| 81 |
|
| 82 |
$mode_labels = plsr_get_mode_labels(); |
| 83 |
$eagerness_labels = plsr_get_eagerness_labels(); |
| 84 |
|
| 85 |
// Ensure only valid keys are present. |
| 86 |
$value = array_intersect_key( $input, $default_value ); |
| 87 |
|
| 88 |
// Set any missing or invalid values to their defaults. |
| 89 |
if ( ! isset( $value['mode'] ) || ! isset( $mode_labels[ $value['mode'] ] ) ) { |
| 90 |
$value['mode'] = $default_value['mode']; |
| 91 |
} |
| 92 |
if ( ! isset( $value['eagerness'] ) || ! isset( $eagerness_labels[ $value['eagerness'] ] ) ) { |
| 93 |
$value['eagerness'] = $default_value['eagerness']; |
| 94 |
} |
| 95 |
|
| 96 |
return $value; |
| 97 |
} |
| 98 |
|
| 99 |
/** |
| 100 |
* Registers setting to control Speculative Loading configuration. |
| 101 |
* |
| 102 |
* @since 1.0.0 |
| 103 |
* @access private |
| 104 |
*/ |
| 105 |
function plsr_register_setting(): void { |
| 106 |
register_setting( |
| 107 |
'reading', |
| 108 |
'plsr_speculation_rules', |
| 109 |
array( |
| 110 |
'type' => 'object', |
| 111 |
'description' => __( 'Configuration for the Speculation Rules API.', 'speculation-rules' ), |
| 112 |
'sanitize_callback' => 'plsr_sanitize_setting', |
| 113 |
'default' => plsr_get_setting_default(), |
| 114 |
'show_in_rest' => array( |
| 115 |
'schema' => array( |
| 116 |
'properties' => array( |
| 117 |
'mode' => array( |
| 118 |
'description' => __( 'Whether to prefetch or prerender URLs.', 'speculation-rules' ), |
| 119 |
'type' => 'string', |
| 120 |
'enum' => array_keys( plsr_get_mode_labels() ), |
| 121 |
), |
| 122 |
'eagerness' => array( |
| 123 |
'description' => __( 'The eagerness setting defines the heuristics based on which the loading is triggered. "Eager" will have the minimum delay to start speculative loads, "Conservative" increases the chance that only URLs the user actually navigates to are loaded.', 'speculation-rules' ), |
| 124 |
'type' => 'string', |
| 125 |
'enum' => array_keys( plsr_get_eagerness_labels() ), |
| 126 |
), |
| 127 |
), |
| 128 |
), |
| 129 |
), |
| 130 |
) |
| 131 |
); |
| 132 |
} |
| 133 |
add_action( 'init', 'plsr_register_setting' ); |
| 134 |
|
| 135 |
/** |
| 136 |
* Adds the settings sections and fields for the Speculative Loading configuration. |
| 137 |
* |
| 138 |
* @since 1.0.0 |
| 139 |
* @access private |
| 140 |
*/ |
| 141 |
function plsr_add_setting_ui(): void { |
| 142 |
add_settings_section( |
| 143 |
'plsr_speculation_rules', |
| 144 |
__( 'Speculative Loading', 'speculation-rules' ), |
| 145 |
static function (): void { |
| 146 |
?> |
| 147 |
<p class="description"> |
| 148 |
<?php esc_html_e( 'This section allows you to control how URLs that your users navigate to are speculatively loaded to improve performance.', 'speculation-rules' ); ?> |
| 149 |
</p> |
| 150 |
<?php |
| 151 |
}, |
| 152 |
'reading', |
| 153 |
array( |
| 154 |
'before_section' => '<div id="speculative-loading">', |
| 155 |
'after_section' => '</div>', |
| 156 |
) |
| 157 |
); |
| 158 |
|
| 159 |
$fields = array( |
| 160 |
'mode' => array( |
| 161 |
'title' => __( 'Speculation Mode', 'speculation-rules' ), |
| 162 |
'description' => __( 'Prerendering will lead to faster load times than prefetching. However, in case of interactive content, prefetching may be a safer choice.', 'speculation-rules' ), |
| 163 |
), |
| 164 |
'eagerness' => array( |
| 165 |
'title' => __( 'Eagerness', 'speculation-rules' ), |
| 166 |
'description' => __( 'The eagerness setting defines the heuristics based on which the loading is triggered. "Eager" will have the minimum delay to start speculative loads, "Conservative" increases the chance that only URLs the user actually navigates to are loaded.', 'speculation-rules' ), |
| 167 |
), |
| 168 |
); |
| 169 |
foreach ( $fields as $slug => $args ) { |
| 170 |
add_settings_field( |
| 171 |
"plsr_speculation_rules_{$slug}", |
| 172 |
$args['title'], |
| 173 |
'plsr_render_settings_field', |
| 174 |
'reading', |
| 175 |
'plsr_speculation_rules', |
| 176 |
array_merge( |
| 177 |
array( 'field' => $slug ), |
| 178 |
$args |
| 179 |
) |
| 180 |
); |
| 181 |
} |
| 182 |
} |
| 183 |
add_action( 'load-options-reading.php', 'plsr_add_setting_ui' ); |
| 184 |
|
| 185 |
/** |
| 186 |
* Renders a settings field for the Speculative Loading configuration. |
| 187 |
* |
| 188 |
* @since 1.0.0 |
| 189 |
* @access private |
| 190 |
* |
| 191 |
* @param array<string, string> $args { |
| 192 |
* Associative array of arguments. |
| 193 |
* |
| 194 |
* @type string $field The slug of the sub setting controlled by the field. |
| 195 |
* @type string $title The title for the field. |
| 196 |
* @type string $description Optional. A description to show for the field. |
| 197 |
* } |
| 198 |
*/ |
| 199 |
function plsr_render_settings_field( array $args ): void { |
| 200 |
if ( empty( $args['field'] ) || empty( $args['title'] ) ) { // Invalid. |
| 201 |
return; |
| 202 |
} |
| 203 |
|
| 204 |
$option = get_option( 'plsr_speculation_rules' ); |
| 205 |
if ( ! isset( $option[ $args['field'] ] ) ) { // Invalid. |
| 206 |
return; |
| 207 |
} |
| 208 |
|
| 209 |
$value = $option[ $args['field'] ]; |
| 210 |
$callback = "plsr_get_{$args['field']}_labels"; |
| 211 |
if ( ! is_callable( $callback ) ) { |
| 212 |
return; |
| 213 |
} |
| 214 |
$choices = call_user_func( $callback ); |
| 215 |
|
| 216 |
?> |
| 217 |
<fieldset> |
| 218 |
<legend class="screen-reader-text"><?php echo esc_html( $args['title'] ); ?></legend> |
| 219 |
<?php |
| 220 |
foreach ( $choices as $slug => $label ) { |
| 221 |
?> |
| 222 |
<p> |
| 223 |
<label> |
| 224 |
<input |
| 225 |
name="<?php echo esc_attr( "plsr_speculation_rules[{$args['field']}]" ); ?>" |
| 226 |
type="radio" |
| 227 |
value="<?php echo esc_attr( $slug ); ?>" |
| 228 |
<?php checked( $value, $slug ); ?> |
| 229 |
> |
| 230 |
<?php echo esc_html( $label ); ?> |
| 231 |
</label> |
| 232 |
</p> |
| 233 |
<?php |
| 234 |
} |
| 235 |
|
| 236 |
if ( ! empty( $args['description'] ) ) { |
| 237 |
?> |
| 238 |
<p class="description" style="max-width: 800px;"> |
| 239 |
<?php echo esc_html( $args['description'] ); ?> |
| 240 |
</p> |
| 241 |
<?php |
| 242 |
} |
| 243 |
?> |
| 244 |
</fieldset> |
| 245 |
<?php |
| 246 |
} |
| 247 |
|
| 248 |
/** |
| 249 |
* Adds a settings link to the plugin's action links. |
| 250 |
* |
| 251 |
* @since 1.2.1 |
| 252 |
* |
| 253 |
* @param string[]|mixed $links An array of plugin action links. |
| 254 |
* @return string[]|mixed The modified list of actions. |
| 255 |
*/ |
| 256 |
function plsr_add_settings_action_link( $links ) { |
| 257 |
if ( ! is_array( $links ) ) { |
| 258 |
return $links; |
| 259 |
} |
| 260 |
|
| 261 |
return array_merge( |
| 262 |
array( |
| 263 |
'settings' => sprintf( |
| 264 |
'<a href="%1$s">%2$s</a>', |
| 265 |
esc_url( admin_url( 'options-reading.php#speculative-loading' ) ), |
| 266 |
esc_html__( 'Settings', 'speculation-rules' ) |
| 267 |
), |
| 268 |
), |
| 269 |
$links |
| 270 |
); |
| 271 |
} |
| 272 |
add_filter( 'plugin_action_links_' . SPECULATION_RULES_MAIN_FILE, 'plsr_add_settings_action_link' ); |
| 273 |
|
