Dead shortcodes and how to find them

Have you ever looked at your plugin list and wondered whether you actually using it anywhere?  Or perhaps deactivated a plugin or swopped themes without realising that you  now have a dead shortcode on a page or post somewhere telling the world that you really aren’t on  top of things in your websites.

Yes well, it happens.  This little plugin may help.

amr-shortcodes searchs through your published or future posts, pages etc looking for shortcodes.  It then lists the pages and the shortcodes that appear on them, with handly little links to edit the post.  It will also flag with a red cross if wordpress does not know about that shortcode anymore – ie the shortcode is dead and there is no function that will switch out the shortcode text for some wonderful other text.

It does not automatically delete the dead text, because you reallly should look at the page or post and delete any surrounding text as well that may no longer be relevant.

And then, just because it might be interesting, I added a tab so you can see the available shortcodes.

View and Manage shortcodes

amr-shortcodes

 

 

A simple little plugin

I’m kinda astounded at how popular the amr-shortcode-any-widget plugin is. The concept and execution is so fairly simple – clever perhaps 😉  but simple.

All it really does is

  • use wp  function to add a sidebar so that any widget settings can be setup using the widgets code
  • add a wordpress shortcode that will use wp functions to run the widget or widget area.  It’ll catch the widget output (so it doesn’t appear at top of the content) and return is as the shortcode so the widget output will appear where you put the shortode.

It certainly doesn’t have any css, any javascript, any jquery, any real settings.  It doesn’t save or create any new files, or impact the .htaccess, or permalinks.  It actually doesn’t do very much at all – truly.

If deactivating the plugin gets rid of an error, it is highly likely that it is because the widget you had in the shortcode sidebar is no longer being used.

Why did it come about?

It started when I wanted a quick fix. I wanted to use Justin Tadlock’s query posts widget plugin – but in a page – to save me having to code up a special template or shortcode.  I realised the key difference between shortcode and widgets and pondered how one could get around this situation where a developer had not offered both a widget and a shortcode or template.

So what is the difference between a widget and a shortcode?

Widgets when called, echo the html straight out. Each piece is output as it is calculated or extracted.

Shortcodes on the other work out the html for each piece and keep building a set of html. The shortcode function returns the total html to the calling code (wordpress). WordPress replaces the [shortcode text] with the html. It does this when it applies the ‘the_content’ filter to the_content.

Know you know this, you can debug these situations:

If you ever see a shortcode plugin that generates the output at the top of the content instead of where the shortcode is, then you know the developer hasn’t quite figured that he or she needs to ‘return’ the html, not ‘echo’ it.

And if the shortcode text just sits there doing nothing after you publish your page, then you know that the theme developer is either ‘not doing it right’ OR perhaps some other plugin is interfering, possibly removing the  ‘the_content’ filters.

How to catch the echoed output and have it appear in the right place?

OK, now the next handy piece is that php lets one buffer the output, rather then letting it echo out directly. So this plugin buffers the output, calls the widget and returns the widget output as the shortcode return value. It does not ‘flush’ the output (else we’d have two lots of the widget html)

Hmm widget settings? how to handle those?

Then I had to find a way for the user to specify the settings for the widget without getting too complicated.

A ‘dummy’ sidebar or widget area was the answer. Users have the same familiar interface. They can test their chosen widget in a normal sidebar and once it works, juts drag and drop that widget into the dummy sidebar.

The plugin knows nothing… well almost nothing

So the plugin does NOT know what widgets are being used, and doesn’t need to know – it’s just calling the widget and catching the widget output to stop it dumping at the top of the content. It then tosses the widget output back out to the shortcode function for wordpress to swop the shortcode text with the output.

That’s the basics.

After that came the extra features that people requested:

  • multiple instances of the same widget meant that id’s had to be used instead of widget names
  • themes where the sidebar background and text was opposite to the page meant that it would be handly to have easy ways to change the css that was being applied, for those who didn’t know how or didnt want to have to add css. Basically one can avoid some css being applied by removing widget classes or changing the html that surrounds the widget – the html tags that the theme is using.
  • then my personal bugbear was when widgets got ‘lost’ when a new theme was tried. So there is a bit of cleverness there to try to remember the widgets being used and add them back in after a new theme activation,
  • and most recently of course the wonderful suggestion to show the widget id at the bottom of the widgets to simplify finding out what id wordpress has assigned to it.

So while it has all these parameters for the shortcode and actually has two shortcodes ( a widget area one too just for fun), all it really does with them, is pass them over to wordpress to pass to the widget, just as wordpress would do when it calls the sidebar code.

Simple.

Debugging a possible clash between plugins and/or a theme

I’ve had to explain this many times, so now I just  link here.  Instead of messing around randomly trying different things, hitting more buttons, approach your problem systematically.

from one of my favourite comics http://xkcd.com/722/

Your theme and plugins can interact in ways that plugin or theme authors do not even realise.  For example tweaks to the wp query may unintentionally affect another plugin’s operation.  Inappropriate Javascript  inclusion also often clashes across wordpress.

The only definitive way to isolate the cause sometimes is to

  1. put your site into maintenance mode and then
  2. deactivate/activate plugins and your theme testing each step of the way.

First determine how to make the  problem visible.  What actions do you take that cause it?   Note the steps down – you will repeat these steps each time you make a change.

Disable any caching plugins and be aware you may need to clear your browser cache too, to ensure you are  seeing ‘new’ behaviour when you are testing.

Now decide which way you’d like to go.  This kinda depends on whether you have an inkling of which plugins might be causing a clash.  Personally I prefer option 1.  It tells me something the quickest, and knowing something sooner rather than later is rewarding.

Quick and Brutal Approach (gives info asap)

deactivate all plugins except the plugin you trying to get working. This has the advantage of fairly quickly telling you that the plugin does/does not work by itself:

  • Problem gone when just that plugin?  The plugin itself might still be causing the clash, but at least now you have some info to pass on to the developers.  Follow the’ problem gone’ after theme switch below.
  • Problem still there ? Switch to a default theme.  Themes do sometimes mess with wordpress operation.
    • Problem still there ? If you now have just the one plugin active and you are sure you are seeing updated pages, you can advise the plugin author that you are seeing the problem on a default wp theme and with no other plugins active.
    • Problem gone? Ok,  now go back to your theme.
      • If the problem reappears you know it is something clashing between your theme and the plugin.  Advise both authors with as much detail as you can.
    • Problem still gone now that you have your theme back?  Now slowly, checking after each activation, reactivate your plugins, starting with your most essential ones.  At some point the problem will re-occur, then you know the clash is between the most recently activated plugin and your new problem one.
    • Problem stays gone once all is reactivated? Weirdly this can happen.  Sometimes it is the order of activation that causes the problem.  Don’t close your eyes and celebrate – a plugin update could cause the problem to come back.  Now you may have to play around with activation sequences here to find the clash

Slow and Steady also gets there in the end

Another approach is step by step deactivation and  switch theme to default theme until the problem disappears.

At some point the problem may go away, then reactive the last plugin active and check if the problem comes back.   Now you know it is part of the ‘clash’ somehow.

Recently Active Plugins

If you are one of those folks who keeps a lot of deactivated plugins hanging around and you forget which ones you really need, don’t panic – WordPress very nicely gives you a week in which it remembers which plugins you had active recently.