1. Home
  2. Documentation
  3. WooCommerce Product Table
  4. Advanced Usage
  5. Developer documentation

Developer documentation

WooCommerce Product Table comes with a number of filters which allow you to customize the plugin’s behavior.

Please note that this code is aimed at developers and if you don’t know how to use it then you should ask your developer. If you don’t have one, we recommend posting a job on Codeable. We have partnered with them to provide plugin customizations for our customers.

WordPress plugin customizations service

Filters

wc_product_table_language_defaults

This filter allows you to override the default values for various items of text used within the plugin. You might use this if you want to change the text for a particular item (e.g. the search box label) which has been provided by the plugin in your chosen language.

This example changes the search label to ‘Filter’, and also the empty table and zero records strings. You would need to look at the code to find the full list of strings.

function wcpt_set_language_defaults( $defaults ) {
    $defaults['search'] = 'Filter';
    $defaults['emptyTable'] = 'Sorry, no products currently available.';
    $defaults['zeroRecords'] = 'No products matched your search.';
    return $defaults;
}
add_filter( 'wc_product_table_language_defaults', 'wcpt_set_language_defaults' );

The full list of language strings and their defaults are:

Option Default Description
$defaults['info'] Showing _START_ to _END_ of _TOTAL_ products The totals message below the table. _START_, _END_ and _TOTAL_ are placeholders for the product totals which appear in the message.
$defaults['infoEmpty'] Showing 0 products The totals message when there are no products.
$defaults['infoFiltered'] (_MAX_ products in total) The message after the totals when searching/filtering. _MAX_ is the placeholder for the maximum number of products.
$defaults['lengthMenu'] Show _MENU_ products The text for the ‘Show X products’ dropdown. _MENU_ is the placeholder for the actual length dropdown.
$defaults['emptyTable'] No matching products found. Message when no products are found when table is first loaded.
$defaults['zeroRecords'] No matching products found. Message when no products are found after searching/filtering.
$defaults['search'] Search: The label shown in front of the search box.
$defaults['searchPlaceholder'] The placeholder for the search box.
$defaults['paginate']['first'] First The first pagination button.
$defaults['paginate']['last'] Last The last pagination button.
$defaults['paginate']['next'] Next The next pagination button.
$defaults['paginate']['previous'] Previous The previous pagination button.
$defaults['filterBy'] Filter: The label for the search filters.
$defaults['thousands'] , The ‘thousands’ separator for numbers and prices (e.g. $1,000)
$defaults['decimal'] . The decimal point for numbers and prices (e.g. $2.99)
$defaults['resetButton'] Reset The reset button text.
$defaults['multiCartButton'] Add Selected To Cart The cart button text for the multi selection.
$defaults['multiCartNoSelection'] Please select one or more products. The message when no products are selected.

wc_product_table_custom_class

Use this to add a custom CSS class to every posts table. E.g.

add_filter( 'wc_product_table_custom_class', 'wcpt_add_custom_class', 10, 2 );
function wcpt_add_custom_class( $class, $product_table ) {
    return 'my-class';
}

wc_product_table_column_class_<column>

Filters the column class used for all product tables. Expects an array of classes to be returned.

add_filter( 'wc_product_table_column_class_price', 'wcpt_custom_column_class_price' );
function wcpt_custom_column_class_price( $class ) { 
    $class[] = 'super-discount';
    return $class;
}

wc_product_table_row_class

Filters the row class used for each row in the table. Expects an array of classes to be returned. Takes two parameters – the classes array and the $product object.

add_filter( 'wc_product_table_row_class', 'wcpt_custom_row_class', 10, 2 );
function wcpt_custom_row_class( $class, $product ) { 
    $class[] = 'trade';
     return $class;
}

wc_product_table_row_attributes

Filters the row attributes used for each product row in the table. Expects an array of attributes to be returned as key => value pairs. Takes two parameters – the classes array and the $product object.

add_filter( 'wc_product_table_row_attributes', 'wcpt_custom_row_attributes', 10, 2 );
function wcpt_custom_row_attributes( $atts, $product ) { 
    $atts['data-foo'] = 'bar';
    return $atts;
}

wc_product_table_inline_config

Filters which allows you to override the inline table configuration used when the DataTables script is initialised. You can use this filter, for example, to disable or enable certain table features. The following example disables the ordering/sorting feature in all product tables:

