Posts Table Pro – Documentation

Everything you need to know about creating the perfect posts table. It supports posts, custom posts, products and more.

Posts Table Pro provides an easy way to list all of your website content in a searchable and sortable data table. Under the hood it uses the jQuery DataTables plugin to provide the searching and sorting features, as well as pagination and responsive layouts for smaller screens.

Installation

Once you have purchased Posts Table Pro you should receive a confirmation email (in addition to your PayPal receipt) which contains your license key and a download link to the plugin. If you don’t receive this email, please get in touch with us.

Once you have downloaded the plugin, go to your WordPress admin, then go to Plugins -> Add New -> Upload Plugin. Click Choose File and select the posts-table-pro.zip file you just downloaded. Once uploaded, click Activate.

Entering your license key

Once activated, go to Settings -> Posts Table Pro and enter your license key. This should be contained in the email confirmation that was sent to you after purchase. Click Save Changes to validate and store your license key. If you get an error saving your license key, please try a second time. If the error persists, please view our troubleshooting page.

Updating the plugin

Updates are handled from the WordPress admin, in the same way as other plugins hosted in the wordpress.org repository. When an update is available, you will see a notice in the Plugins menu in the usual way. Click the update link under the plugin to update to the latest version.


Usage

To use Posts Table Pro, simply add the shortcode [posts_table] to any page, post, widget or other editable area in the WordPress admin. The default configuration will display your site’s posts, but you can of course customise the table in many different ways using the shortcode options listed below.

Examples

Basic usage displaying blog posts:
[posts_table columns="title,content,date,author,tags"]

Displaying pages:
[posts_table columns="title,content" post_type="page"]

Displaying a custom post type:
[posts_table columns="title,content" post_type="product"]

Displaying custom fields:
[posts_table columns="id,title,cf:document_status" post_type="document"]

Displaying taxonomies:
[posts_table columns="title,content,tax:film_category,tax:film_genre" post_type="film"]

Displaying the post excerpt:
[posts_table columns="title,excerpt,author,tags,date"]

Selecting posts in categories “design” or “web”:
[posts_table category="design,web"]

Selecting posts (from custom post type) which have the custom taxonomy term “comedy”:
[posts_table post_type="film" term="film_genre:comedy"]

Selecting posts with a custom field called “show_form” with a value of “yes”:
[posts_table cf="show_form:yes"]

Displaying WooCommerce products, including tags, categories and price (please note that we also have a dedicated WooCommerce plugin which you may wish to use instead of Posts Table Pro – WooCommerce Product Table):
[posts_table columns="title,tax:product_tag,tax:product_cat,cf:_price" post_type="product"]

Displaying featured images (with custom image size):
[posts_table columns="image,title,content" image_size="100x50"]

Choosing custom column headings:
[posts_table post_type=property columns="title:Name,date:Added On,tax:listing_cat:Property Type,cf:property_val:Price (£)"]


Archive Pages

While Posts Table Pro is primarily designed to be used on standard WordPress pages, it can also be used on post category/archive pages by overwriting the archive template in your theme. Archive pages are categories, tags, author and date archives.

You can download an example ‘archive.php’ template from this link. This will display a posts table for all ‘archive’ pages in your theme. It’s important to note that this is just an example, and you will need to modify this to work with your theme (for example, changing the surrounding HTML based on the other theme templates).

You should also be aware of the order of precedence with theme templates. For example, if your theme contains both a category.php file and an archive.php file, the category.php one will take precedence, so you will either need to remove the category file or add the posts table code to that file as well.

You may want to modify the shortcode in the template to suit your requirements – for example, to select which columns are displayed. See the rest of this documentation for details.

Automatically displaying a posts table on your archive pages isn’t straightforward and if you’re not comfortable with these instructions then we recommend that you ask your web developer to do it, or request a quote from our customisations service.

Translating the plugin into other languages

