
**********************************************************************
Documentation for WordPress plugin: SEO for wpDataTables Master-Detail
**********************************************************************

00. CONTENTS

00. Contents
01. Summary
02. Main features
03. Limitations
04. Prerequisites
05. Setup & Configuration
06. Basic configuration
07. Multimode
08. URL examples
09. Frequently asked questions
10. Download & Updates/upgrades
11. Changelog
12. Disclaimer
13. Support
14. Donations

01. SUMMARY

SEO for wpDataTables Master-Detail (seo-for-wdt-md) is a free third-party addon
for wpDataTables.

This plugin addresses several search engine optimization (SEO) considerations
of wpDataTables Master-Detail pages, while also providing them clean URLs.

Thank you for your interest in the plugin! If you decide to experiment with it,
please read through this documentation first.

02. MAIN FEATURES

NOTE: All features described below are specifically for the Master-Detail
pages, the plugin doesn't modify other WordPress or wpDataTables functionality.
The "Without the plugin" behavior described below is based on the latest
version of Master-Detail Tables (2.0.2 at the time of writing).

Sets the HTML title tags based on actual data. Title format is configurable.
(Without the plugin: All titles identical. Bad for SEO.)

Provides clean URLs, i.e. short URLs and optionally also friendly URLs. Slug
format is configurable. If friendly URLs are enabled, short URLs redirect to
them.
Please note that the actual lengths of URLs depend also on the length of your
domain.
(Without the plugin: URLs are long, complex and not informative for users or
search engines.)

Sets the HTML canonical tags to actual clean URLs.
(Without the plugin: All canonical tags point to the template page. Very bad
for SEO.)

Dynamically generates a sitemap (in plain text format) in order to have all the
Master-Detail pages, and therefore all the rows, indexed by search engines.
You can point to the generated sitemap in your robots.txt file, or submit it to
search engines manually via their webmaster tools or search console.
(Without the plugin: As for tables utilizing server-side processing, search
engines can only crawl the rows that are visible when that particular page
loads, e.g. not more than the first 10 rows.)

03. LIMITATIONS

If the plugin is enabled on multiple tables (see section on multimode below),
the tables need to have matching column names i.e. "origin headers" for any
columns specified in the plugin configuration. This is because the same
settings will be used for all tables.
Full individual sets of settings for different tables are currently not
possible nor planned, however in the future some single setting might be
considered to be made independently configurable for tables.

Slugs cannot be numerical only.

04. PREREQUISITES

A WordPress instance running the full version of wpDataTables and its addon
Master-Detail Tables (at least version 2.0).

NOTE: Due to the nature of this plugin, it is highly recommended to have a
testing environment (typically on a subdomain so no issues with licensing) and
not to install it on a live production site. The plugin affects WordPress URL
handling and this is not something one might want to experiment with on any
installation having actual traffic and visitors.

A wpDataTable (MySQL-based or Manual table) with Master-Detail functionality
enabled and properly configured:
Master-Detail template page (not post) set up and selected, the options "Send
details over" set to GET, "Show details in" set to Page, "Parent table column
Name" set to the row ID column ("wdt_ID" recommended).

"ID column for editing" (also for non-editable tables) set.

No other SEO plugin configured to affect the Master-Detail pages.

Basic understanding of editing a configuration file and gathering the use-case
specific information on your wpDataTables installation.

Pretty Permalinks enabled in WordPress (they are by default).

Allowed characters for wpDataTables row ID column names ("wdt_ID" by default)
in the SQL database are alphanumeric, dash, underscore. However, it is highly
recommended to use "wdt_ID" for every table the plugin is enabled on, because
of compatibility reasons. While other names can work in some configurations, it
is more likely they will cause problems.

05. SETUP & CONFIGURATION

*******************************************************************************
NOTE: If installing over previous version, please first make sure you have a
backup of your settings for the plugin, placed somewhere other than the plugin
folder, because that folder will be fully replaced! Also see section on updates
and upgrades below.
*******************************************************************************

