Amongst the holiday time come for me a wee bit of time to attend to more minor code bits in my WordPress SPLOT themes that will likely rarely be noticed.
For those that actually still use their WordPress sites, you likely as well do not notice that when you go to tag a post, WordPress kindly offers suggestions for tags to use as you type in the box… say a tag such as “splot”
Tagging inherently is messy. Even in your own sites. you forget which tags you used before, or you may not type them the same like do I use trucollector or tru-collector? I apparently have used both.
Tag suggestions are one way to nudge use to re-ue existing tags. No one ever asked for this feature, I just felt like it should be there.
Tagging content remains an underused capability to cross-connect related items, in a way not dictated by code or algorithm or design, but by the people who use your tool. See it in use in one of the earliest course applications of TRU Collector, a visual arts collection with over 450 student submitted entries for the TRU Visual Arts course where the tags on the left indicate art terms or subject as well as the Coventry University WordBox with the tags are used to indicate sources.
These are methods not designed by software, but enabled. The way they are used are designed by the people creating a site.
This feature has been built in to the SPLOT themes for a while. It’s a bit tricky as the WordPress functionality is designed for the dashboard, and getting it to work on a front end form has not been easy, especially as I have found virtually no clear documentation on it.
And— since I have pretty much done away with needing a secret log in to WordPress, it was not even working. So here I have a bit of updated information on theme updating, and the code gnarly details of figuring out the puzzle.
This bothered me, but now it is fully available in TRU Writer, TRU Collector, and SPLOTbox themes and can be used with the contribution forms on the demo sites of TRU Writer, TRU Collector, and SPLOTbox.
When adding a new feature, I like to give it a test run on one of these sites, so see one that used this new feature at https://splot.ca/collector/770/.
A Review of SPLOT Theme Updates
For the most part, when I have casually looked around at sites using SPLOT themes, most rarely update the themes. So they miss out on features (and bug fixes) that are ongoing.
This is more to do with the arcanenes of “unofficial” WordPress themes (maybe in a galaxy far far far away I might get around to making SPLOTs pass the muster tests to get in the WordPress theme repository). Also, until WordPress 5.5 once you uploaded a theme as a ZIP file, you could not update it without resorting to manual uploading via ftp or relying on plugins like Easy Theme and Plugin Updater.
Your update options are a bit less onerous in 2021, and I have been trying to get the options spelled out a bit more clearly. These include:
- The most automated way to keep themes up to date is the WP Pusher plugin (detailed in a post with a Steppenwolf reference). This lets you install a SPLOT theme directly from GitHub, and set it up so when I update the theme there, they are pushed to your site. Automagically. But I will lose most readers at the prospect of anther plugin AND making a github account. If you want to scare every day people away from your technology, just whisper “github” or “markdown”
- Do it Yourself. As of WordPress 5.5 you can update a manually uploaded theme or plugin the same way you installed it, by uploading a .zip file of a new version in the WordPress Themes area. (or you old schoolers can just manually upload new files by ftp…) This means you choose when to update. Hey look, someone blogged about this too.
- Reclaim Hosting cpanel installers. I’ve been honored that Reclaim Hosting has made TRU Writer and TRU Collector set up as a one click install under Featured Apps in all customer cpanel. This is quite elegant, as you get not only a new WordPress site installed with the necessary theme files, they even have it set up to add in any needed/suggested plugins, and populate the site with demo content. It too will be updated, but the frequency is less often, as it requires Alan to remember to mark a new release, and someone at Reclaim to update their scripts that actually do the work. Also, for some arcane reason, these installs will not automatically connect logins from your cpanel, so be sure to remember your admin login details.
See if this was all some LMS-ish type infrastructure, you would not even have options to choose from, and in fact, you would not get a say as to what you can even use. So you have great freedome, great responsibility, Peter Parker’s Uncle words ringing true.
My suggestion for most people with self hosted sites is the second one. You will learn the most about making use of these SPLOTs if you go through some of the set up manually. But at least updating a non prime time theme like SPLOTs is much easier in WordPress.
The Nitty Gritty Details of Tag Suggestion
Feel free to quietly exit this post as code shall commence.
Getting this to work has required the usual rounds of wading through StackExchange posts, comments in WordPress forums, developer blog posts, foraging in the WordPress code, and a lot of just trying things out by hammering until it works. I cannot recall but I think my starting point was a post Using WordPress built-in tag auto complete script in your Plugins in the blog named Night Dreaming (by Sudar).
Just to reiterate, the tag suggestions is designed for use in the WordPress dashboard (available for plugin developers too), where you get much more functionality available than from a form on the front of a site, that SPLOTs use.
A few things need to be set up in advance, this is within a few scripts of the themes that enqueue, or make available to a page, various jQuery libraries and other goodies you might need. My code has a test to make this only happen when a viewer is on the page with the form.
The first is to make sure the jQuery suggest library is available. I totally lost track of where I learned this, but it’s listed amongst the various jQuery libraries WordPress makes available. I am fairly sure this happens for logged in users with access to admin stuff, but for the general SPLOT user, they are not logged in (anymore), so I make it available this way in the place I am lining up scripts:
|
1 2 3 4 |
if (! is_admin() ) { // Build in tag auto complete script wp_enqueue_script( 'suggest' ); } |
I think I got a clue on how to set this up from a post by the HollerBox developer, that the suggest library creates a method you attach that triggers an ajax call when something is entered in a field- this lives in a jQuery code I enqueue as well.
It makes this call via a function typically available for logged in users to make use of ajax functionality in the dashboard- and my script needs to know the URL for a php file that manages ajax. I found a nifty way to pass this to my jQuery script via wp_localize (look a post on this!).
All this means is that I can pass some data my jQuery script will need from WordPress php functions, and this is done between registering my jQuery script and enqueuing it:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
// custom jquery for the uploader on the form wp_register_script( 'jquery.collector' , get_stylesheet_directory_uri() . '/js/jquery.collector.js', array( 'suggest') , false, true ); // add a local variable for the site's home url wp_localize_script( 'jquery.collector', 'collectorObject', array( 'ajaxUrl' => admin_url('admin-ajax.php'), 'siteUrl' => esc_url(home_url()), 'uploadMax' => trucollector_option('upload_max' ) ) ); wp_enqueue_script( 'jquery.collector' ); |
I make my script depend on the suggest script being loaded earlier and pass to it via a variable a few values the script needs, in this case ajaxUrl the URL for a site’s ajax library, plus the site’s own URL in siteURL, and the value of a theme option that contains the maximum upload size for files a site owner has defined.
All of this done, so that in the jQuery code used for say TRU Collector’s sharing form, I can use something like the standard ajax call to add options for a tag suggestion used in a form element with id #wTags:
|
1 2 |
jQuery('#wTags').suggest( collectorObject.ajaxUrl + "?action=ajax_tag_search&tax=post_tag", {multiple:true, multipleSep: ","}); |
This is what worked for SPLOTs that were using the old method of having visitors invisibly logged in as a special site user. And it worked because the ajax_tag_search is available for logged in users. You do have to set up a few extra functions to provide ajax outside of the dashboard. I tried to test things out, as it was only working when I was logged in
With a lot of digging, I found the URLs being sent to ajax- if I am logged in to WordPress, a call to:
https://splot.ca/collector/wp-admin/admin-ajax.php?action=tag_search&tax=post_tag&q=splot
produces 3 matches:
But if you try that link, not logged in, you will see just a result of 0. So tag suggestions do not work without a logged in user.
This stumped me for a while. And thus I found the answer on my own. I poked around the WordPress codex and found the code that is called as I was doing it before.
And here was why the built-in function would not work
|
1 2 3 |
if ( ! current_user_can( $tax->cap->assign_terms ) ) { wp_die( -1 ); } |
This is an exit condition that prevents the tag suggestions from working for a non-logged in user. I got this idea, I copied this function to the SPLOT theme, and removed these lines, as my own function, called splot_ajax_tag_search In my set up code, I make this function available via ajax for both logged in and non-logged in users:
|
1 2 |
add_action( 'wp_ajax_nopriv_splot_ajax_tag_search', 'splot_ajax_tag_search' ); //allow on front-end add_action( 'wp_ajax_splot_ajax_tag_search', 'splot_ajax_tag_search' ); |
And then put it into use in my custom form jQuery code so it would call my tag function rather than WordPress’s
|
1 2 |
jQuery('#wTags').suggest( collectorObject.ajaxUrl + "?action=splot_ajax_tag_search&tax=post_tag", {multiple:true, multipleSep: ","}); |
This is almost all of it, and there was a small bit I had forgotten from my first attempts at this- all of the stuff that is rendered is not viewable. This is because it depends on the CSS that is included in the dashboard. The answer actually was in a comment from the Night Dreams blog post I started at – I just needed to lift from CSS to add to my theme.
So What?
This was a lot of circuitous bits to get to implementing a small feature. It’s not a “plugin” where you just get a magic fix in one click. It takes some digging around, uessing, a wee bit of frustration, but when it clicks… Ahh this feels good.
Most people will not need to know this. But give the new tagging features a try. If you have a SPLOT site now, see if you can update it.
And mostly, keep doing nifty things with it. That’s what motivates me to dive down the rabbit code holes.
Featured Image: A story here. I was looking for open licensed images for “tag” which mostly got me price tags. I tried “playing tag”, “freeze tag”, and then I just somehow ended up on one of those leachy public domain sites I prefer not using, pxhere. Look it’s a familiar photo it’s mine! At least they give me attribution by name now. I have enough info to find it in my own photos.