At the present time there are translations provided for: German, French, Spanish, Italian, Dutch, Norwegian and Polish. We plan to add more languages in future, but in the meantime you may wish to translate the plugin yourself. There is a .pot file provided in the plugin’s /languages folder which you can use to translate into your chosen language. Once you have created the relevant .po and .mo file for your language, upload them to this location:

<your site>/wp-content/languages/plugins/

The file name for the .mo and .po files should be the text domain followed by the relevant locale. So for example, if we were translating into Croatian, the local is ‘hr_HR’. The text domain for the plugin is posts-table-pro, so the file name would be: posts-table-pro-hr_HR.mo and posts-table-pro-hr_HR.po

Next, you will need to add a .json file to your site which provides the translations for the jQuery datatables library that WooCommerce Product Table relies on. You can see an example datatables translation file here:

https://datatables.net/plug-ins/i18n/Italian

In this example we’re translation to Italian. So create a file called “Italian.json” and copy the translations (in the format contained in the above link) into the file. Upload it to your server somewhere – it could go in your theme folder or, preferably, the /wp-content/languages/plugins/ folder.

Finally, you need to add some code to your theme’s functions.php file to add the json file to the plugin. Please see the posts_table_supported_languages filter below for an example.


Shortcode Options

There are a number of options available with the Posts Table shortcode:

columns

The columns to display in the table. This is the main option in the shortcode and determines which data is displayed.

You can choose from: id, title, content, excerptimage, date, author, categories, tags, status, or any custom field or taxonomy column (see below). You can choose as many columns as you want and in any order. You must separate each column with a comma. It doesn’t matter if there are spaces before or after the comma.

Here’s an example displaying the title, date, post author and excerpt for blog posts:
[posts_table columns="title,date,author,excerpt"]

The id column will display the post ID, which is a unique number used internally by WordPress for each post.
The title column is the main post title.

The content column will show the post content but will be truncated to 15 words. You can modify this length by setting the content_length option.

The excerpt column will show the post excerpt. It will be truncated to 55 words (the WordPress default) but themes and plugins sometimes override this value. To have precise control over the length, you can set the excerpt_length option.

The image column will display the featured image (i.e. the post thumbnail) for the post or page (see image_size option to set a custom size).

The date column will display the date that the post was published. The author column displays the post author’s display name.

The categories and tags columns apply to blog posts only (i.e. post_type="post") and will display the categories or tags for each post (comma-separated if there is more than one).

The status column will show the status of the post (e.g. draft, pending, publish, etc).

Displaying custom fields

Custom fields are a good way to include other types of content in the table. You can use them to store links, buttons, icons, shortcodes from other plugins, etc. You should add the full HTML code or shortcode to the custom field so that the product table can display it correctly. If you’re using shortcodes, you will need to set shortcodes to true.

You can add custom fields to your table using the format cf:<field name>. If you are using Advanced Custom Fields, the field name can be found under the “Field Name” column in the Custom Fields menu.

Here’s an example adding two custom fields – my_field1 and my_field2:
[posts_table columns="title,content,cf:my_field1,cf:my_field2"]

Displaying custom taxonomies

For taxonomies (other than post categories and tags), use the format tax:<taxonomy slug>. So, for example, to display for a custom taxonomy with the slug document_type, you would use:
[posts_table columns="title,content,tax:document_type"].

You can find the taxonomy slug by going to the WordPress admin and finding the main page which lists those taxonomies. For example, WooCommerce product categories are edited under the Products -> Categories menu. On that page, the URL at the top of the screen shows “…edit-tags.php?taxonomy=product_cat….”. The ‘product_cat’ bit after the equals is the taxonomy slug you need to use.

Choosing your own column headings

You can set custom column headings by adding a : (colon) after the column name. You can do this for as many columns as you like. If you don’t set a custom heading, the default one will be used. For example, the default heading for the post title is “Title”, but if you wanted the heading “My Heading” instead, you would use:

[posts_table columns="title:My Heading,date,author,content"]

