fix(README): Link syntax

Since wordpress also doesn't allow brackets in attribute values, first
replace `((` and `))` by `[` and `]` before expanding the shortcodes.

Expands the README to full documentation, and renames internal functions
to make more sense.

Resolves #10.

Co-authored-by: Glen Whitney <glen@studioinfinity.org>
Reviewed-on: #11

README.md

@@ -24,8 +24,7 @@ Download a release from https://code.studioinfinity.org/glen/tablepress-pods/rel
 
 ##### Usage
 
-This extension operates by adding additional parameters to the [table id=NN /] shortcode. For a list of the provided parameters and their meanings, see the source file tablepress-pods.php. For it 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.
+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:
 
@@ -42,6 +41,44 @@ will produce a two-column table that lists the number and title of each "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:

tablepress-pods.php

@@ -3,7 +3,7 @@
 Plugin Name: TablePress Extension: Pods tables
 Plugin URI: https://code.studioinfinity.org/glen/tablepress-pods
 Description: Custom Extension for TablePress to incorporate Pods information in tables
-Version: 0.3.0
+Version: 0.4.1
 Author: Glen Whitney
 Author URI: http://studioinfinity.org/
 */
@@ -44,6 +44,11 @@ Street, Fifth Floor, Boston, MA 02110-1301 , USA.
  *              designation, even though it contains magic tags; hence, the 
  *              magic tags will appear in the result.
  *
+ * Note that in the pod_name and pod_where parameters, `((` and `))` are
+ * replaced by `[` and `]` respectively and do_shortcode() is run on the
+ * result, to facilitate the use of shortcodes to specify the values of these
+ * parameters.
+ *
  * [table id=1 pod_name="mypod" pod_dump=true pod_where="t.myfield = 3" /]
  *
  * *Ignores* the contents of the table altogether, and replaces it with a
@@ -56,21 +61,21 @@ Street, Fifth Floor, Boston, MA 02110-1301 , USA.
  */
 
 add_filter( 'tablepress_shortcode_table_default_shortcode_atts',
-            'playground_add_shortcode_parameter_pods' );
-add_filter( 'tablepress_table_raw_render_data', 'playground_expand_pod', 10, 2 );
-add_filter( 'tablepress_admin_view_actions', 'playground_add_export_pod_action');
-add_filter( 'tablepress_load_file_full_path', 'playground_exportpods_path', 10, 3);
-add_filter( 'tablepress_view_data', 'playground_exportpods_data', 10, 2);
-add_action( 'admin_post_tablepress_exportpods', 'playground_handle_exportpods');
+            'tbp_pods_add_shortcode_parameter_pods' );
+add_filter( 'tablepress_table_raw_render_data', 'tbp_pods_expand_pod', 10, 2 );
+add_filter( 'tablepress_admin_view_actions', 'tbp_pods_add_export_pod_action');
+add_filter( 'tablepress_load_file_full_path', 'tbp_pods_exportpods_path', 10, 3);
+add_filter( 'tablepress_view_data', 'tbp_pods_exportpods_data', 10, 2);
+add_action( 'admin_post_tablepress_exportpods', 'tbp_pods_handle_exportpods');
 
-function playground_add_shortcode_parameter_pods( $default_atts ) {
+function tbp_pods_add_shortcode_parameter_pods( $default_atts ) {
     $default_atts['pod_name'] = '';
     $default_atts['pod_dump'] = '';
     $default_atts['pod_where'] = '';
     return $default_atts;
 }
 
-function playground_add_export_pod_action( $view_actions ) {
+function tbp_pods_add_export_pod_action( $view_actions ) {
     $view_actions['exportpods'] = array(
         'show_entry'       => true,
         'page_title'       => __( 'Export Pods Table', 'tablepress' ),
@@ -81,12 +86,12 @@ function playground_add_export_pod_action( $view_actions ) {
     return $view_actions;
 }
 
-function playground_exportpods_path( $fullpath, $filename, $directory ) {
+function tbp_pods_exportpods_path( $fullpath, $filename, $directory ) {
     if ($filename !== 'view-exportpods.php') return $fullpath;
     return plugin_dir_path( __FILE__ ) . $filename;
 }
 
-function playground_exportpods_data( $data, $act ) {
+function tbp_pods_exportpods_data( $data, $act ) {
     if ($act !== 'exportpods') return $data;
     // Load all table IDs without priming the post meta cache, as table options/visibility are not needed.
     $data['table_ids'] = TablePress::$model_table->load_all( false );
@@ -108,13 +113,20 @@ function playground_exportpods_data( $data, $act ) {
     return $data;
 }
 
-function playground_expand_pod( $table, $render_options) {
+function tbp_pods_maybe_shortcodes($value) {
+    $bracketed = str_replace(array('((', '))'), array('[', ']'), $value);
+    return do_shortcode($bracketed);
+}
+
+function tbp_pods_expand_pod( $table, $render_options) {
     if (empty($render_options['pod_name'])) return $table;
+    $final_pod_name = tbp_pods_maybe_shortcodes($render_options['pod_name']);
     $pod_params = array('limit'=>-1);
     if (!empty($render_options['pod_where'])) {
-        $pod_params['where'] = $render_options['pod_where'];
+        $pod_params['where'] =
+            tbp_pods_maybe_shortcodes($render_options['pod_where']);
     }
-	$pod = pods($render_options['pod_name'], $pod_params);
+    $pod = pods($final_pod_name, $pod_params);
     $ndata = array();
     $rvis = array();
     $cvis = array();
@@ -188,7 +200,7 @@ function playground_expand_pod( $table, $render_options) {
 	return $table;
 }
 
-function playground_handle_exportpods () {
+function tbp_pods_handle_exportpods () {
 		TablePress::check_nonce( 'exportpods' );
 
 		if ( ! current_user_can( 'tablepress_export_tables' ) ) {
@@ -211,7 +223,7 @@ function playground_handle_exportpods () {
 		    $r_opts['pod_dump'] = true;
 		}
 		$filter = function( $data, $tab, $fmt, $delim ) use ($r_opts) {
-		    $newtab = playground_expand_pod($tab, $r_opts);
+		    $newtab = tbp_pods_expand_pod($tab, $r_opts);
 		    $exporter = TablePress::load_class( 'TablePress_Export', 'class-export.php', 'classes' );
 		    return $exporter->export_table( $newtab, $fmt, $delim );
 		};