To install, first download the plugin zip file (see the web address below) and
then install it following the typical WordPress plugin installation process.
Don't activate the plugin yet. (If you did, no problem, you just have to
re-activate it afterwards.)

The next step after installing is to configure the plugin, for the time being
this involves manually editing the configuration file in the plugin folder. As
you are a webmaster or advanced user, this hopefully is no problem for you.
There are several ways to proceed with this, but it is recommended to access
the file using a file explorer tool (e.g. cPanel File Manager) or an FTP
application.
You should navigate to your WordPress installation folder, and then within it,
to the actual plugin folder: "wp-content/plugins/seo-for-wdt-md".

First copy the file "settings_default.php" so that you have another file named
"settings.php" with the same content. This is for you to have a backup of the
original configuration in case you need to restore it during testing.
Open the "settings.php" text file and carefully make the needed changes to the
configuration values in the beginning of the file, there are comments further
down the file to inform and help you understand what every line is for.
Pay attention to only modifying the values on the right, keeping the value
names and the colon character (:) in the beginning of every line unchanged.

After you have configured the plugin according to your needs, save the file and
then you can proceed to activating the plugin and start testing the features.

In case of problems, first double check your configuration, maybe try changing
individual settings to default. If that does not help, you can restore all the
default settings (copy the "settings_default.php" file over the "settings.php")
and/or deactivate the plugin.

For some of the settings you need to re-activate (deactivate and then activate)
the plugin for the new setting to take effect. These are indicated in the
explanations section in the configuration file.

06. BASIC CONFIGURATION

So, which values in the configuration file you have to change, at minimum, in
order to go and test how the plugin works?

To answer in short: "Table numbers", "Page title format", and "Configured".
I explain this in detail below. And you already read the prerequisites, right?

The first value in the beginning that determines which of your wpDataTables the
plugin is enabled for: "Table numbers". These are the same IDs you can see when
using the "Browse Tables" view of wpDataTables. Please test with only one table
first.

Also if you don't actually have columns "make" and "model" (see the second
setting "Page title format") in your SQL database for the wpDataTable(s) you
want to enable the plugin on, you have to replace those with any other columns
you do have. The data from those columns will be used for generating the page
titles.

Lastly, you need to change the last setting ("Configured") to 1 to confirm you
have configured the plugin (you can still make more changes later).

The rest of the values are fine as they are, for testing purposes.
After saving the file (make sure the name is "settings.php"), you can proceed
to activating the plugin. If you already have activated though, now it's the
time to reactivate.

07. MULTIMODE

Multimode means enabling the plugin on multiple wpDataTables of your choosing
and introducing table IDs in the clean URLs. In most earlier versions of the
plugin it was only possible to enable it on one table at a time, hence only row
IDs were needed.

The same settings will be used for all tables however, therefore the tables
need to have a column structure similar enough and no deviations from the
settings are possible for individual tables. It's especially important that
certain column names in the SQL database match between the wpDataTables, these
being the column names that are actually used in the two settings of the plugin:
Page title format, Slug format (if enabled).

Unfortunately multimode will not work (and thus should not be enabled) on
tables having no matching column names to be used in the settings mentioned,
unless slugs are disabled and page title format is reduced into minimum using
only a common column such as row ID (usually "wdt_ID").

Most likely all this does somewhat affect the results you want to achieve, some
compromises might be needed to accommodate multiple tables and their desired
Master-Detail presentation, sometimes multimode is simply not suitable for the
scenario.

Considering the sitemap feature, the records from all tables will be included
in the same sitemap.

To ensure backward compatibility, any possible original table (used with an
earlier non-multimode capable version of the plugin) should be put first in the
Table numbers setting. The first table can be accessed without specifying any
table ID in the clean URL.

08. URL EXAMPLES

example.com/item/001-00123/
Page path set to "item/", table number and row number padding set to 3 and 5,
respectively. No slug. Multimode.

