Class WPDP_Project_Page_List_View extends WPDP_Child_List_Table_View

This class implements the lookup functionality. A lookup is the opposite of a one to many relationship. (1) A lookup provides the user with a listbox of possible values (2) A lookup offers the user comfort to search in lookup strings (e.g. titles or descriptions)

see \WPDataProjects\Parent_Child\WPDP_Child_List_Table_View
author Peter Schulz
since 2.0.0
package WPDataProjects\Project
inherited_from \WPDataProjects\Parent_Child\WPDP_Child_List_Table_View

 Methods

WPDP_Project_Page_List_View constructor

__construct(array $args = array()

A table name must be provided in the constructor call. The table must be a valid MySQL database table to which acces (to the back-end) is granted. If no table name is provided, the table does not exist or access to the back-end for the given table is not granted, processing is stopped. It makes no sense to continue without a valid table. A check for table existence is performed to prevent SQL injection.

There are two types of tables to build a list table on:

  • List of tables in the WordPress database schema
  • List of rows in a specific table

To build a list of tables in the WordPress database schema, we query table 'information_schema.tables' (which is in fact a view). This is the only query allowed outside the WordPress database schema. The table/view name is stored in constant WPDA_List_Table::LIST_BASE_TABLE for validation purposes.

A list of rows for a specific table is based on WordPress class WP_List_Table.

WPDA_List_Table can be used to build list tables for views as well. View based list tables however, do not support insert, update, delete, import and export actions.

A table name is not the only thing we need to build a list table. We also need to have access to the table columns. If no table columns are provided execution is stopped as well.

inherited_from \WPDataProjects\Parent_Child\WPDP_Child_List_Table_View::__construct()

Parameters

$args

array

WPDA_List_Table constructor

__construct(array $args = array()
Inherited

A table name must be provided in the constructor call. The table must be a valid MySQL database table to which acces (to the back-end) is granted. If no table name is provided, the table does not exist or access to the back-end for the given table is not granted, processing is stopped. It makes no sense to continue without a valid table. A check for table existence is performed to prevent SQL injection.

There are two types of tables to build a list table on:

  • List of tables in the WordPress database schema
  • List of rows in a specific table

To build a list of tables in the WordPress database schema, we query table 'information_schema.tables' (which is in fact a view). This is the only query allowed outside the WordPress database schema. The table/view name is stored in constant WPDA_List_Table::LIST_BASE_TABLE for validation purposes.

A list of rows for a specific table is based on WordPress class WP_List_Table.

WPDA_List_Table can be used to build list tables for views as well. View based list tables however, do not support insert, update, delete, import and export actions.

A table name is not the only thing we need to build a list table. We also need to have access to the table columns. If no table columns are provided execution is stopped as well.

since 1.0.0

Parameters

$args

array

[

'table_name' => (string) Database table name

'wpda_list_columns' => (object) Reference to a WPDA_List_Columns object

'singular' => (string) Singular object label

'plural' => (string) lural object label

'ajax' => (string) TRUE = list table support Ajax

'column_headers' => (array|string) Column headers

'title' => (string) Page title

'subtitle' => (string) Page subtitle

'bulk_export_enabled' => (boolean)

'search_box_enabled' => (boolean)

'bulk_actions_enabled' => (boolean)

'show_view_link' => (string) on|off

'allow_insert' => (string) on|off

'allow_update' => (string) on|off

'allow_delete' => (string) on|off

'allow_import' => (string) on|off

'hide_navigation' => (boolean)

'default_where' => (string)

]

Render bulk edit checkbox

column_cb(array $item) : string
Inherited
since 1.0.0

Parameters

$item

array

Column list.

Returns

stringContent for checkbox column.

Render columns

column_default(array $item, string $column_name) : mixed
Inherited

Three links are provided for every list table row:

  • 'View' => Link to view form (readonly data entry form)
  • 'Edit' => Link to data entry form (updatable)
  • 'Delete' => Link to delete record from database table

Links to view, edit and delete records are only available if a primary key for the table is found. Without a primary key unique identification of records is not possible.

Links to action are offered through hidden forms to prevent long URL's and problem when refreshing pages manually. More information about how and why is provided in source code at place where I thoug the information could be helpful.

since 1.0.0

Parameters

$item

array

Column info.

$column_name

string

Column name.

Returns

mixedValue display in list table column

column_media_attachment()

column_media_attachment($url, $title, $mime_type) 
InheritedStatic

Parameters

$url

$title

$mime_type

Delete record from database table

delete_row(string $where) : mixed
Inherited

The table must have a primary key and the values for all primary key colummns must be provided in the request. The where clause must be a named array in format: ['column_name'] = 'value'

since 1.0.0

Parameters

$where

string

Where clause.

Returns

mixed

Returns an associative array containing the bulk action

get_bulk_actions() : array
Inherited
since 1.0.0

Returns

array

Return an associative array of columns

get_columns() : array
Inherited
since 1.0.0

Returns

array

Perform query to retrieve rows from database

get_rows() 
Inherited

Where clause must be prepared in advance and written to $this->where (\WPDataAccess\List_Table\WPDA_List_Table::construct_where_clause()).

No return value. Result is directly written to $this->items (base class member).

since 1.0.0

List of columns to make sortable

get_sortable_columns() : array
Inherited
since 1.0.0

Returns

array

get_where_clause()

get_where_clause() 
Inherited

I18n text displayed when no data found

no_items() 
Inherited
since 1.0.0

Prepares the list of items for displaying

prepare_items() 
Inherited

Overwrites WP_List_Table::prepare_items()

since 1.0.0

Print column headers

print_column_headers(boolean $with_id = true
Inherited

Overriding original method print_column_headers to support post instead of get. Changes are marked!

since 1.0.0
staticvar $cb_counter int

Parameters

$with_id

boolean

Whether to set the id attribute or not.

Process bulk actions

process_bulk_action() 
Inherited

Delete and bulk-delete actions use the primary key list as a reference. Before performing the actual delete statement(s) we'll check the provided column names against the data dictionary. This will protect us against SQL injection attacks.

For export actions table names will not be checked here. They are handed over WPDA_Export where the validity and access rights are checked anyway (to be safe).

All actions can be processed only with a valid wpnonce value.

To perform actions the user must have the appropriate rights.

since 1.0.0

Number of records in database table

record_count() : null | string
Inherited

Returns the number of records in the database table. Where clause must be prepared in advance and written to $this->where (\WPDataAccess\List_Table\WPDA_List_Table::construct_where_clause())

since 1.0.0

Returns

nullstringNumber of rows in the current table

Enable or disable bulk actions

set_bulk_actions_enabled(boolean $bulk_actions_enabled) 
Inherited
since 1.0.0

Parameters

$bulk_actions_enabled

boolean

TRUE = allowed, FALSE = not allowed.

Enable or disable bulk export options

set_bulk_export_enabled(boolean $bulk_export_enabled) 
Inherited
since 1.0.0

Parameters

$bulk_export_enabled

boolean

TRUE = allowed, FALSE = not allowed.

Set columns to be queries

set_columns_queried(mixed $columns_queried) 
Inherited

Set columns to be queried and shown in the list table. By default all columns in the table will be displayed.

since 1.0.0

Parameters

$columns_queried

mixed

Column list.

Show or hide search box

set_search_box_enabled(boolean $search_box_enabled) 
Inherited
since 1.0.0

Parameters

$search_box_enabled

boolean

TRUE = show search box, FALSE = do not show search bow.

Set page subtitle

set_subtitle(string $subtitle) 
Inherited
since 1.0.0

Parameters

$subtitle

string

Page subtitle.

Set page title

set_title(string $title) 
Inherited
since 1.0.0

Parameters

$title

string

Page title.

Show list table page

show() 
Inherited

Inside the list table page, the list table is shown. The necessary functionality to show the list table specifically is found in method \WPDataAccess\List_Table\WPDA_List_Table::display().

since 1.0.0
see \WPDataAccess\List_Table\WPDA_List_Table::display()

Add button to page header

add_header_button(string $add_param = ''
Inherited

By default "add new" and "import" buttons are added (depending on the settings). Overwrite this method to add your own buttons.

since 1.0.1

Parameters

$add_param

string

Parameter to be added to form action.

Add parent arguments as hidden items

add_parent_args() 
Inherited

Use this method to build parent child relationships.

add_parent_args_as_string(array $item) : string
Inherited

Overwrite this function if you want to use the list table as a child list table related to some parent form. You can add parent arguments to calls to make sure you get back to the right parent.

since 1.5.0

Parameters

$item

array

Column info.

Returns

stringString contains parent arguments.

Bind javascript code to action buttons

bind_action_buttons() 
Inherited
since 1.6.2

Override this method to add actions to first column of row

column_default_add_action(array $item, string $column_name, array $actions) 
Inherited

Parameters

$item

array

Item information.

$column_name

string

Column name.

$actions

array

Array of actions to be added to row.

Performs lookup query

column_lookup(string $target_column_name, string $target_table_name, string $source_column_name, mixed $value, string $data_type, string $and, string $target_schema_name) : mixed
Inherited

Parameters

$target_column_name

string

Lookup key column

$target_table_name

string

Lookup tabel name

$source_column_name

string

Source column name

$value

mixed

Lookup key value

$data_type

string

Lookup key data type

$and

string

Extension of where clause

$target_schema_name

string

Database schema name

Returns

mixedLookup value

Build where clause

construct_where_clause() 
Inherited

Arguments might come from the URL so we need to check for SQL injection and use prepare. The resulting where clause is written directly to member $this->where.

since 1.0.0

Generates the table navigation

display_tablenav(string $which) : void
Inherited

Generates the table navigation above or bellow the table and removes the _wp_http_referrer and _wpnonce because it generates a error about URL too large.

since 1.0.0

Parameters

$which

string

CSS Class name.

Generate hidden fields for keys

get_key_input_fields(array $item) : string
Inherited

Parameters

$item

array

Column info.

Returns

stringString containg key items and values.

Get search value (entered by the user or taken from cookie).

get_search_value() : string
Inherited
since 1.5.0

Returns

string

Overwrite method to prevent double row actions

handle_row_actions(object $item, string $column_name, string $primary) : string
Inherited

Parameters

$item

object

$column_name

string

$primary

string

Returns

string

Display the pagination

pagination(string $which) 
Inherited

Overriding original method pagination to support post instead of get. Changes are marked!

since 1.0.0

Parameters

$which

string

CSS Class name.

Render column content

render_column_content(string $column_content, string $column_name) : string
Inherited

Strip content if too long and replace & character.

Parameters

$column_content

string

Unprepared column content

$column_name

string

Database column name

Returns

stringRendered column content

 Properties

 

Indicates that this is a list table for a child

$is_child : boolean

Default

true

Parent and stand-alone list tables do not have this property.

 

Allow deletes?

$allow_delete : string

Default

null
 

Allow inserts?

$allow_insert : string

Default

null
 

Allow updates?

$allow_update : string

Default

null
 

Enable bulk actions?

$bulk_actions_enabled : boolean

Default

\WPDataAccess\List_Table\WPDA_List_Table::DEFAULT_BULK_ACTIONS_ENABLED
 

Enable exports?

$bulk_export_enabled : boolean

Default

\WPDataAccess\List_Table\WPDA_List_Table::DEFAULT_BULK_EXPORT_ENABLED
 

Child relationships (for actual parent)

$child : array

Default

 

Child tab clicked (used for parent child relationships only)

$child_tab : null

Default

''
 

Column headers (labels)

$column_headers : array

Default

 

Column options for the given table

$column_options_listtable : array | null

Default

 

Store columns in array with column name as index for fast access

$columns_indexed : array

Default

array()
 

Columns in query

$columns_queried : array

Default

 

Page number

$current_page : integer

Default

1
 

Name of the column containing action links

$first_display_column : string

Default

''

Default is the first column displayed

 

Show help icon if hrlp url is available

$help_url : null | string

Default

null
 

Hides tablenav

$hide_navigation : boolean

Default

false
 

Number of rows displayed in list box

$items_per_page : integer

Default

 

Table row number within the current response

$list_number : integer

Default

0
Static
 

Possible values: edit and view

$mode : string

Default

 

Menu slug of the current page

$page : string

Default

 

Page number text item

$page_number_item : null

Default

''
 

Page number item name (default 'page_number')

$page_number_item_name : string

Default

'page_number'

The name can be changed for pages on multiple levels. This is needed to get back to the right page in parent-child page.

   

Parent key values

$parent : array

Default

 

Database schema name

$schema_name : string

Default

''
 

Add search box?

$search_box_enabled : boolean

Default

\WPDataAccess\List_Table\WPDA_List_Table::DEFAULT_SEARCH_BOX_ENABLED
 

Name of search item (WP default 's')

$search_item_name : string

Default

SELF::SEARCH_ITEM_NAME_DEFAULT
 

Search string (entered by user or taken from cookie)

$search_value : null | string

Default

null
 

Previous search string

$search_value_old : null | string

Default

null
 

Options set name

$setname : string

Default

'default'
 

$show_page_title

$show_page_title 

Default

true
   

Page subtitle

$subtitle : string

Default

''
 

Database table name

$table_name : string

Default

''
 

Page title

$title : string

Default

 

Where clause

$where : string

Default

''
 

Flexible usage of IN and NOT IN :-o

$where_in : string

Default

'in'
 

Reference to dictionary object

$wpda_data_dictionary : \WPDataAccess\Data_Dictionary\WPDA_Dictionary_Exist

Default

 

Reference to import object

$wpda_import : \WPDataAccess\Utilities\WPDA_Import

Default

null
 

Reference to column list

$wpda_list_columns : \WPDataAccess\Data_Dictionary\WPDA_List_Columns

Default

 

Table settings

$wpda_table_settings : null | object

Default

null

 Constants

 

Default value bulk actions enabled

DEFAULT_BULK_ACTIONS_ENABLED = true 
 

Default value bulk export enabled

DEFAULT_BULK_EXPORT_ENABLED = true 
 

Default value bulk search enabled

DEFAULT_SEARCH_BOX_ENABLED = true 
 

Base table for list of all tables

LIST_BASE_TABLE = 'information_schema.tables' 
 

Make the default accessible to other classes

SEARCH_ITEM_NAME_DEFAULT = 'wpda_s'