Here’s a more complex example where we’re displaying a custom post type “property”, and we want to set the title column heading to “Property Description”, the date column to “Added On”, a custom taxonomy to “Type” and a custom field to “Sale Price (£)”:

[posts_table post_type=property columns="title:Property Description, date:Added On, tax:listing_cat:Type, cf:valuation:Sale Price (£)"]

Note in the above example, the taxonomy and custom field columns now have two colons – one to define the taxonomy (or custom field) name, and the other to set the column heading. This is perfectly fine as long as you adhere to the correct syntax shown. For these column types, everything after the second colon will be used as the custom heading.

Removing the column heading

If you would like to remove the column heading completely use the keyword blank after the colon. For example: columns="title:blank,content,categories"

sort_by

The sort_by option sets which column should be used for sorting the table by when it is first displayed. Defaults to date which is the date the post or page was published.

You can sort by any column present in the table, or by any of the following keywords (whether or not they are included in your table):

  • id – sort by post ID
  • title – sort by post title
  • menu_order – sort by the ‘order’ option
  • date – sort by the date of the post/page (i.e the publish date)
  • name – sort by post ‘slug’
  • modified – sort by last modified date
  • author – sort by author name
  • comment_count – sort by number of comments
  • type – sort by post type
  • rand – random order

Sort using keyword:  [posts_table columns="title,content" post_type="page" sort_by="menu_order"] 
Sort using column in table:  [posts_table columns="image,title,content,author" sort_by="content"] 

sort_order

The direction to use for sorting by when the table is first displayed. Can be either asc for ascending order or desc for descending order. Defaults to desc for date-based sorting, and asc for everything else, but you can override using this option.

category

Controls which blog post categories are displayed in the table. This applies to blog posts only (i.e. where post_type is set to post). If you’re displaying pages or other custom post types, then this option has no effect and you need to use ‘term‘ instead.

You should specify the category slug or category ID – this can be found under the Posts -> Categories menu in the WordPress dashboard. You can also specify multiple categories to display – either separated by commas or by a plus sign (+). If you use commas it means “posts in this Category A or Category B”. If you use a plus, it means “posts in Category A and Category B”.

For example, to display posts which are in the “design” category or in the “print” category, use:
[posts_table category="design,print"]

To display posts which are in the “design” category and in the “print” category, use:
[posts_table category="design+print"]

tag

Applies to blog posts only and selects posts based on their post tags. Use the tag slug or tag ID – you can find this in WordPress under the Posts -> Tags menu.

As with categories, you can use one tag or several tags, and you can use commas or a plus sign to denote how tags should be checked. Using commas means “posts with this tag OR that tag”; using the plus sign (+) means “posts with this tag AND that tag”. You can’t mix and match commas and pluses – it’s one or the other.

Example 1: Display posts with tag “awesome”: [posts_table tag="awesome"]

Example 2: Display posts with tags “cool”, “awesome” or “good”: [posts_table tag="cool,awesome,good"]

Example 3: posts with tags “cool”, “awesome” and “good”: [posts_table tag="cool+awesome+good"]

post_type

This option determines which post type (or types) will be displayed in the table. The default is post which will display blog posts. For pages use post_type="page". For attachments you can use post_type="attachment".

For custom post types, you will need to find the ‘slug’ for that post type. The easiest way to do this is to find the post type in the WordPress admin. For example, WooCommerce has a ‘products’ post type. If you go to the ‘Products’ menu in the admin, you will notice in the URL in your browser that it looks something like: “../wp-admin/edit.php?post_type=product”. The “product” bit is the post type you need to use. If you’re using Easy Digital Downloads, use post_type="download".

You can also use a list of post types, separated by commas. For example post_type="page,post", will display all blog posts and pages.

post_status

Determines which posts are displayed based on their post status. The default status is publish. The other options are draft, pending, future, private or any. Pending posts are those pending a review. Future posts are those scheduled to be published at a future date. And private posts have their visibility set to Private which means they can only be viewed by the post author or other administrators.

