Clarify shortcode operation.

README.md

@@ -52,8 +52,8 @@ Features (in no particular order):
 8.  All data modifications are recorded, along with optional comments that users
     can provide when updating data.
 9.  The `[tabulate]` shortcode can be used to embed tables, lists, row-counts,
-    and data-entry forms into WordPress content. For more details, see the
-    [FAQ section](https://wordpress.org/plugins/tabulate/faq/).
+    and data-entry forms into WordPress content. For more details,
+    [read the documentation](http://tabulate.readthedocs.org/en/latest/shortcode.html).
 10. Tables with *point* columns can be exported to KML and OpenStreetMap XML.
     Also, data entry for these columns is done with a small slippy map, on which
     a marker can be placed.
@@ -66,23 +66,9 @@ See http://tabulate.readthedocs.org/en/latest/install.html
 
 ## Frequently Asked Questions
 
-### How does one use the shortcode?
+### Where is the documentation?
 
-A [Shortcode](http://codex.wordpress.org/Shortcode) is a WordPress method of
-embedding content into posts and pages. Tabulate provides one short code, `[tabulate]`,
-which can be used to add tables, lists, data-entry forms, and record-counts to
-your content. Its parameters (which can appear in any order) are as follows:
-
-1. `table` — The name of the table in question. Required. No default.
-2. `format` — One of `table`, `list`, `form`, `count`, or `record`. Optional. Defaults to `table`.
-
-Do note that if a table is not accessible to the browsing user then nothing will
-be displayed.
-
-When using the `record` format, the primary key of the record to display will be
-taken from the URL parameter that is the table's name
-(e.g. `[tabulate table=widgets format=record]` will look for `?widgets=45`
-and display the record with a primary key value of `45`).
+Tabulate documentation is hosted on *Read The Docs* at http://tabulate.readthedocs.org/
 
 ### Where should issues be reported?
 

docs/conf.py

@@ -12,7 +12,7 @@
 project = u'Tabulate for WordPress'
 copyright = u'2016, Sam Wilson'
 version = '2.5'
-release = '2.5.1'
+release = '2.5.5'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/index.rst

@@ -50,3 +50,4 @@ Contents
 
    intro
    install
+   shortcode

docs/shortcode.rst

@@ -0,0 +1,68 @@
+Using the shortcode
+===================
+
+A `Shortcode`_ is a WordPress method of adding dynamic content to posts and pages.
+Tabulate provides one short code, ``[tabulate]``,
+which can be used to add tables, lists, data-entry forms, and record-counts to your content.
+Its parameters (which can appear in any order) are as follows:
+
+  1. ``table`` — The name of the table in question. Required. No default.
+  2. ``format`` — One of ``table``, ``list``, ``form``, ``count``, or ``record``. Optional. Defaults to ``table``.
+  3. ``ident`` — Used for the Record format. Optional. No default.
+  4. ``search`` — Whether to display a search form for the Table format. Optional. Defaults to ``false``.
+
+Do note that if a table is not accessible to the browsing user then nothing will be displayed.
+Keep in mind that you can grant access to non-logged-in users to view tables if you wish
+(via the Grants page in the Admin Area).
+
+ .. _shortcode: http://codex.wordpress.org/Shortcode
+
+Table format
+------------
+
+Example: ``[tabulate table=widgets search=yes]``
+
+The table format displays an HTML-table displaying all records from the Tabulate-table specified.
+
+If the additional parameter ``search`` is provided (and given any value at all; ``yes`` is just a convention)
+then a record-filtering form will be displayed.
+
+List format
+------------
+
+Example: ``[tabulate format=list table=widgets]``
+
+The list format displays a comma-separated list of all of the titles of the records from the table specified.
+
+Form format
+------------
+
+Example: ``[tabulate format=form table=widgets]``
+
+The form format displays a data-entry form to users who have been granted access to create records in the specified table.
+
+The form operates exactly the same as the form in the Admin Area,
+except that after submission the user is sent back to a blank form in readiness for the next data-entry
+(rather than shown their saved data).
+A message such as "Record saved." is displayed after submission.
+
+Count format
+------------
+
+Example: ``There are [tabulate format=count table=widgets] Widgets in our catalogue.``
+
+The count format displays a simple integer count of the records in the given table.
+
+This usage of the shortcode can be used inline within a sentence.
+
+Record format
+-------------
+
+Example: ``[tabulate format=form table=widgets ident=45]``
+
+The record format displays a single record from a table.
+
+To specify which record to display, either provide the ``ident`` shortcode parameter,
+or set a URL parameter equal to the name of the table.
+For example, ``[tabulate table=widgets format=record]`` will look for ``?widgets=45``
+and display the record with a primary key value of ``45``.

src/Controllers/ShortcodeController.php

@@ -30,6 +30,7 @@ public function run( $atts ) {
 		$defaults = array(
 			'format' => 'table',
 			'table' => null,
+			'ident' => null,
 		);
 		$attrs = shortcode_atts( $defaults, $atts );
 		if ( ! isset( $attrs['table'] ) ) {
@@ -61,12 +62,22 @@ protected function error( $message = '' ) {
 	}
 
 	protected function record_format( Table $table, $attrs, $query = null ) {
-		if ( ! isset( $query[ $table->get_name() ] ) || ! is_scalar( $query[ $table->get_name() ] ) ) {
-			return '';
+		// Check for the ident shortcode parameter...
+		if ( isset( $attrs['ident'] ) ) {
+			$ident = $attrs['ident'];
 		}
-		$record = $table->get_record( $query[ $table->get_name() ] );
+		// ...or the tablename=ident URL parameter.
+		if ( isset( $query[ $table->get_name() ] ) && is_scalar( $query[ $table->get_name() ] ) ) {
+			$ident = $query[ $table->get_name() ];
+		}
+		if ( ! isset( $ident ) ) {
+			return $this->error( __( 'No record identifier could be determined.', 'tabulate' ) );
+		}
+
+		// Get the record.
+		$record = $table->get_record( $ident );
 		if ( $record === false ) {
-			return $this->error("No record found.");
+			return $this->error( __( 'No record found.', 'tabulate' ) );
 		}
 		$template = new Template( 'record/view.html' );
 		$template->table = $table;

tabulate.php

@@ -7,9 +7,9 @@
  * License: GPL-2.0+
  * Text Domain: tabulate
  * Domain Path: /languages
- * Version: 2.5.4
+ * Version: 2.5.5
  */
-define( 'TABULATE_VERSION', '2.5.4' );
+define( 'TABULATE_VERSION', '2.5.5' );
 define( 'TABULATE_SLUG', 'tabulate' );
 
 // Load textdomain.

templates/base.html

@@ -21,7 +21,6 @@ <h3 class="nav-tab-wrapper">
 		{% if current_user_is_admin %}
 		<a href="{{table.get_url('index', false, 'schema')}}" class="nav-tab {% if action=='structure' %}nav-tab-active{% endif %}">
 			{{__('Structure', 'tabulate')}}
-			Structure
 		</a>
 		{% endif %}
 	</h3>