example.com/product/012345-brandx-3000-plus/
Page path set to "product/", row number padding set to 6. Slug generated from
brand and product name column data, conversion to lowercase.
Same URL also accessible via example.com/product/012345/ (will be redirected).

example.com/123/
Page path omitted, row number padding set to 0 (or 3). No slug.
NOTE: Omitting the page path is an experimental feature. It can cause
unintentionally catching of requests for possible other pages and posts
(matching the clean URL patterns used by the plugin), so use with caution.
If your site root only has pages such as "about" and "contact-us" etc, with no
posts or any other URLs starting with numbers, there should be no problem.

09. FREQUENTLY ASKED QUESTIONS

When testing the plugin after configuring, I get "This page could not be found"
(or similar) error, when trying to access any Master-Detail from my table?
-You should try reactivating the plugin for the settings to take effect.

Trying to access a proper clean URL just takes me to the front page of my site?
-There can be several reasons for this:
 Does the URL have invalid ID number(s) i.e. the data row in question actually
 does not exist?
 Is the template page not set for the table in the Master-Detail settings of
 wpDataTables?
 Do you have the row ID column name set to something else than "wdt_ID"?
 Is the setting "Page title format" or "Slug format" (if slugs are enabled)
 misconfigured or do those columns not contain any data in that row?

Will the plugin work with the theme I'm using?
-As the things this plugin does are very "low level" compared to themes, which
impact the appearance and design of the site, it is very unlikely for a theme
to conflict with this plugin or vice versa.

How do I shot web... err, I mean, how do I enable multimode?
-It is automatically enabled on plugin activation if there are multiple values
specified in the "Table numbers" setting. 

Do I need to create the page path folder in my file system?
-No, the page path is not an actual folder and it should not exist in the file
system. You just set the desired page path in the configuration, the plugin
then makes the URLs look like there is a folder with the same name.

I'm having problems with the plugin after changing my Master-Detail template
page to another page for one of my tables. What should I do?
-You should try reactivating the plugin to refresh the template configuration.

Master-Detail page does not show data for one of my tables even though I have
enabled the plugin for the table?
-Make sure you also have enabled Master-Detail functionality for the table in
wpDataTables settings and configured it properly (see section on prerequisites
above).

What if I wanted to access my detail pages also with URLs such as /car/1234/
and /bike/1234/ so that the page path varies according to table ID?
-At least for now this is not possible with the plugin, but this could be
achieved with htaccess redirects, by adding suitable rules before the ones
added by WordPress. Details on how to do this are however outside the scope of
this documentation, but lots of tutorials exist on the subject. If you feel you
need something like this applied, but can't find enough help online or are not
confident doing it by yourself, consulting a developer is advised.

Will making a typo in column data used for the slug make my friendly URL wrong
permanently?
-Accessing the Master-Detail pages is based on ID numbers, the slug only offers
additional information for users and search engines. After correcting the typo,
the search engines will eventually adapt and update their index to point to the
correct URL. On your site the change should reflect immediately after the typo
has been corrected, while the old wrong URL will also work, automatically
redirecting to the correct one.

Why no admin menu for configuring the settings?
-There are several reasons for the plugin not having an admin menu, at least
for now. I like to keep the plugin simple. I have prioritized my other projects
over delving into too deep with this side project. Also, I think this is not a
plugin you need to tinker with frequently, I believe it's usually more like
configuring and testing once when setting up a site, kind of set and forget.
After all, the main target group are advanced users who are comfortable with
editing configuration files once in a while, not everything is a click away :)

10. DOWNLOAD & UPDATES/UPGRADES

At least for now, there are no automatic updates or update notices for the
plugin, so it's more or less a manual process. On the other hand, it is highly
unlikely that the plugin will actually need updating very often.
The current and any future versions of the plugin will be available at:
https://antero.eu/seo-for-wdt-md/

