Documentation

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
codeCoverageIgnore
since
2.0.0

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

$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()

$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_) and the value is the label and title.

$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()

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

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_filter_by_status()

Prints the available statuses so the user can click to filter.

protected display_filter_by_status() : 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_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
global

wpdb $wpdb

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
global

wpdb $wpdb

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

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_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
$row : array<string|int, mixed>

Row to render

$column_name :

Current row

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

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 = ''
Return values
mixed

Search results