You can also use a list of post statuses separated by commas, for example:
[posts_table columns="title,author,categories" post_status="publish,draft"]

term

This option allows you to display only those posts which have the specified term or terms. The taxonomy that you are selecting from doesn’t have to be a column in your table.

Enter this in the format: term="<taxonomy slug>:<term slug or ID>". You can enter one term or multiple terms and, as with categories and tags, you can separate terms using a comma (,) or a plus sign (+) to denote whether the posts have any of the terms specified or all of them.

You need to prefix this option with the slug of the taxonomy followed by a colon. For example, to display WooCommerce products that have the product category “coats”, we would use:
[posts_table columns="title,content" post_type="product" term="product_cat:coats"]

To display posts with multiple terms, separate terms by a plus sign (AND) or a comma (OR). If you are selecting from several custom taxonomies, you need to add the taxonomy slug before each term.

The following example will display posts with a document_type of policy or memo:
[posts_table columns="title,content" post_type="document" term="document_type:policy,memo"]

The following example will display posts with a document_type of memo and a document_status of approved:
[posts_table columns="title,content" term="document_type:policy+document_status:approved"]

cf

This option is used to select posts based on a custom field value. You should use the format cf="<field name>:<field value>" when using this option. As with the above options you can enter one custom field to check, or several, and can separate them using a comma or a plus sign (see categories or tags for more details).

For example, if you are displaying a “car” custom post type and wanted to display cars which are either blue OR are Audis, you would use:
[posts_table columns="title,content" post_type="car" cf="color:blue,make:audi"]

However if you wanted to select the blue Audis (i.e. have color = blue AND make = audi) you would use:
[posts_table columns="title,content" post_type="car" cf="color:blue+make:audi"]

year

The following three options control which posts are displayed based on the date they were published. The “year” option can be set to limit posts to a specific year. E.g. year="2016"

month

Selects posts from a specific month. You should use a number here between 1 and 12. You can combine this with the year or day options if you want more fine grained control, e.g. year="2015" month="11"

day

Selects posts from a specific day in the month. You should use a number between 1 and 31, and as above, you can combine this with the year or month options, e.g. month="4" day="25"

author

Select posts by post author. Use the author ID or a list of IDs.
[posts_table author="1,4"]

exclude

The exclude option can be used to exclude posts or pages from your results based on their post ID. You can enter one ID or a list or IDs. For example, if you were displaying a table of your pages, but wanted to exclude the current page (id=23) which the table is displayed on, you would use:

[posts_table columns="title,content" post_type="page" exclude="23"]

include

The include option can be used to show only specific posts or pages in your table. You can enter one post ID or a list or IDs separated by commas. Note that include and exclude are mutually exclusive – if you set one, the other will be ignored.

Example: you are displaying a table of posts only want to show four specific posts:
[posts_table include="23,45,67,90"]

exclude_category

The exclude_category option is used to exclude entire categories of posts from your table. You can use category IDs or slugs, and it can be one category or a comma-separated list.

Example: [posts_table exclude_category="3,6"]
Example: [posts_table exclude_category="design"]

post_limit

Controls the maximum number of posts displayed in your table. Defaults to 500 posts. Warning: setting too large a limit could have a performance impact on your server.
[posts_table post_limit="750"]

rows_per_page

How many rows to display on each page of results, e.g. rows_per_page="50". The default is 25 rows. Set this to rows_per_page="-1" to show all records in your table.

paging_type

Controls the style of pagination used for your posts table. Defaults to simple_numbers, which displays numbers for each page plus ‘Previous’ and ‘Next’ buttons. Choose from one of the following:

  • numbers – page numbers only
  • simple – ‘Previous’ and ‘Next’ only
  • simple_numbers – ‘Previous’ and ‘Next’ buttons, plus page numbers
  • full – ‘First’, ‘Previous’, ‘Next’ and ‘Last’ buttons
  • full_numbers – ‘First’, ‘Previous’, ‘Next’ and ‘Last’ buttons, plus page numbers

