tablepress / views / class-editor-button-thickbox-list-table.php

class-editor-button-thickbox-list-table.php in TablePress – Tables in WordPress made easy 3.3.4, at views/class-editor-button-thickbox-list-table.php

377 lines 11.7 KB

Raw Download Zip

1	<?php
2	/**
3	* Editor Button Thickbox List Table
4	*
5	* @package TablePress
6	* @subpackage Views
7	* @author Tobias Bäthge
8	* @since 2.0.0
9	*/
10
11	// Prohibit direct script loading.
12	defined( 'ABSPATH' ) \|\| die( 'No direct script access allowed!' );
13
14	/**
15	* TablePress Editor Button Thickbox List Table Class
16	*
17	* @package TablePress
18	* @subpackage Views
19	* @author Tobias Bäthge
20	* @since 1.0.0
21	*/
22	class TablePress_Editor_Button_Thickbox_List_Table extends WP_List_Table {
23
24	/**
25	* Number of items of the initial data set (before sort, search, and pagination).
26	*
27	* @since 1.0.0
28	*/
29	protected int $items_count = 0;
30
31	/**
32	* Initializes the List Table.
33	*
34	* @since 1.0.0
35	*/
36	public function __construct() {
37	// @phpstan-ignore argument.type (WordPress Core's docblocks state wrong argument types in some places.)
38	parent::__construct( array(
39	'singular' => 'tablepress-table', // Singular name of the listed records.
40	'plural' => 'tablepress-editor-button-list', // Plural name of the listed records.
41	'ajax' => false, // Does this list table support AJAX?
42	'screen' => get_current_screen(), // WP_Screen object.
43	) );
44	}
45
46	/**
47	* Sets the data items (here: tables) that are to be displayed by the List Tables, and their original count.
48	*
49	* @since 1.0.0
50	*
51	* @param string[] $items Tables to be displayed in the List Table.
52	*/
53	public function set_items( array $items ): void {
54	$this->items = $items;
55	$this->items_count = count( $items );
56	}
57
58	/**
59	* Checks whether the user has permissions for certain AJAX actions.
60	* (not used, but must be implemented in this child class)
61	*
62	* @since 1.0.0
63	*
64	* @return bool true (Default value).
65	*/
66	#[\Override]
67	public function ajax_user_can(): bool {
68	return true;
69	}
70
71	/**
72	* Gets a list of columns in this List Table.
73	*
74	* Format: 'internal-name' => 'Column Title'.
75	*
76	* @since 1.0.0
77	*
78	* @return array<string, string> List of columns in this List Table.
79	*/
80	#[\Override]
81	public function get_columns(): array {
82	$columns = array(
83	// "name" is special in WP, which is why we prefix every entry here, to be safe!
84	'table_id' => __( 'ID', 'tablepress' ),
85	'table_name' => __( 'Table Name', 'tablepress' ),
86	'table_description' => __( 'Description', 'tablepress' ),
87	'table_action' => __( 'Action', 'tablepress' ),
88	);
89	return $columns;
90	}
91
92	/**
93	* Gets a list of columns that are sortable.
94	*
95	* Format: 'internal-name' => array( $field for $item[ $field ], true for already sorted ).
96	*
97	* @since 1.0.0
98	*
99	* @return array<string, array{string, bool}> List of sortable columns in this List Table.
100	*/
101	#[\Override]
102	protected function get_sortable_columns(): array {
103	// No sorting on the Empty List placeholder.
104	if ( ! $this->has_items() ) {
105	return array();
106	}
107
108	$sortable_columns = array(
109	'table_id' => array( 'id', true ), // true means its already sorted.
110	'table_name' => array( 'name', false ),
111	'table_description' => array( 'description', false ),
112	);
113	return $sortable_columns;
114	}
115
116	/**
117	* Gets the name of the default primary column.
118	*
119	* @since 1.7.0
120	*
121	* @return string Name of the default primary column, in this case, the table name.
122	*/
123	#[\Override]
124	protected function get_default_primary_column_name(): string {
125	return 'table_name';
126	}
127
128	/**
129	* Renders a cell in the "table_id" column.
130	*
131	* @since 1.0.0
132	*
133	* @param array<string, mixed> $item Data item for the current row.
134	* @return string HTML content of the cell.
135	*/
136	protected function column_table_id( array $item ): string {
137	return esc_html( $item['id'] );
138	}
139
140	/**
141	* Returns a clean label for the primary (Table Name) column's row header `aria-label`.
142	*
143	* Provides screen readers with just the table name as the row header name,
144	* preventing them from computing the name from the full cell content.
145	*
146	* @since 3.3.4
147	*
148	* @param array<string, mixed> $item Data item for the current row.
149	* @return string The table name.
150	*/
151	protected function get_primary_column_aria_label( /* array */ $item ): string {
152	// Don't use type hints in the method declaration to prevent PHP errors, as the method is inherited.
153
154	return trim( $item['name'] );
155	}
156
157	/**
158	* Renders a cell in the "table_name" column.
159	*
160	* @since 1.0.0
161	*
162	* @param array<string, mixed> $item Data item for the current row.
163	* @return string HTML content of the cell.
164	*/
165	protected function column_table_name( array $item ): string {
166	if ( '' === trim( $item['name'] ) ) {
167	$item['name'] = __( '(no name)', 'tablepress' );
168	}
169	return esc_html( $item['name'] );
170	}
171
172	/**
173	* Renders a cell in the "table_description" column.
174	*
175	* @since 1.0.0
176	*
177	* @param array<string, mixed> $item Data item for the current row.
178	* @return string HTML content of the cell.
179	*/
180	protected function column_table_description( array $item ): string {
181	if ( '' === trim( $item['description'] ) ) {
182	$item['description'] = __( '(no description)', 'tablepress' );
183	}
184	return esc_html( $item['description'] );
185	}
186
187	/**
188	* Renders a cell in the "table_action" column, i.e. the "Insert" link.
189	*
190	* @since 1.0.0
191	*
192	* @param array<string, mixed> $item Data item for the current row.
193	* @return string HTML content of the cell.
194	*/
195	protected function column_table_action( array $item ): string {
196	return '<input type="button" class="insert-shortcode button button-compact" title="' . esc_attr( '[' . TablePress::$shortcode . " id={$item['id']} /]" ) . '" value="' . esc_attr__( 'Insert Shortcode', 'tablepress' ) . '">';
197	}
198
199	/**
200	* Holds the message to be displayed when there are no items in the table.
201	*
202	* @since 1.0.0
203	*/
204	#[\Override]
205	public function no_items(): void {
206	_e( 'No tables found.', 'tablepress' );
207	if ( 0 === $this->items_count ) {
208	echo ' ' . __( 'You should add or import a table on the TablePress screens to get started!', 'tablepress' );
209	}
210	}
211
212	/**
213	* Generates the elements above or below the table (like bulk actions and pagination).
214	*
215	* In comparison with parent class, this has modified HTML (no nonce field), and a check whether there are items.
216	*
217	* @since 1.0.0
218	*
219	* @param 'top'\|'bottom' $which Location ("top" or "bottom").
220	*/
221	#[\Override]
222	protected function display_tablenav( /* string */ $which ): void {
223	// Don't use type hints in the method declaration to prevent PHP errors, as the method is inherited.
224
225	if ( ! $this->has_items() ) {
226	return;
227	}
228	?>
229	<div class="tablenav <?php echo esc_attr( $which ); ?>">
230	<div class="alignleft actions">
231	<?php $this->bulk_actions( $which ); ?>
232	</div>
233	<?php
234	$this->extra_tablenav( $which );
235
236	add_filter( 'ngettext_default', array( $this, 'change_pagination_items_string' ), 10, 5 );
237	$this->pagination( $which );
238	remove_filter( 'ngettext_default', array( $this, 'change_pagination_items_string' ), 10 );
239	?>
240	<br class="clear">
241	</div>
242	<?php
243	}
244
245	/**
246	* Replaces the "%s item/%s items" string in the pagination with "%s table/%s tables".
247	*
248	* @since 2.0.0
249	*
250	* @param string $translation The current translation of a singular or plural form.
251	* @param string $single The text to be used if the number is singular.
252	* @param string $plural The text to be used if the number is plural.
253	* @param int $number The number to compare against to use either the singular or plural form.
254	* @param string $domain Text domain. Defaults to 'default'.
255	* @return string The changed translation.
256	*/
257	public function change_pagination_items_string( string $translation, string $single, string $plural, int $number, string $domain ): string {
258	if ( '%s item' === $single && '%s items' === $plural ) {
259	/* translators: %s: Number of tables */
260	$translation = _n( '%s table', '%s tables', $number, 'tablepress' );
261	}
262	return $translation;
263	}
264
265	/**
266	* Callback to determine whether the given $item contains the search term.
267	*
268	* @since 1.0.0
269	*
270	* @param string $item Table ID that shall be searched.
271	* @return bool Whether the search term was found or not.
272	*/
273	protected function _search_callback( string $item ): bool {
274	static $term;
275	static $json_encoded_term;
276	if ( is_null( $term ) \|\| is_null( $json_encoded_term ) ) {
277	$term = wp_unslash( $_GET['s'] );
278	$json_encoded_term = substr( wp_json_encode( $term, TABLEPRESS_JSON_OPTIONS ), 1, -1 ); // @phpstan-ignore argument.type
279	}
280
281	// Load table again, with table data, but without options and visibility settings.
282	$item = TablePress::$model_table->load( $item, true, false );
283
284	if ( is_wp_error( $item ) ) {
285	return false;
286	}
287
288	// Don't search corrupted tables.
289	if ( isset( $item['is_corrupted'] ) && $item['is_corrupted'] ) {
290	return false;
291	}
292
293	$fn_stripos = function_exists( 'mb_stripos' ) ? 'mb_stripos' : 'stripos';
294
295	// Search from easy to hard, so that "expensive" code maybe doesn't have to run.
296	if ( false !== $fn_stripos( $item['id'], (string) $term )
297	\|\| false !== $fn_stripos( $item['name'], (string) $term )
298	\|\| false !== $fn_stripos( $item['description'], (string) $term )
299	\|\| false !== $fn_stripos( TablePress::get_user_display_name( $item['author'] ), (string) $term )
300	\|\| false !== $fn_stripos( TablePress::format_datetime( $item['last_modified'] ), (string) $term )
301	\|\| false !== $fn_stripos( wp_json_encode( $item['data'], TABLEPRESS_JSON_OPTIONS ), (string) $json_encoded_term ) ) { // @phpstan-ignore argument.type
302	return true;
303	}
304
305	return false;
306	}
307
308	/**
309	* Callback to for the array sort function.
310	*
311	* @since 1.0.0
312	*
313	* @param array<string, mixed> $item_a First item that shall be compared to.
314	* @param array<string, mixed> $item_b The second item for the comparison.
315	* @return int (-1, 0, 1) depending on which item sorts "higher".
316	*/
317	protected function _order_callback( array $item_a, array $item_b ): int {
318	global $orderby, $order;
319
320	if ( $item_a[ $orderby ] === $item_b[ $orderby ] ) {
321	return 0;
322	}
323
324	// Fields in this list table are all strings.
325	$result = strnatcasecmp( $item_a[ $orderby ], $item_b[ $orderby ] );
326
327	return ( 'asc' === $order ) ? $result : - $result;
328	}
329
330	/**
331	* Prepares the list of items for displaying, by maybe searching and sorting, and by doing pagination.
332	*
333	* @since 1.0.0
334	*/
335	#[\Override]
336	public function prepare_items(): void {
337	global $orderby, $order, $s;
338	wp_reset_vars( array( 'orderby', 'order', 's' ) );
339
340	// Maybe search in the items.
341	if ( $s ) {
342	$this->items = array_filter( $this->items, array( $this, '_search_callback' ) );
343	}
344
345	// Load actual tables after search for less memory consumption.
346	foreach ( $this->items as &$item ) {
347	// Don't load data nor table options.
348	$item = TablePress::$model_table->load( $item, false, false );
349	}
350	unset( $item ); // Unset use-by-reference parameter of foreach loop.
351
352	// Maybe sort the items.
353	$_sortable_columns = $this->get_sortable_columns();
354	if ( $orderby && ! empty( $this->items ) && isset( $_sortable_columns[ "table_{$orderby}" ] ) ) {
355	usort( $this->items, array( $this, '_order_callback' ) );
356	}
357
358	// Number of records to show per page.
359	$per_page = 20; // Hard-coded, as there's no possibility to change this in the Thickbox.
360	// Page number the user is currently viewing.
361	$current_page = $this->get_pagenum();
362	// Number of records in the array.
363	$total_items = count( $this->items );
364
365	// Slice items array to hold only items for the current page.
366	$this->items = array_slice( $this->items, ( ( $current_page - 1 ) * $per_page ), $per_page );
367
368	// Register pagination options and calculation results.
369	$this->set_pagination_args( array(
370	'total_items' => $total_items, // Total number of records/items.
371	'per_page' => $per_page, // Number of items per page.
372	'total_pages' => (int) ceil( $total_items / $per_page ), // Total number of pages.
373	) );
374	}
375
376	} // class TablePress_Editor_Button_Thickbox_List_Table
377