// Disable column sorting
add_filter( 'wc_product_table_inline_config', 'wcpt_inline_table_config', 10, 2 );
function wcpt_inline_table_config( $config, $product_table ) {
    $config['ordering'] = false;
    return $config;
}

wc_product_table_process_shortcodes

By default, WooCommerce Product Table will strip shortcodes from the main product description so any content that would appear inside these shortcodes will not appear in your table. If you wish to override this behavior globally (for all tables), return true from this filter. If you wish to enable it for just one table, use the shortcodes option.

add_filter( 'wc_product_table_process_shortcodes', '__return_true' );

wc_product_table_data_<column>

This filter is provided to allow you to modify the column data before it is added to the table. One filter is provided for each column in the table in the format: wc_product_table_data_<column>.

For example, to override the price column you would use the filter: wc_product_table_data_price.

Any hyphens in the column name are replaced with underscores, so for the add-to-cart column the filter is: wc_product_table_data_add_to_cart.

Each of these filters takes two parameters: the data to add to the table, and the $product object (which is an instance of WC_Product).

add_filter( 'wc_product_table_data_name', 'wcpt_custom_data_name', 10, 2 );
function wcpt_custom_data_name( $name, $product ) {
    return 'Item: ' . $name;
}

wc_product_table_data_custom_field

Filters which allows you to override the value of a custom field displayed in the table. It accepts 3 parameters – the custom field value, the custom field key and the current product object.

// Override the 'extra_notes' custom field
add_filter( 'wc_product_table_data_custom_field', 'wcpt_override_custom_field', 10, 3 );
function wcpt_override_custom_field( $value, $field, $product ) {
    if ( 'extra_notes' === $field ) {
       // do something with $value
    }
    return $value;
}

wc_product_table_acf_value

Filters which allows you to override the custom field value returned from Advanced Custom Fields. It accepts 3 parameters – the custom field value, the ACF field object and the current post (i.e. product) ID.

add_filter( 'wc_product_table_acf_value', 'wcpt_override_acf_value', 10, 3 );
function wcpt_override_acf_value( $value, $field_obj, $post_id ) {
    if ( 'file' === $field_obj['type'] ) {
       // do something with $value
    }
    return $value;
}

wc_product_table_custom_data_<column>

Filter which allows you to add custom data to the table, in addition to the standard columns provided by the plugin. It accepts three parameters: the custom data to return (defaults to an empty string), the current $post object, and the current $product.

For example, to add a custom column “minimum_quantity” to your table, first add the custom column to your shortcode:
[product_table columns="title,content,date,minimum_quantity"]

Then add a filter to your theme or plugin to return this data:

add_filter( 'wc_product_table_custom_data_minimum_quantity', 'wcpt_add_custom_data_min_quantity', 10, 3 );
function wcpt_add_custom_data_min_quantity( $value, $post, $product ) {
    $value = 3; // set value as required
    return $value;
}

wc_product_table_separator_<type>

Filter which allows you to change the separator used between categories, tags, terms, attributes and custom fields. For example, a product can have multiple categories, each separated by a comma. This filter allows you to change the comma for a different character, line breaks, or other custom HTML.

The filter must include the relevant type. Possible values for type are: categories, tags, terms, attributescustom_field, and custom_field_row.

For example, to change the separator between categories in the table, add this filter:

add_filter( 'wc_product_table_separator_categories', 'wpt_set_categories_separator' );
function wpt_set_categories_separator( $sep ) {
    return '<br/>';
}

wc_product_table_column_heading_<column>

Filters the column heading for the specified column for all product tables on your site. If a custom heading is specified within the shortcode itself (in the columns option), then it will take precedence over the value returned from this filter.

// Override the 'name' column heading
add_filter( 'wc_product_table_column_heading_name', 'wcpt_custom_heading_name' );
function wcpt_custom_heading_name( $heading ) {
    return 'Item Name';
}

wc_product_table_column_priority_<column>

Filters the column priority for all product tables. If a priority is specified within the shortcode itself (using the priorities option), then it will take precedence over the value returned from this filter.

add_filter( 'wc_product_table_column_priority_date', 'wcpt_custom_priority_date' );
function wcpt_custom_priority_date( $priority ) {
    return 10; // a high number means low priority
}