filters

The filters option allows you to display drop-down lists above your table which allow you to filter (i.e. search) the table by selecting an item from the drop-down list. For example, with the categories filter, selecting a category from the list will filter the table to show posts only from that category.

To show filters based on the contents of the table, add filters="true" to the shortcode. This will show all filterable columns as filters above your table. This example would show categories and tags as search filters:

[posts_table columns="title,categories,tags" filters="true"]

To specify which filters are shown (regardless of the columns displayed), you can list the filters to be included, e.g:

[posts_table columns="image,title,content" filters="categories,tax:my_taxonomy"]

You can enable filters for: categories, tags, author and any custom taxonomy. At the present time, you cannot enable filters for a custom field.

The filters are displayed above the table by default, but if you have positioned your search box below the table (see display_search_box), then the filters will also appear below the table.

display_page_length

Controls whether to display the “Show <x> entries” drop-down menu, and whether to display it above or below your table. Defaults to top. Choose from one of the following options:

  • top – show page length above the table (top-left)
  • bottom – show it below the table (bottom-left)
  • false – hide the page length drop-down

Controls whether to display the search box for filtering the table by keyword, and where it should appear. Defaults to top. Choose from one of the following options:

  • top – show search box above the table (top-right)
  • bottom – show below the table (bottom-right)
  • false – hide the search box

display_totals

Controls whether to display the product totals (e.g. “Showing 1 to 10 of 50 entries”), and where to display it. Defaults to bottom. Choose from one of the following:

  • top – show above the table (top-left)
  • bottom – show below the table (bottom-left)
  • false – hide the product totals

display_pagination

Controls whether to display the pagination buttons for scrolling between the results, and where to display them. Defaults to bottom. Choose from one of the following:

  • top – show above the table (top-right)
  • bottom – show below the table (bottom-right)
  • false – hide the pagination buttons.

display_reset_button

Controls whether to display the ‘Reset’ button above the table. Defaults to true. Set to false to hide the reset button.

lazy_load

By default, Posts Table Pro will load all of the data into the table when it is first displayed on screen. If you have more rows than can fit on a single page of results (e.g. you are showing 20 rows per page and you have 30 results) then it will create multiple pages with pagination links at the bottom of the table.

For large numbers of posts, this can cause a hit on performance as all matching posts need to be fetched from the database and then formatted by the plugin. This can result in slower page load times and for very large data sets it may even result in a server or database error when attempting to load the table. If this becomes an issue for you, or you’re worried about performance, we recommend enabling the “lazy load” option. This will load the posts one page at a time rather than all at once. As the user navigates between the pages of results, they will see a “Processing” message displayed (briefly) while the next posts are loaded from the database.

Please note: enabling this option means that all post fetching, searching, and sorting is handled by the server rather than in the browser. Due to limitations in WordPress, the search & filtering features become limited to the title and content columns only, and the ‘search_on_click’ feature is disabled. We hope to provide a fix for this in future.

[posts_table lazy_load="true"]

 widths

Posts Table Pro will automatically calculate column widths, but you can override this using the widths option. You need to enter a value for each column in your table – either a percentage, a pixel amount or the keyword “auto” to have the plugin calculate the width automatically.

So for example, if you have 3 columns in your table: title, content and date. And you want to set the width of the title column to 20%, the content column to 50% and the date column to 30%, you would use: [posts_table columns="title,content,date" widths="20,50,30"].

If you wanted to set the width of the first column to 50px, and the other two to be automatically sized you would use:
[posts_table columns="title,content,date" widths="50px,auto,auto"]

auto_width

By default, Posts Table Pro will automatically calculate column widths to best fit your content in the space available. Set this option to false to disable this feature.
[posts_table auto_width="false"]

content_length

This option sets length of content column, if used in your table. Enter the number of words, e.g. content_length="20". The default is 15 words. Set content_length="-1" to show the whole post/page content.

