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

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

192 lines 6.8 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	* Filters the dependencies of a TablePress script file.
67	*
68	* @since 2.0.0
69	*
70	* @param string[] $dependencies List of the dependencies that the $name script relies on.
71	* @param string $name Name of the JS script, without extension.
72	*/
73	$dependencies = apply_filters( 'tablepress_admin_page_script_dependencies', $dependencies, $name );
74
75	wp_enqueue_script( "tablepress-{$name}", $js_url, $dependencies, $version, true );
76
77	// Load JavaScript translation files, for all scripts that rely on `wp-i18n`.
78	if ( in_array( 'wp-i18n', $dependencies, true ) ) {
79	wp_set_script_translations( "tablepress-{$name}", 'tablepress' );
80	}
81
82	if ( ! empty( $script_data ) ) {
83	foreach ( $script_data as $var_name => $var_data ) {
84	$var_data = wp_json_encode( $var_data, JSON_FORCE_OBJECT );
85	wp_add_inline_script( "tablepress-{$name}", "const tablepress_{$var_name} = {$var_data};", 'before' );
86	}
87	}
88	}
89
90	/**
91	* Register a filter hook on the admin footer.
92	*
93	* @since 1.0.0
94	*/
95	public function add_admin_footer_text(): void {
96	// Show admin footer message (only on TablePress admin screens).
97	add_filter( 'admin_footer_text', array( $this, '_admin_footer_text' ) );
98	}
99
100	/**
101	* Adds a TablePress "Thank You" message to the admin footer content.
102	*
103	* @since 1.0.0
104	*
105	* @param string $content Current admin footer content.
106	* @return string New admin footer content.
107	*/
108	public function _admin_footer_text( /* string */ $content ): string {
109	// Don't use a type hint in the method declaration as many WordPress plugins use the `admin_footer_text` filter in the wrong way.
110
111	// Protect against other plugins not returning a string in their filter callbacks.
112	if ( ! is_string( $content ) ) {
113	$content = '';
114	}
115
116	$content .= ' • ' . sprintf( __( 'Thank you for using <a href="%s">TablePress</a>.', 'tablepress' ), 'https://tablepress.org/' );
117	if ( tb_tp_fs()->is_free_plan() ) {
118	$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' );
119	}
120	return $content;
121	}
122
123	/**
124	* Print the JavaScript code for a WP feature pointer.
125	*
126	* @since 1.0.0
127	*
128	* @param string $pointer_id The pointer ID.
129	* @param string $selector The HTML elements, on which the pointer should be attached.
130	* @param array<string, mixed> $args Arguments to be passed to the pointer JS (see wp-pointer.js).
131	*/
132	public function print_wp_pointer_js( string $pointer_id, string $selector, array $args ): void {
133	if ( empty( $pointer_id ) \|\| empty( $selector ) \|\| empty( $args['content'] ) ) {
134	return;
135	}
136
137	/*
138	* Print JS code for the feature pointers, extened with event handling for opened/closed "Screen Options", so that pointers can
139	* be repositioned. 210 ms is slightly slower than jQuery's "fast" value, to allow all elements to reach their original position.
140	*/
141	?>
142	<script>
143	( function( $ ) {
144	let options = <?php echo wp_json_encode( $args, TABLEPRESS_JSON_OPTIONS ); ?>;
145
146	if ( ! options ) {
147	return;
148	}
149
150	options = $.extend( options, {
151	close: function() {
152	$.post( ajaxurl, {
153	pointer: '<?php echo $pointer_id; ?>',
154	action: 'dismiss-wp-pointer'
155	} );
156	$( this ).pointer( { 'disabled': true } );
157	}
158	} );
159
160	$( function () {
161	$( '<?php echo $selector; ?>' ).pointer( options ).pointer( 'open' );
162	} );
163
164	$( document ).on( 'screen:options:open screen:options:close', function () {
165	setTimeout( function () { $( '<?php echo $selector; ?>' ).pointer( 'reposition' ); }, 210 );
166	} );
167	} )( jQuery );
168	</script>
169	<?php
170	}
171
172	/**
173	* Returns a safe JSON representation of a variable for printing inside of JavaScript code.
174	*
175	* @since 2.0.0
176	*
177	* @param mixed $data Variable to convert to JSON.
178	* @return string Safe JSON representation of a variable for printing inside of JavaScript code.
179	*/
180	public function convert_to_json_parse_output( /* string\|array\|bool\|int\|float\|null */ $data ): string {
181	$json = wp_json_encode( $data, TABLEPRESS_JSON_OPTIONS );
182	if ( false === $json ) {
183	// JSON encoding failed, return an error object. Use a prefixed "_error" key to avoid conflicts with intentionally added "error" keys.
184	$json = '{ "_error": "The data could not be encoded to JSON!" }';
185	}
186	// Print them inside a `JSON.parse()` call in JS for speed gains, with necessary escaping of `</script>`, `'`, and `\`.
187	$json = str_replace( array( '</script>', '\\', "'" ), array( '<\/script>', '\\\\', "\'" ), $json );
188	return "JSON.parse( '{$json}' )";
189	}
190
191	} // class TablePress_Admin_Page
192