wc_product_table_column_width_<column>

Filter which allows you to override a column width for all product tables on your site. If a width is specified within the shortcode itself (using the widths option), then it will take priority over the value returned from this filter.

add_filter( 'wc_product_table_column_width_sku', 'wcpt_custom_width_sku' );
function wcpt_custom_width_sku( $width ) {
    return '100px';
}

wc_product_table_max_product_limit

Filter which allows you to override the default products limit (500 products) set by WooCommerce Product Table. This will override the option in the plugin settings page. Note that this option only applies when you are not using the lazy_load option.

add_filter( 'wc_product_table_max_product_limit', 'wcpt_set_product_limit', 10, 2 );
function wcpt_set_product_limit( $limit, $product_table ) {
    return 1000;
}

wc_product_table_query_args

Filters the query args passed to WP_Query prior to retrieving products from the database. See WP_Query documentation for details. Takes two parameters – the query args and the WC_Product_Table_Query instance.

add_filter( 'wc_product_table_query_args', 'wcpt_custom_query_args', 10, 2 );
function wcpt_custom_query_args( $args, $pt_query ) {
    // do something with $args
    return $args;
}

wc_product_table_meta_query

Filter the meta query used in building the product table. Takes two parameters – the meta_query array and the WC_Product_Table_Query instance.

wc_product_table_tax_query

Filter the tax query used in building the product table. Takes two parameters – the tax_query array and the WC_Product_Table_Query instance.

wc_product_table_optimize_table_query

Filter whether the product table query should be optimized. Defaults to true.

Optimization involves removing the content and excerpt columns from the wp_posts query to reduce the amount of data returned from the database. The optimization only occurs if the description or short-description columns are used.

add_filter( 'wc_product_table_optimize_table_query', '__return_false' );

wc_product_table_shortcode_output

Allows you to modify the HTML returned by the [wc_product_table] shortcode. Takes two parameters: the HTML and the WC_Product_Table instance.

add_filter( 'wc_product_table_shortcode_output', 'wcpt_shortcode_output', 10, 2 );
function wcpt_shortcode_output( $html, $table ) {
    // do something with HTML
    return $html;
}

wc_product_table_filter_label

Allows you to change the “Filter:” label shown next to the search filters (if enabled).

add_filter( 'wc_product_table_filter_label', 'wcpt_custom_filter_label' );
function wcpt_custom_filter_label( $label ) {
    return "Search by:";
}

wc_product_table_filter_heading_<filter>

Allows you to change the heading (i.e. the default option) for the drop-down search filters shown above the table. The default heading for each filter is the same as the column heading (e.g. “Categories”, “Tags”, etc), or the custom column heading if you’ve supplied one.

You will need to append the appropriate filter name when using this hook:

  • For the categories filter: wc_product_table_filter_heading_categories
  • For the tags filter: wc_product_table_filter_heading_tags
  • For an attribute filter, e.g. pa_color: wc_product_table_filter_heading_pa_color
  • For a custom taxonomy, e.g. shop_brand: wc_product_table_heading_shop_brand

This example will change the heading for the “Categories” filter to “Filter by category”:

add_filter( 'wc_product_table_filter_heading_categories', 'wcpt_custom_categories_filter_heading' );
function wcpt_custom_categories_filter_heading( $heading ) {
    return "Filter by category";
}

wc_product_table_reset_button

Allows you to change the text used for the Reset button link above the table.

add_filter( 'wc_product_table_reset_label', 'wcpt_custom_reset_button' );
function wcpt_custom_reset_button( $label ) {
    return "Clear";
}

wc_product_table_multi_cart_button

Allows you to change the text used for the multiple add to cart button button above the table. Default button text is “Add Selected To Cart”.

add_filter( 'wc_product_table_multi_cart_button', 'wcpt_custom_multi_cart_button' );
function wcpt_custom_multi_cart_button( $label ) {
    return "Add Selected Products";
}

wc_product_table_multi_cart_class

Allows you to change the button class used for the multi add to cart button. Defaults to ‘button’.

add_filter( 'wc_product_table_multi_cart_class', 'wcpt_multi_cart_button_class' );
function wcpt_multi_cart_button_class( $class ) {
    return "btn";
}

wc_product_table_multi_add_to_cart_data