excerpt_length

This option sets length of excerpt column, if used in your table. Enter the number of words, e.g. excerpt_length="20". The WordPress default excerpt length is 55 words.

shortcodes

The shortcodes option allows your table to display content generated by any shortcodes used on your site. For example, WordPress provides several built-in shortcodes for displaying audio files, videos, media playlists and image galleries. Enabling this option allows these media files to be displayed in your table.

By default, shortcodes is set to false which will remove all shortcodes from your table. This is done for two reasons: processing shortcode content can take a significant amount of time – especially for large tables – so enabling them can have a performance impact on your site. Secondly, shortcodes often add HTML to the content which makes it difficult to limit content to a set number of words (see content_length and excerpt_length). For this reason, if you enable shortcodes, the full content is always displayed and the content_length option is ignored.

Example: [posts_table columns="image,title,content" shortcodes="true"]

image_size

Controls the size of the image column if you are using this in your table. Defaults to thumbnail. You can use any standard image size (thumbnail, medium, large or full), or one or two numbers to denote the exact width and height for the image.

For example, to use the medium image size:
[posts_table columns="image,title,content" image_size="medium"]

For a square image 50 by 50 pixels:
[posts_table columns="image,title,content" image_size="50"]

For an image 50 pixels wide by 40 pixels high:
[posts_table columns="image,title,content" image_size="50x40"]

date_format

The date format to use when displaying the date column in your table. If you don’t set this option, the default format in your WordPress settings will be used (see Date Format under the Settings -> General menu).

You can set the date format to any valid date/time format string. For example: F j, Y will format the dates in this format: “August 24, 2016”. See the WordPress Codex for more information.

date_columns

The date columns option is used to specify which columns in your table should be treated as dates. This is useful if you have custom fields or taxonomies which represent date values, and you want enable sorting for these columns or change the format. This option should contain one or more columns (as a comma-separated list) using the same syntax as the columns option. For example:

[posts_table columns="image,title,cf:my_date,tax:my_custom_tax" date_columns="cf:my_date,tax:my_custom_tax"]

You don’t need to include the date column here, as this is always treated as a date. This is just for additional date columns such as custom fields.

Setting this option will also allow you to set the date format for these columns using date_format option.

This controls which data in your table is formatted as hyperlinks or plain text. This applies to the following columns: id, title, categories, tags, author, image as well as any custom taxonomy. Use links="all" to have all applicable columns have links, links="none" for no links, or any combination of the following keywords: idtitle, authorcategories, tags, terms or image as a comma-separated list.

If enabled for the id, title or image column, it will link to the post or page in question. For the author column, it will link to their author archive page. For tags, categories and custom terms, it will link to the relevant tag/category/term.

As an example, to have the title and image columns contain links, but not for other columns you would use: [posts_table columns="image,title,categories,tags" links="image,title"]

no_posts_message

The message to display in the table if there are no posts found by your shortcode. Set this to any text, e.g. if you’re displaying products you could use: [posts_table no_posts_message="Sorry, no products found" post_type="product"]

no_posts_filtered_message

The message to display if there are no records found after the user has entered a search term. For example: [posts_table no_posts_message="Sorry, no products match this search" post_type="product"]

Whether to show the column headings at the bottom of the table as well as the top. The default option is false (i.e. hide the footer headings), but you can set this to true to show them.

search_on_click

Certain data in the table can be displayed as links. (See the links option for more information about which columns display links). For example, the post author column can show a link to the relevant author page, and the categories column can link to the category archive for each category in the table.

Posts Table Pro provides a ‘search on click’ feature which means that instead of directing the user to the relevant page (e.g. the author page), it searches the table for that data instead.

For example, clicking on the author link “Pete Smith” would have the result of filtering the results in the table to only those posts written by Pete Smith. This is a quick way of filtering the results in the table. Defaults to true. To disable, set this to false.

wrap

