tablepress-pods

Abstract

Create Tablepress tables which summarize and display information from Pods

Description

This project is an extension to the TablePress plug-in (see https://tablepress.org/) for WordPress (https://wordpress.org/). It is not useful without the TablePress plug-in. This project is not part of TablePress, but designed to work with it and extend its capabilities.

This project also assumes that you have installed the Pods plug-in (see https://pods.io/) in your WordPress installation. It is also not useful without the Pods plug-in.

The tablepress-pods extension allows you to extract and display in Tablepress tables information from the content in Pods custom post types and taxonomies. If you use Pods and would like to produce tables from the information you've stored in them, this extension is potentially very useful.

Installation/Upgrade

Download a release from https://code.studioinfinity.org/glen/tablepress-pods/releases (as a zip file) and install and activate in your WordPress site like any other extension in zip format. Namely, from your Dashboard, you can:

1. Select Plugins from the left-hand menu bar.
2. Click on "Add New" and then "Upload Plugin."
3. Browse to the downloaded zip file on your local disk, and click "Install Now."
4. If this is an upgrade, it will show you the currently installed version and the new version and ask you to confirm the replacement.

Usage

This extension operates by adding additional parameters to the [table id=NN /] shortcode. (See below for a list of the provided parameters and their meanings.) For this extension to be useful, you then need to go to the table definition (in the Tablepress tabs from the Dashboard) of the corresponding table and use Pods "magic tags" within that table.

Here's a brief example:

[table id=2 pod_name="problem" /]

together with a definition of table 2 in Tablepress that looks like

	A	B
1	Number	Title
2	{@number}	<a href="{@permalink}">{@title}</a>

will produce a two-column table that lists the number and title of each "problem" in the Pod, with the title being a link to the problem.

Note that the {}-expressions allowed in the entries of the table definition include arbitrary Pods "magic tags" syntax. So for example in my installation, which categorizes articles from a periodical, I have such expressions as {@issue.issue_number} and {@section.permalink}. You can also use the custom postprocessing argument, e.g. {@source, list_of_links_to_terms} (where "list_of_links_to_terms" is defined in the functions.php of my theme).

Note that the expansion can also be controlled by the following "pseudo-shortcodes" which must occur at the beginning of the first column of the row (you may want to dedicate a hidden column just for this purpose if you are making use of these).

• [once]: This row expands only into a single row (corresponding to the first record returned by the find() call), with magic tags expanded
• [literal]: Do not expand this row, except for removing the [literal] designation, even though it contains magic tags; hence, the magic tags will appear in the result.

[table] shortcode parameters supported

• pod_name=NAME

  The name of the pod from which records will be extracted.

• pod_where=SPECIFICATION

  The SPECIFICATION is passed as the "where" parameter of the pods() call that extracts the data, so that it can filter the data returned. For example, pod_where="t.id = 27" would return only the record with id 27, whereas if you have a custom field "account" and your POD uses meta-data storage, pod_where="account.meta_value = 'Sales'" would return all records where the "account" field has value "Sales".

An example that puts this all together:

[table id=2 pod_name="budget" pod_where="account.meta_value = 'Sales'"]

would present the TablePress table with id 2 but with any row in which magic tags appeared into a sequence of rows with those tags expanded, for each record returned by pods('budget', [ 'where' => "account.meta_value = 'Sales'" ])

See the [pods() documentation][https://docs.pods.io/code/pods/] for more on possible values for the where parameter.

• pod_dump=true

  If this attribute is specified, the shortcode will ignore the the contents of the Tablepress table altogether, and replace it with a simple dump of the ID, date, title, author, permalink, and all custom Pods fields for each record in the Pod specified by the pod_name attribute and filtered by the pod_where attribute. Note that the taxonomies, if any, of the post type will not be shown. Useful mainly for debugging and seeing what is present in your Pod; for any presentation tables you will most not want to specify the pod_dump attribute.

Further shortcodes in attribute values

It might happen that you would like either the Pod name or some portion of the filter specified by pod_where to be generated by another short code. However, it's not possible to specify brackets as part of the attribute value of a shortcode (due to the way Wordpress parses shortcodes). Thus, to assist with this, this extension will first replace (( with [ and )) with ] in the attribute values, and then run Wordpress do_shortcode() on the result. Therefore, you can write for example

[table id=2 pod_name="budget" pod_where="account.meta_value = '((current_account))'"]

to show the records from the "budget" Pod with "account" value equal to whatever the shortcode [current_account] expands to.

Troubleshooting

If you experience the symptom that the displayed table in your page won't update if you change the data in the Pod that it is reading from, unless you visit the table in Tablepress and re-save it, try adding cache_table_output=false to the shortcode that is displaying your table. (Thanks to ezolboo for this information.)

Building

To produce an installable zip file, assuming you have cloned this repository:

1. Make sure that you have committed your changes with an update to the Version parameter in tablepress-pods.php.
2. Make sure the current git head is on the commit you want to build.
3. From the top-level directory of the repository, execute bash mkplugin.sh.