Filters the data used for the ‘Add Selected to Cart’ form which adds multiple products to the cart based on the selected products. Expects an array of key => value pairs, where the key name is the name given to the hidden field input to be included in the cart data.

add_filter( 'wc_product_table_multi_add_to_cart_data', 'wcpt_multi_cart_form_extra_data' ); 
function wcpt_multi_cart_form_extra_data( $data ) { 
    $data['foo'] = 'bar';
    return $data; 
}

wc_product_table_search_label

Allows you to modify the search label shown next to the Search box above (or below) the table. Defaults to “Search:”.

add_filter( 'wc_product_table_search_label', 'wcpt_custom_search_label' );
function wcpt_custom_search_label( $label ) {
    return "I'm Looking for:";
}

wc_product_table_open_products_in_new_tab

Product tables contain various links to the product details page. For example, the name column will (by default) include a link to the product page.

These will open in the same tab or window by default. To open them in a new tab use the wc_product_table_open_products_in_new_tab filter. For example:

add_filter( 'wc_product_table_open_products_in_new_tab', '__return_true' );

wc_product_table_column_searchable_<column>

This filter allows you to set whether or not a column is “searchable” in the product table. If a column is searchable, it means that the column will be used when the user types something into the search box above the table.

By default, the plugin includes all columns for searching, except for the image column (unless you’re using the lazy load option, in which case only the title and content columns are searchable). To override this behavior when you’re not using lazy load, use this filter with the appropriate column name added to the filter.

E.g. to exclude the price column from the table search:

add_filter( 'wc_product_table_column_searchable_price', '__return_false' );

If you want to disable searching for custom fields, attributes or taxonomies, use the column name without the cf:, att: or tax: prefix:

add_filter( 'wc_product_table_column_searchable_my_custom_field', '__return_false' );

wc_product_table_column_sortable_<column>

This filter allows you to set whether or not a column is “sortable” in the product table. If a column is sortable, the table can be re-ordered by that column using the up/down arrows that appear in the column heading.

If you’re using lazy load, the sorting is restricted to certain columns only. If you’re not using lazy load, then sorting is enabled for all columns except image, add-to-cart and button.

E.g. to prevent the table being sorted by price:

add_filter( 'wc_product_table_column_sortable_price', '__return_false' );

See the note above about using this filter for custom field, attribute or taxonomy columns.

wc_product_table_use_fitvids

Whether to use the FitVids library to make videos in the table responsive. Defaults to true.

wc_product_table_data_cache_expiry

The length of time in seconds that the product table data will be cached. Defaults to 24 * HOUR_IN_SECONDS (1 day).

wc_product_table_use_data_cache

Filter whether to use data caching globally across all product tables. Should return true or false.

Actions

wc_product_table_parse_args

Fired when the product table arguments have been parsed and set. Takes one argument which is the WC_Product_Table_Args instance.

wc_product_table_before_get_table

Fired once before each table is created on the page. Takes one argument – the WC_Product_Table instance.

wc_product_table_get_table

Fired once after each table is created on the page. Takes one argument – the WC_Product_Table instance.

wc_product_table_before_get_data

Fired once before the data is fetched and added to the table. Takes one argument – the WC_Product_Table instance.

wc_product_table_get_data

Fired once after the data is added to the table. Takes one argument – the WC_Product_Table instance.

Template functions

wc_get_product_table

This function can be used in your theme or plugin to retrieve a product table, passing a list of arguments as an array.

Arguments

array $args – The list of arguments to create the product table. Argument names are the same as those used in the product table shortcode. List based arguments (such as the columns option) can be passed as a comma-separated string or an array.

Return

string – The complete HTML for the product table table.

Example
$args = array( 
  'columns' => 'name,price,add-to-cart',
  'filters' => true,
  'category' => 'featured'
);
$table = wc_get_product_table( $args );

wc_the_product_table

Similar to the above function, but will print (rather than return) the product table in the current location.

Example
wc_the_product_table( array( 'category' => 'featured' ) );
Arguments

array $args – The list of arguments to create the product table.

CSS selectors