This option tells the table whether to wrap long content onto multiple lines, or to keep everything on a single line and hide the rest. The default is true which means longer content will “wrap” onto extra lines as needed. If you set this to false it will ensure that each row is exactly one line high:
[posts_table columns="title,author,categories" wrap="false"]

priorities

This option is only relevant when displaying the table on smaller screen sizes (mobiles, tablets, etc) or when you have a lot of columns in your table and the plugin can’t fit everything in. When the screen size gets too small, the plugin will collapse certain columns down so they are no longer visible, and a “+” icon will appear at the left-side of each row. Clicking this icon will expand the row to show its full contents.

So the priorities option is used to determine the order in which columns are “collapsed” on smaller screens. Some default priorities are used, but if you wish to override these you can use this option. The lower the number, the higher priority that column has. So a column with a priority of “1” would have the highest priority and be collapsed last. If you had a table with three columns – title, author, and categories, and you wanted to make title the most important, categories second most, and author least important you would use the following: [posts_table columns="title,author,categories" priorities="1,3,2"]

column_breakpoints

Use this option to have more fine-grained control over the breakpoints for each column when viewed at smaller screen sizes. By default Posts Table Pro will show or hide columns on smaller screens based on the priorities option (or the default priorities if none are set). If you wish to set more specific breakpoints, you can set one of the following options for each column: desktop, tablet, mobile, all, none or default. For example, setting a breakpoint of tablet for a column means it will display on tablet devices, but not on mobiles or desktop screens.

The all option means the column will always be visible, regardless of screen size. The none option means it will not be shown in the table, but the column will still show in the child row (or modal) when expanded. The default option will let the plugin decide when it is hidden (using the priorities option if set).

You should set one option for each column in the table, for example:
[posts_table columns="title,content,tags,date" column_breakpoints="default,desktop,mobile,all"]

responsive_control

When the plugin can’t fit all the data within the space available (for example, on mobile devices) a “plus” icon appears to the left of each row to allow the user to show or expand the full content. This option sets whether that “+” icon control is displayed inside the first column (responsive_control="inline") or within its own separate column (responsive_control="column"). Defaults to inline.

responsive_display

This option determines how the “child rows” are displayed when viewing the table on smaller screen sizes (or when there is too much data to fit in the table). By default, the extra columns are displayed inside a child row which can be shown by clicking the “+” icon at the start of each row. You can also choose from the following options:

  • child_row – the default option. Extra data will be displayed in a hidden child row.
  • child_row_visible – Extra data is displayed in a child row which is expanded automatically when the table is first viewed.
  • modal – Extra data is displayed in a modal window when the “+” icon is clicked.

scroll_offset

When paging between multiple pages of results in your table, Posts Table will automatically “jump” back to the top each time. This is particularly useful if you are displaying a large number of rows on each page. Posts Table attempts to scroll to the correct position on the page but sometimes it doesn’t quite calculate this correctly. This is because each website and WordPress theme is different and some can have features which interfere with the scroll position – e.g. sticky navigation menus.

The scroll_offset option lets you override the scroll amount or disable this behaviour altogether. The default scroll amount is 15. If you find that the top of your table is “chopped off” when moving between pages, try increasing this to a larger number (e.g. scroll_offset="50"). If you’d like to disable automatic scrolling, set this option to false.


Developer Documentation

There are a number of filters provided in Posts Table Pro which allow you to customise the behaviour of the plugin.

posts_table_supported_languages

Allows you to add additional languages into the plugin which are not currently supported. Note that you must use the correct locale for your language as the key in the $langs array. In this example we’re adding Croatian so the locale is ‘hr_HR’.

add_filter( 'posts_table_supported_languages', 'ptp_supported_languages' );
function ptp_supported_languages( $langs ) {
    $langs['hr_HR'] = 'http://example.com/wp-content/languages/plugins/Croatian.json';
    return $langs;
}

posts_table_custom_class

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

add_filter( 'posts_table_custom_class', 'ptp_add_custom_class', 10, 2 );
function ptp_add_custom_class( $class, $posts_table ) {
    return 'my-class';
}

