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.


Debugging a possible clash between plugins and/or a theme

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

Put your site into maintenance mode and then 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.

Quick and Brutal Approach (gives you info the fastest)

deactivate all plugins except the plugin you trying to get working. This has the advantage of quickly telling you if 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.

Must use plugins

If you have plugins showing up as ‘must use’ plugins and the problem is still there after deactivating other plugins and using default theme, you may need to use ftp or your control panel file manager to temporarily move the must use plugins in case there is code in there that is causing the clash.

Warning for older themes, or perhaps not so well written themes

Most themes should keep their settings and widgets and all should be fine when you switch back to that theme.¬† There some that don’t.¬† Make sure you have a backup that you know how to restore from OR that you know your theme’s settings and what widgets were being used where.

Recently Active Plugins

Your temporarily deactivated plugins will be in ‘recently active’.¬†¬† This makes it really easy to reactivate them.

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.

Call current_user_can after init()

Running buddypress? Are you getting a debug notice like this:

The current user is being initialized without using $wp->init()

and you cannot figure out where it is coming from ?

Most likely one of your plugins is calling a user related wordpress function a bit early (see wordpress action sequence).   You could try deactivating them until the debug message goes away.  The last plugin deactivated will be it.  Let the developer know because his/her code may not be quite working the way it was intended to.

eg: current_user_can()  or possibly  wp_set_current_user()

These need to be used after the init action.  The plugin or theme might have something like

add_action ('plugins_loaded', 'some_function');

The action should be added later, when the current user has been initialised.

add_action ('init', 'some_function');