​.wc-product-table
The main product <table> element
.wc-product-table th
The table headings
.wc-product-table thead tr
.wc-product-table tfoot tr
The table header and footer rows
​.wc-product-table tbody tr
The table content rows
​.wc-product-table tbody td
The table cells
​.wc-product-table tbody tr.child
The responsive child rows (shown when clicking the + icon)
​.wc-product-table tbody tr.child .dtr-details
The responsive child data (shown when clicking the + icon)
​.wc-product-table td​.col-name​
To target a particular column. The class name is always col- followed by the column name, e.g. col-name, col-price, col-add-to-cart, etc.
​.wc-product-table-controls .wc-product-table-select-filters
​.wc-product-table-controls .wc-product-table-select-filters label
​.wc-product-table-controls .wc-product-table-select-filters select
The filter dropdowns above the table
​.wc-product-table-controls .dataTables_length
​.wc-product-table-controls .dataTables_length select
The ‘Show … products’ dropdown above the table
.wc-product-table-controls .dataTables_filter
.wc-product-table-controls .dataTables_filter input[type="search"]
The search box shown above the table
​.wc-product-table-controls .dataTables_paginate
​.wc-product-table-controls .dataTables_paginate .paginate_button
The pagination buttons below the table
​.wc-product-table-controls .dataTables_info
The product totals message (e.g. Showing 1 of 5 products)
​.wc-product-table .wc-product-table-reset
​.wc-product-table .wc-product-table-reset a
The reset link above the table.
​.wc-product-table-controls .multi-cart-form
​.wc-product-table-controls .multi-cart-form input[type="submit"]
The ‘Add Selected To Cart’ button
​.wc-product-table .add-to-cart-wrapper
​.wc-product-table .add-to-cart-wrapper form.cart
The Add To Cart form for a product in the table

Javascript Events

There are various events triggered by the plugin, during the lifetime of each product table.

Most events are passed the ProductTable object, which you can use to read certain data from the table.

The ProductTable object

Each table is represented in Javascript by a ProductTable object. The main properties are:

  • id – The table ID assigned to the <table> element.
  • config – The configuration object used to initialise the table.
  • $table – A jQuery object representing the <table> element.
  • $tableWrapper – A jQuery object representing the wrapper <div> around the table.
  • $filters – A jQuery object of the search filters (if used). This set contains each of the <select> elements for the filters.
  • ajaxData – If using lazy load, this will contain the data returned from the server in JSON format.

Events

init.wcpt

This event is triggered once for each table, after it has been fully initialised and all data has been loaded and drawn in the table.

Parameters: table – The ProductTable instance.

draw.wcpt

This event is triggered once for each table ‘draw’. A draw is any event which changes the appearance of the table. There is one draw when the table is first loaded, and subsequent draws occur whenever the table is re-ordered, a new page of results is selected, when the filters are changed, when a search is carried out, etc.

Parameters: table – The ProductTable instance.

lazyload.wcpt

If using lazy load, this event is triggered each time the data in the table is updated. For example, when scrolling through each page of results, or re-ordering the table. This occurs before the draw.wcpt event.

Parameters: table – The ProductTable instance.

load.wcpt

This event is triggered once for each table, on the window.load event.

Parameters: table – The ProductTable instance.

responsive-display.wcpt

This event is triggered whenever the ‘responsive’ child row or modal window is opened for a row in the table. This happens when the user clicks the + icon at the start of the row. The event is only triggered when the child row is shown (not hidden).

Parameters:
table – The ProductTable instance.
childRow – A jQuery object representing the child row <tr> element.

lazyload.wcpt

If using lazy load, this event is triggered each time the data in the table is updated. For example, when scrolling through each page of results, or re-ordering the table. This occurs before the draw.wcpt event.

Parameters: table – The ProductTable instance.

adding_to_cart

This event is triggered when a product is about to be added to the cart, after the ‘Add to basket’ button has been clicked. This event is also triggered (once) when adding multiple products to the cart using checkboxes.

Parameters:
$button – A jQuery object of the add to cart button.
data – The cart data (product ID, quantity, etc).

added_to_cart

This event is triggered when a product has been added to the cart, after the ‘Add to basket’ button has been clicked. This event is also triggered (once) when adding multiple products to the cart using checkboxes.

Parameters:
fragments – The cart fragments returned from WooCommerce (see WooCommerce docs or code for more info).
cart_hash – The cart hash returned from WooCommerce.
$button – A jQuery object of the add to cart button.

Was this article helpful?

Related Articles