********************************************************************** 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