Documentation

ActionScheduler_ListTable extends ActionScheduler_Abstract_ListTable
in package

Implements the admin view of the actions.

Tags
codeCoverageIgnore

Table of Contents

$admin_notices  : array<string|int, mixed>
$bulk_actions  : array<string|int, mixed>
Bulk actions. The key of the array is the method name of the implementation:
$columns  : array<string|int, mixed>
Columns to show (name => label).
$did_notification  : bool
Flag variable to render our notifications, if any, once.
$filter_by  : mixed
$ID  : mixed
The Primary key of our table
$items_per_page  : mixed
How many items do we render per page?
$logger  : ActionScheduler_Logger
A logger to use for getting action logs to display
$package  : string
The package name.
$row_actions  : array<string|int, mixed>
Actions (name => label).
$runner  : ActionScheduler_QueueRunner
A ActionScheduler_QueueRunner runner instance (or child class)
$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>
$store  : ActionScheduler_Store
The active data stores
$table_header  : string
$table_name  : mixed
The table name
$time_periods  : array<string|int, mixed>
Array of seconds for common time periods, like week or month, alongside an internationalised string representation, i.e. "Day" or "Days"
__construct()  : mixed
Sets the current data store object into `store->action` and initialises the object.
column_args()  : string
Serializes the argument of an action to render it in a human friendly format.
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.
column_log_entries()  : string
Prints the logs entries inline. We do so to avoid loading Javascript and other hacks to show it in a modal.
column_schedule()  : string
Prints the scheduled date in a human friendly format.
display_admin_notices()  : mixed
Renders admin notifications
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
Bulk delete
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_log_entry_html()  : string
Prints the logs entries inline. We do so to avoid loading Javascript and other hacks to show it in a modal.
get_recurrence()  : string
Returns the recurrence of an action or 'Non-repeating'. The output is human readable.
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_schedule_display_string()  : string
Get the scheduled date in a human friendly format.
get_search_box_button_text()  : mixed
Get the text to display in the search box on the list table.
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()  : string
Only display row actions for pending 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_action()  : mixed
Implements the logic behind processing an action once an action link is clicked on the list table.
process_row_actions()  : mixed
row_action_cancel()  : mixed
Implements the logic behind running an action. ActionScheduler_Abstract_ListTable validates the request and their parameters are valid.
row_action_run()  : mixed
Implements the logic behind running an action. ActionScheduler_Abstract_ListTable validates the request and their parameters are valid.
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)
human_interval()  : string
Convert an interval of seconds into a two part human friendly string.

Properties

$bulk_actions

Bulk actions. The key of the array is the method name of the implementation:

protected array<string|int, mixed> $bulk_actions = array()

bulk_(array $ids, string $sql_in).

See the comments in the parent class for further details

$did_notification

Flag variable to render our notifications, if any, once.

protected static bool $did_notification = alse

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

$time_periods

Array of seconds for common time periods, like week or month, alongside an internationalised string representation, i.e. "Day" or "Days"

private static array<string|int, mixed> $time_periods

Methods

column_args()

Serializes the argument of an action to render it in a human friendly format.

public column_args(array<string|int, mixed> $row) : string
Parameters
$row : array<string|int, mixed>

The array representation of the current row of the table

Return values
string

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

column_log_entries()

Prints the logs entries inline. We do so to avoid loading Javascript and other hacks to show it in a modal.

public column_log_entries(array<string|int, mixed> $row) : string
Parameters
$row : array<string|int, mixed>

Action array.

Return values
string

column_schedule()

Prints the scheduled date in a human friendly format.

public column_schedule(array<string|int, mixed> $row) : string
Parameters
$row : array<string|int, mixed>

The array representation of the current row of the table

Return values
string

display_admin_notices()

Renders admin notifications

public display_admin_notices() : mixed

Notifications:

  1. When the maximum number of tasks are being executed simultaneously
  2. Notifications when a task us manually executed
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
Return values
mixed

bulk_delete()

Bulk delete

protected bulk_delete(array<string|int, mixed> $ids, string $ids_sql) : mixed

Deletes actions based on their ID. This is the handler for the bulk delete. It assumes the data properly validated by the callee and it will delete the actions without any extra validation.

Parameters
$ids : array<string|int, mixed>
$ids_sql : string

Inherited and unused

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

Get the text to display in the search box on the list table.

protected get_search_box_button_text() : mixed
Return values
mixed

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

Only display row actions for pending actions.

protected maybe_render_actions(array<string|int, mixed> $row, string $column_name) : string
Parameters
$row : array<string|int, mixed>

Row to render

$column_name : string

Current row

Return values
string

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

Implements the logic behind processing an action once an action link is clicked on the list table.

protected process_row_action(int $action_id, string $row_action_type) : mixed
Parameters
$action_id : int
$row_action_type : string

The type of action to perform on the action.

Return values
mixed

row_action_cancel()

Implements the logic behind running an action. ActionScheduler_Abstract_ListTable validates the request and their parameters are valid.

protected row_action_cancel(int $action_id) : mixed
Parameters
$action_id : int
Return values
mixed

row_action_run()

Implements the logic behind running an action. ActionScheduler_Abstract_ListTable validates the request and their parameters are valid.

protected row_action_run(int $action_id) : mixed
Parameters
$action_id : int
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

human_interval()

Convert an interval of seconds into a two part human friendly string.

private static human_interval(int $interval[, int $periods_to_include = 2 ]) : string

The WordPress human_time_diff() function only calculates the time difference to one degree, meaning even if an action is 1 day and 11 hours away, it will display "1 day". This function goes one step further to display two degrees of accuracy.

Inspired by the Crontrol::interval() function by Edward Dale: https://wordpress.org/plugins/wp-crontrol/

Parameters
$interval : int

A interval in seconds.

$periods_to_include : int = 2

Depth of time periods to include, e.g. for an interval of 70, and $periods_to_include of 2, both minutes and seconds would be included. With a value of 1, only minutes would be included.

Return values
string

A human friendly string representation of the interval.

Search results