posts_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( 'posts_table_inline_config', 'ptp_inline_table_config', 10, 2 );
function ptp_inline_table_config( $config, $posts_table ) {
    $config['ordering'] = false;
    return $config;
}

posts_table_process_shortcodes

By default, Posts Table Pro will strip shortcodes from the post content so any content that would appear inside these shortcodes will not appear in the table. You can enable shortcodes on a per-table basis using the shortcodes option, but if you want to enable them globally, return true from this filter as follows:

add_filter( 'posts_table_process_shortcodes', '__return_true' );

posts_table_data_<column>

There are numerous filters which allow you to modify the data added to the table. One is provided for each column in the table in the form posts_table_data_<column>. So to filter the image column you would add a filter called posts_table_data_image. To filter custom taxonomies use the filter posts_table_data_terms.

add_filter( 'posts_table_data_image', 'ptp_custom_data_image' );
function ptp_custom_data_image( $image ) {
    // do something with $image
    return $image;
}

posts_table_data_custom_field

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

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

posts_table_acf_value

Filters which allows you to override the custom field value returned from Advanced Custom Fields. It accepts 3 arguments – the custom field value, the ACF field object and the current post ID.

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

posts_table_custom_data_<column>

Filter which allows you to add custom data to the table, in addition to the standard columns provided by Posts Table Pro. It accepts two arguments: the custom data to return (defaults to an empty string) and the current post object.

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

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

add_filter( 'posts_table_custom_data_rating', 'ptp_add_custom_data_rating', 10, 2 );
function ptp_add_custom_data_rating( $value, $post ) {
    $value = 'xyz'; // set value as required
    return $value;
}

posts_table_cell_data_<column>

Filter which allows you to modify the HTML data for a cell before it is added to the table. The <column> in the filter should be replaced with the column you wish to filter. For example, the filter data in the title column:

 

add_filter( 'posts_table_cell_data_title', 'ptp_custom_title_html', 10, 2 );
function ptp_custom_title_html( $title, $post ) {
    return '<span class="xyz">' . $title . '</span>';
}

posts_table_column_heading_<column>

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

add_filter( 'posts_table_column_heading_title', 'ptp_custom_heading_title' );
function ptp_custom_heading_title( $heading ) {
    return 'My Title';
}

posts_table_column_priority_<column>

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

add_filter( 'posts_table_column_priority_date', 'ptp_custom_priority_date' );
function ptp_custom_priority_date( $priority ) {
    return 10;
}

posts_table_column_width_<column>

Filter which allows you to override a column width for all posts 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( 'posts_table_column_width_author', 'ptp_custom_width_author' );
function ptp_custom_width_author( $width ) {
    return '100px';
}

posts_table_max_posts_limit

Filter which allows you to override the maximum posts limit (500 posts) set in Posts Table Pro. Note that this option only applies when you are not using the lazy_load option.

add_filter( 'posts_table_max_posts_limit', 'ptp_set_posts_limit', 10, 2 );
function ptp_set_posts_limit( $limit, $posts_table ) {
    return 1000;
}

posts_table_query_args

Filter which allows you to override the query args passed to WP_Query prior to retrieving posts from the database. See WP_Query documentation for details.

add_filter( 'posts_table_query_args', 'ptp_custom_query_args', 10, 2 );
function ptp_custom_query_args( $args, $posts_table ) {
    // do something with $args
    return $args;
}

posts_table_filter_label

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

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

posts_table_reset_button

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

add_filter( 'posts_table_reset_label', 'ptp_custom_reset_button' );
function ptp_custom_reset_button( $label ) {
    return "Clear";
}

posts_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( 'posts_table_search_label', 'ptp_custom_search_label' );
function ptp_custom_search_label( $label ) {
    return "I'm Looking for:";
}

STUCK? If you’re having any problems with Posts Table Pro, check out the troubleshooting page.