tablepress / classes / class-admin-page-helper.php

class-admin-page-helper.php in TablePress – Tables in WordPress made easy 3.0.4, at classes/class-admin-page-helper.php

200 lines 7.4 KB

Raw Download Zip

1	<?php
2	/**
3	* Admin Page Helper Class for TablePress with functions needed in the admin area
4	*
5	* @package TablePress
6	* @subpackage Views
7	* @author Tobias Bäthge
8	* @since 1.0.0
9	*/
10
11	// Prohibit direct script loading.
12	defined( 'ABSPATH' ) \|\| die( 'No direct script access allowed!' );
13
14	/**
15	* Admin Page class
16	*
17	* @package TablePress
18	* @subpackage Views
19	* @author Tobias Bäthge
20	* @since 1.0.0
21	*/
22	class TablePress_Admin_Page {
23
24	/**
25	* Enqueue a CSS file, possibly with dependencies.
26	*
27	* @since 1.0.0
28	*
29	* @param string $name Name of the CSS file, without extension.
30	* @param string[] $dependencies Optional. List of names of CSS stylesheets that this stylesheet depends on, and which need to be included before this one.
31	*/
32	public function enqueue_style( string $name, array $dependencies = array() ): void {
33	$css_file = "admin/css/build/{$name}.css";
34	$css_url = plugins_url( $css_file, TABLEPRESS__FILE__ );
35	wp_enqueue_style( "tablepress-{$name}", $css_url, $dependencies, TablePress::version );
36	}
37
38	/**
39	* Enqueue a JavaScript file, possibly with dependencies and extra information.
40	*
41	* @since 1.0.0
42	*
43	* @param string $name Name of the JS file, without extension.
44	* @param string[] $dependencies Optional. List of names of JS scripts that this script depends on, and which need to be included before this one.
45	* @param array<string, mixed> $script_data Optional. JS data that is printed to the page before the script is included. The array key will be used as the name, the value will be JSON encoded.
46	*/
47	public function enqueue_script( string $name, array $dependencies = array(), array $script_data = array() ): void {
48	$js_file = "admin/js/build/{$name}.js";
49	$js_url = plugins_url( $js_file, TABLEPRESS__FILE__ );
50
51	$version = TablePress::version;
52
53	// Load dependencies and version from the auto-generated asset PHP file.
54	$script_asset_path = TABLEPRESS_ABSPATH . "admin/js/build/{$name}.asset.php";
55	if ( file_exists( $script_asset_path ) ) {
56	$script_asset = require $script_asset_path;
57	if ( isset( $script_asset['dependencies'] ) ) {
58	$dependencies = array_merge( $dependencies, $script_asset['dependencies'] );
59	}
60	if ( isset( $script_asset['version'] ) ) {
61	$version = $script_asset['version'];
62	}
63	}
64
65	/*
66	* Register the `react-jsx-runtime` polyfill, if it is not already registered.
67	* This is needed as a polyfill for WP < 6.6, and can be removed once WP 6.6 is the minimum requirement for TablePress.
68	*/
69	if ( ! wp_script_is( 'react-jsx-runtime', 'registered' ) ) {
70	wp_register_script( 'react-jsx-runtime', plugins_url( 'admin/js/react-jsx-runtime.min.js', TABLEPRESS__FILE__ ), array( 'react' ), TablePress::version, true );
71	}
72
73	/**
74	* Filters the dependencies of a TablePress script file.
75	*
76	* @since 2.0.0
77	*
78	* @param string[] $dependencies List of the dependencies that the $name script relies on.
79	* @param string $name Name of the JS script, without extension.
80	*/
81	$dependencies = apply_filters( 'tablepress_admin_page_script_dependencies', $dependencies, $name );
82
83	wp_enqueue_script( "tablepress-{$name}", $js_url, $dependencies, $version, true );
84
85	// Load JavaScript translation files, for all scripts that rely on `wp-i18n`.
86	if ( in_array( 'wp-i18n', $dependencies, true ) ) {
87	wp_set_script_translations( "tablepress-{$name}", 'tablepress' );
88	}
89
90	if ( ! empty( $script_data ) ) {
91	foreach ( $script_data as $var_name => $var_data ) {
92	$var_data = wp_json_encode( $var_data, JSON_FORCE_OBJECT \| JSON_HEX_TAG \| JSON_UNESCAPED_SLASHES );
93	wp_add_inline_script( "tablepress-{$name}", "const tablepress_{$var_name} = {$var_data};", 'before' );
94	}
95	}
96	}
97
98	/**
99	* Register a filter hook on the admin footer.
100	*
101	* @since 1.0.0
102	*/
103	public function add_admin_footer_text(): void {
104	// Show admin footer message (only on TablePress admin screens).
105	add_filter( 'admin_footer_text', array( $this, '_admin_footer_text' ) );
106	}
107
108	/**
109	* Adds a TablePress "Thank You" message to the admin footer content.
110	*
111	* @since 1.0.0
112	*
113	* @param string $content Current admin footer content.
114	* @return string New admin footer content.
115	*/
116	public function _admin_footer_text( /* string */ $content ): string {
117	// Don't use a type hint in the method declaration as many WordPress plugins use the `admin_footer_text` filter in the wrong way.
118
119	// Protect against other plugins not returning a string in their filter callbacks.
120	if ( ! is_string( $content ) ) { // @phpstan-ignore function.alreadyNarrowedType (The `is_string()` check is needed as the input is coming from a filter hook.)
121	$content = '';
122	}
123
124	$content .= ' • ' . sprintf( __( 'Thank you for using <a href="%s">TablePress</a>.', 'tablepress' ), 'https://tablepress.org/' );
125	if ( tb_tp_fs()->is_free_plan() ) {
126	$content .= ' ' . sprintf( __( 'Take a look at the <a href="%s">Premium features</a>!', 'tablepress' ), 'https://tablepress.org/premium/?utm_source=plugin&utm_medium=textlink&utm_content=admin-footer' );
127	}
128	return $content;
129	}
130
131	/**
132	* Print the JavaScript code for a WP feature pointer.
133	*
134	* @since 1.0.0
135	*
136	* @param string $pointer_id The pointer ID.
137	* @param string $selector The HTML elements, on which the pointer should be attached.
138	* @param array<string, mixed> $args Arguments to be passed to the pointer JS (see wp-pointer.js).
139	*/
140	public function print_wp_pointer_js( string $pointer_id, string $selector, array $args ): void {
141	if ( empty( $pointer_id ) \|\| empty( $selector ) \|\| empty( $args['content'] ) ) {
142	return;
143	}
144
145	/*
146	* Print JS code for the feature pointers, extended with event handling for opened/closed "Screen Options", so that pointers can
147	* be repositioned. 210 ms is slightly slower than jQuery's "fast" value, to allow all elements to reach their original position.
148	*/
149	?>
150	<script>
151	( function( $ ) {
152	let options = <?php echo wp_json_encode( $args, JSON_HEX_TAG \| JSON_UNESCAPED_SLASHES ); ?>;
153
154	if ( ! options ) {
155	return;
156	}
157
158	options = $.extend( options, {
159	close: function() {
160	$.post( ajaxurl, {
161	pointer: '<?php echo $pointer_id; ?>',
162	action: 'dismiss-wp-pointer'
163	} );
164	$( this ).pointer( { 'disabled': true } );
165	}
166	} );
167
168	$( function () {
169	$( '<?php echo $selector; ?>' ).pointer( options ).pointer( 'open' );
170	} );
171
172	$( document ).on( 'screen:options:open screen:options:close', function () {
173	setTimeout( function () { $( '<?php echo $selector; ?>' ).pointer( 'reposition' ); }, 210 );
174	} );
175	} )( jQuery );
176	</script>
177	<?php
178	}
179
180	/**
181	* Returns a safe JSON representation of a variable for printing inside of JavaScript code.
182	*
183	* @since 2.0.0
184	*
185	* @param mixed $data Variable to convert to JSON.
186	* @return string Safe JSON representation of a variable for printing inside of JavaScript code.
187	*/
188	public function convert_to_json_parse_output( /* string\|array\|bool\|int\|float\|null */ $data ): string {
189	$json = wp_json_encode( $data, JSON_HEX_TAG \| JSON_UNESCAPED_SLASHES );
190	if ( false === $json ) {
191	// JSON encoding failed, return an error object. Use a prefixed "_error" key to avoid conflicts with intentionally added "error" keys.
192	$json = '{ "_error": "The data could not be encoded to JSON!" }';
193	}
194	// Print the JSON data inside a `JSON.parse()` call in JS for speed gains, with necessary escaping of `\` and `'`.
195	$json = str_replace( array( '\\', "'" ), array( '\\\\', "\'" ), $json );
196	return "JSON.parse( '{$json}' )";
197	}
198
199	} // class TablePress_Admin_Page
200