ActionScheduler_Abstract_ListTable
extends WP_List_Table
in package
Action Scheduler Abstract List Table class
This abstract class enhances WP_List_Table making it ready to use.
By extending this class we can focus on describing how our table looks like, which columns needs to be shown, filter, ordered by and more and forget about the details.
This class supports:
- Bulk actions
- Search
- Sortable columns
- Automatic translations of the columns
Tags
Table of Contents
- $admin_notices : array<string|int, mixed>
- $bulk_actions : mixed
- Enables bulk actions. It must be an array where the key is the action name and the value is the label (which is translated automatically). It is important to notice that it will check that the method exists (`bulk_$name`) and will throw an exception if it does not exists.
- $columns : mixed
- Columns to show in the table listing. It is a key => value pair. The key must much the table column name and the value is the label, which is automatically translated.
- $filter_by : mixed
- $ID : mixed
- The Primary key of our table
- $items_per_page : mixed
- How many items do we render per page?
- $package : mixed
- Package name, used in translations
- $row_actions : mixed
- Defines the row-actions. It expects an array where the key is the column name and the value is an array of actions.
- $search_by : mixed
- Enables search in this table listing. If this array is empty it means the listing is not searchable.
- $sort_by : mixed
- Enables sorting, it expects an array of columns (the column names are the values)
- $status_counts : array<string|int, mixed>
- $table_header : string
- $table_name : mixed
- The table name
- column_cb() : mixed
- Renders the checkbox for each row, this is the first column and it is named ID regardless of how the primary key is named (to keep the code simpler). The bulk actions will do the proper name transformation though using `$this->ID`.
- column_default() : mixed
- Default column formatting, it will escape everythig for security.
- display_page() : mixed
- Render the list table page, including header, notices, status filters and table.
- extra_tablenav() : mixed
- get_columns() : mixed
- Returns the columns names for rendering. It adds a checkbox for selecting everything as the first column
- get_sortable_columns() : mixed
- Reads $this->sort_by and returns the columns name in a format that WP_Table_List expects
- prepare_items() : mixed
- Prepares the data to feed WP_Table_List.
- bulk_delete() : mixed
- Default code for deleting entries. We trust ids_sql because it is validated already by process_bulk_action()
- display_admin_notices() : mixed
- Display the table heading and search query, if any
- display_filter_by_status() : mixed
- Prints the available statuses so the user can click to filter.
- display_header() : mixed
- Display the table heading and search query, if any
- display_table() : mixed
- Renders the table list, we override the original class to render the table inside a form and to render any needed HTML (like the search box). By doing so the callee of a function can simple forget about any extra HTML.
- get_bulk_actions() : mixed
- Reads `$this->bulk_actions` and returns an array that WP_List_Table understands. It also validates that the bulk method handler exists. It throws an exception because this is a library meant for developers and missing a bulk method is a development-time error.
- get_items_offset() : int
- Returns the number of items to offset/skip for this current view.
- get_items_query_filters() : mixed
- Prepares the SQL to filter rows by the options defined at `$this->filter_by`. Before trusting any data sent by the user it validates that it is a valid option.
- get_items_query_limit() : string
- Get prepared LIMIT clause for items query
- get_items_query_offset() : string
- Get prepared OFFSET clause for items query
- get_items_query_order() : mixed
- Prepares the ORDER BY sql statement. It uses `$this->sort_by` to know which columns are sortable. This requests validates the orderby $_GET parameter is a valid column and sortable. It will also use order (ASC|DESC) using DESC by default.
- get_items_query_search() : string
- Check if the current request is doing a "full text" search. If that is the case prepares the SQL to search texts using LIKE.
- get_request_order() : string
- Return the sortable column order specified for this request.
- get_request_orderby() : string
- Return the sortable column specified for this request to order the results by, if any.
- get_request_search_query() : string
- Return the search filter for this request, if any.
- get_request_status() : string
- Return the status filter for this request, if any.
- get_search_box_placeholder() : mixed
- Get the text to display in the search box on the list table.
- get_table_columns() : array<string|int, mixed>
- Process and return the columns name. This is meant for using with SQL, this means it always includes the primary key.
- maybe_render_actions() : mixed
- Renders the row-actions.
- prepare_column_headers() : mixed
- Prepares the _column_headers property which is used by WP_Table_List at rendering.
- process_bulk_action() : mixed
- Checks if the current request has a bulk action. If that is the case it will validate and will execute the bulk method handler. Regardless if the action is valid or not it will redirect to the previous page removing the current arguments that makes this request a bulk action.
- process_row_actions() : mixed
- set_items() : mixed
- Set the data for displaying. It will attempt to unserialize (There is a chance that some columns are serialized). This can be override in child classes for futher data transformation.
- translate() : mixed
- Makes translation easier, it basically just wraps `_x` with some default (the package name)
Properties
$admin_notices
protected
array<string|int, mixed>
$admin_notices
= array()
$bulk_actions
Enables bulk actions. It must be an array where the key is the action name and the value is the label (which is translated automatically). It is important to notice that it will check that the method exists (`bulk_$name`) and will throw an exception if it does not exists.
protected
mixed
$bulk_actions
= array()
This class will automatically check if the current request has a bulk action, will do the
validations and afterwards will execute the bulk method, with two arguments. The first argument
is the array with primary keys, the second argument is a string with a list of the primary keys,
escaped and ready to use (with IN
).
$columns
Columns to show in the table listing. It is a key => value pair. The key must much the table column name and the value is the label, which is automatically translated.
protected
mixed
$columns
= array()
$filter_by
protected
mixed
$filter_by
= array()
$ID
The Primary key of our table
protected
mixed
$ID
= 'ID'
$items_per_page
How many items do we render per page?
protected
mixed
$items_per_page
= 10
$package
Package name, used in translations
protected
mixed
$package
$row_actions
Defines the row-actions. It expects an array where the key is the column name and the value is an array of actions.
protected
mixed
$row_actions
= array()
The array of actions are key => value, where key is the method name
(with the prefix row_action_
$search_by
Enables search in this table listing. If this array is empty it means the listing is not searchable.
protected
mixed
$search_by
= array()
$sort_by
Enables sorting, it expects an array of columns (the column names are the values)
protected
mixed
$sort_by
= array()
$status_counts
protected
array<string|int, mixed>
$status_counts
= array()
$table_header
protected
string
$table_header
$table_name
The table name
protected
mixed
$table_name
Methods
column_cb()
Renders the checkbox for each row, this is the first column and it is named ID regardless of how the primary key is named (to keep the code simpler). The bulk actions will do the proper name transformation though using `$this->ID`.
public
column_cb(mixed $row) : mixed
Parameters
- $row : mixed
Return values
mixed —column_default()
Default column formatting, it will escape everythig for security.
public
column_default(mixed $item, mixed $column_name) : mixed
Parameters
- $item : mixed
- $column_name : mixed
Return values
mixed —display_page()
Render the list table page, including header, notices, status filters and table.
public
display_page() : mixed
Return values
mixed —extra_tablenav()
public
extra_tablenav(mixed $which) : mixed
Parameters
- $which : mixed
Return values
mixed —get_columns()
Returns the columns names for rendering. It adds a checkbox for selecting everything as the first column
public
get_columns() : mixed
Return values
mixed —get_sortable_columns()
Reads $this->sort_by and returns the columns name in a format that WP_Table_List expects
public
get_sortable_columns() : mixed
Return values
mixed —prepare_items()
Prepares the data to feed WP_Table_List.
public
prepare_items() : mixed
This has the core for selecting, sorting and filting data. To keep the code simple its logic is split among many methods (get_items_query_*).
Beside populating the items this function will also count all the records that matches the filtering criteria and will do fill the pagination variables.
Return values
mixed —bulk_delete()
Default code for deleting entries. We trust ids_sql because it is validated already by process_bulk_action()
protected
bulk_delete(array<string|int, mixed> $ids, mixed $ids_sql) : mixed
Parameters
- $ids : array<string|int, mixed>
- $ids_sql : mixed
Return values
mixed —display_admin_notices()
Display the table heading and search query, if any
protected
display_admin_notices() : mixed
Return values
mixed —display_filter_by_status()
Prints the available statuses so the user can click to filter.
protected
display_filter_by_status() : mixed
Return values
mixed —display_header()
Display the table heading and search query, if any
protected
display_header() : mixed
Return values
mixed —display_table()
Renders the table list, we override the original class to render the table inside a form and to render any needed HTML (like the search box). By doing so the callee of a function can simple forget about any extra HTML.
protected
display_table() : mixed
Return values
mixed —get_bulk_actions()
Reads `$this->bulk_actions` and returns an array that WP_List_Table understands. It also validates that the bulk method handler exists. It throws an exception because this is a library meant for developers and missing a bulk method is a development-time error.
protected
get_bulk_actions() : mixed
Return values
mixed —get_items_offset()
Returns the number of items to offset/skip for this current view.
protected
get_items_offset() : int
Return values
int —get_items_query_filters()
Prepares the SQL to filter rows by the options defined at `$this->filter_by`. Before trusting any data sent by the user it validates that it is a valid option.
protected
get_items_query_filters() : mixed
Return values
mixed —get_items_query_limit()
Get prepared LIMIT clause for items query
protected
get_items_query_limit() : string
Tags
Return values
string —Prepared LIMIT clause for items query.
get_items_query_offset()
Get prepared OFFSET clause for items query
protected
get_items_query_offset() : string
Tags
Return values
string —Prepared OFFSET clause for items query.
get_items_query_order()
Prepares the ORDER BY sql statement. It uses `$this->sort_by` to know which columns are sortable. This requests validates the orderby $_GET parameter is a valid column and sortable. It will also use order (ASC|DESC) using DESC by default.
protected
get_items_query_order() : mixed
Return values
mixed —get_items_query_search()
Check if the current request is doing a "full text" search. If that is the case prepares the SQL to search texts using LIKE.
protected
get_items_query_search() : string
If the current request does not have any search or if this list table does not support that feature it will return an empty string.
TODO:
- Improve search doing LIKE by word rather than by phrases.
Return values
string —get_request_order()
Return the sortable column order specified for this request.
protected
get_request_order() : string
Return values
string —get_request_orderby()
Return the sortable column specified for this request to order the results by, if any.
protected
get_request_orderby() : string
Return values
string —get_request_search_query()
Return the search filter for this request, if any.
protected
get_request_search_query() : string
Return values
string —get_request_status()
Return the status filter for this request, if any.
protected
get_request_status() : string
Return values
string —get_search_box_placeholder()
Get the text to display in the search box on the list table.
protected
get_search_box_placeholder() : mixed
Return values
mixed —get_table_columns()
Process and return the columns name. This is meant for using with SQL, this means it always includes the primary key.
protected
get_table_columns() : array<string|int, mixed>
Return values
array<string|int, mixed> —maybe_render_actions()
Renders the row-actions.
protected
maybe_render_actions(array<string|int, mixed> $row, $column_name) : mixed
This method renders the action menu, it reads the definition from the $row_actions property, and it checks that the row action method exists before rendering it.
Parameters
Return values
mixed —prepare_column_headers()
Prepares the _column_headers property which is used by WP_Table_List at rendering.
protected
prepare_column_headers() : mixed
It merges the columns and the sortable columns.
Return values
mixed —process_bulk_action()
Checks if the current request has a bulk action. If that is the case it will validate and will execute the bulk method handler. Regardless if the action is valid or not it will redirect to the previous page removing the current arguments that makes this request a bulk action.
protected
process_bulk_action() : mixed
Return values
mixed —process_row_actions()
protected
process_row_actions() : mixed
Return values
mixed —set_items()
Set the data for displaying. It will attempt to unserialize (There is a chance that some columns are serialized). This can be override in child classes for futher data transformation.
protected
set_items(array<string|int, mixed> $items) : mixed
Parameters
- $items : array<string|int, mixed>
Return values
mixed —translate()
Makes translation easier, it basically just wraps `_x` with some default (the package name)
protected
translate(mixed $text[, mixed $context = '' ]) : mixed
Parameters
- $text : mixed
- $context : mixed = ''