*******************************************************************************
NOTE: Always make a backup of the plugin settings (the "settings.php" file in
plugin version 2.0.0 and higher) before updating/upgrading or reinstalling!
When using the "Add New Plugin" button in WordPress, the old contents of the
plugin folder will be fully erased. You have more control on what will happen
when uploading the files using an FTP application or a file explorer tool.
*******************************************************************************

It is recommended to test the update/upgrade workflow on a staging site first,
before taking such action on actual live site. You need to manually inspect and
make sure the settings are the way you want afterwards.
If there are no new settings to configure in the new version, the process is
quite straightforward however, installing over an old version and then manually
restoring the settings from a backup.

11. CHANGELOG

1.2.6   07/2024   First seo-for-wdt-md version released to public.
1.2.7   08/2024   Feature: Preserve case of slug text.
1.5.2   09/2024   Bug fix: Null values in table data caused unwanted behaviour
                           upon constructing page title, thus preventing such
                           Master-Detail pages from showing any data.
                  Feature: Dynamic sitemap.
                  Change: Meta description optional, with revised format.
                  Lots of code restructuring.
1.5.4   10/2024   Feature: Sitemap name configurable.
                  Feature: Slug format configurable.
2.0.0   01/2025   Feature: Zero padding for ID numbers in URLs.
                  Support: MySQL-based tables (previously Manual tables only).
                  Support: Several tables with one configuration.
                  Support: Custom table name in database.
                  Change: Page path can be omitted to achieve the cleanest URLs
                          (experimental feature).
                  Change: Check for required Master-Detail version upon
                          activation.
                  Change: Check for completed configuration upon activation.
                  Lots of code restructuring and several small improvements.
                  Many additions to the documentation, including new sections.
2.1.0   01/2025   Bug fix: Fetching row ID column failed on table IDs other
                           than 1 and always defaulted to "wdt_ID". Apart from
                           unnecessary admin notices, this did not actually
                           matter if "wdt_ID" is what you are using in your
                           tables anyway.
                  Bug fix: Excessive leading zeros in ID numbers were not
                           removed from requested URLs.
                  Change:  Added validation for configuration values that will
                           cause unexpected behaviour improperly configured,
                           these now trigger admin notices to help troubleshoot
                           your configuration.
                  New setting: "Validate settings".
                  A few small improvements.

12. DISCLAIMER

The plugin was created for a specific project I'm actively working on and even
if it doesn't necessarily follow all the coding guidelines, it does the things
it was written for and should be safe to use. Security is never something to
compromise on.

I shall not be liable for any possible loss or damages arising from the use of
the plugin, also I strongly recommended not to use the plugin in any critical
production environments. If you're fine with this, good, feel free to use it :)

Like most of the plugins, if not all, also this one can stop working correctly
after an upgrade to something it depends on (php, WordPress or wpDataTables).
Fortunately it's not very likely, but if it happens some day and even prevents
your pages from showing, you should deactivate this plugin and wait until an
update is released. For a business-critical site, you might want to hire a
developer in such a situation.
If you feel you need a quick temporary workaround, so that your Master-Detail
pages can still be reached using the clean URLs, you might want to consult a
developer or learn online about htaccess rules.

Even though I really like wpDataTables, at the time of writing I have no
affiliation with TMS, or any of their products.

13. SUPPORT

Feel free to follow the official Facebook page of the plugin, for info on
updates etc... support questions are welcome there too, but please first make
sure you have the latest version of the plugin.
You can find the page at: https://www.facebook.com/seo.for.wdt.md/

Unfortunately I can't really promise any support for configuring or using the
plugin, but if you encounter any bugs or other unexpected behaviour, you can
try reaching me via the Facebook page. 

14. DONATIONS

The plugin is, and will be, provided free of charge.

However, it took me some time and effort to do research and write the code, so
if you find the plugin quite useful and are able to show your appreciation by
donating a small amount via PayPal, I would be very grateful.
You can find the Donate button at: https://antero.eu/seo-for-wdt-md/
(any donations go to the expenses of my non-profit web projects, such as this
plugin and a few websites I'm working on).

---
Antero Alex Kiltti
