I spent over 4 hours this morning troubleshooting a mysterious and equally frustrating pr0blem with the menu of one of the many WordPress sites I’ve worked on and want to document my findings for posterity.

I should pre-empt all this by saying that I am not a programmer.  I’m good at troubleshooting technical problems based on observation, trial and error – but I’m not a programmer.  So there may have been a far easier way to resolve this problem – as well as a more technically appropriate solution – however this is what I experienced, and what I did to fix it.

Suggestions on better solutions are wholeheartedly welcome.

Background

By design, the site incorporates a large number of pages (not posts).  In this sense we’ve used WordPress as more of a content management system (CMS) than a blogging platform.  Having used Drupal in the past, I find WordPress quicker to set up and easier to maintain, and thought it might be sufficient for this particular project – especially given the fact the primary users were relatively inexperienced technical users. (I still love Drupal though, no doubt about it.)

By and large WordPress has indeed been a great solution, however due to the nature of the number of pages (over 20), using the default menu option just wouldn’t have worked.  So we instead opted to go with the Multi-level Navigation Plugin.

By and large for the last few months it’s been a fantastic plugin that’s done everything we need it to.  However all of a sudden within the last little while it stopped working, and I wasn’t sure why.

Variables and Uncertainties

The fact is I’m not sure exactly when it stopped working, which posed some major challenges in the troubleshooting of the issue, since I’m not the primary user, moderator or administrator of the site and am not sure what changes may or may not have been made recently.

I do know that the primary users are not ones to mess around with source code or WordPress Dashboard settings, run updates or install additional plugins – only add and edit content.  So while it is possible that someone changed something, I’d say it’s fairly unlikely.

That said though, I do not believe the issue resulted from a bug or fault with the plugin.  Truth be told I have no idea what’s caused the problem, only what the symptoms where and what I’ve done to fix it.

This is why I’m documenting this problem.  The root cause is unclear, and as such I didn’t find much information available on how to go about troubleshooting it. Only through sheer force of will did I manage to narrow down the search to the header.php file in the theme I’m using.

The symptoms

In short, the links in the menu were not clickable; nor could you browse down through the page hierarchy.  The first level menu items were displayed as you’d expect, but that was the extent of things.  It’s as if they were just static text.

And yet the plugin settings all checked out, and the pages all existed; plus you could load them in the browser if you knew the direct URLs.  The page links were also displayed properly in the page source.  Swapping back to the native/default WordPress menu also worked successfully.

Additionally Internet Explorer displayed the menu properly, but all other browsers on the PC didn’t.  These included Safari, Firefox and Chrome.

To confuse matters more, I attempted to reproduce the error by exporting the pages and content from the main site, importing them into a test site, installing the Multi-level Navigation Plugin and configuring the settings in the same way – I even used the same banner graphic.  However the test site worked perfectly across all browsers.

The workaround

In the end the workaround lay in the header.php file of the theme I was using (Irrigation).

During the set-up process for the plugin, in addition to activating the plugin you also have to add a single line of code to the header.php page:

<?php if (function_exists('pixopoint_menu')) {pixopoint_menu();} ?>

You then have to either remove the native theme menu code or comment it out using

<!-- [original code here] -->.

Both of which I’d done some time before.

For some reason in order to fix the problem this morning I had to precede the plugin’s code with two additional break tags – <br><br> – before the menu was clickable again.

In other words:

<br><br><?php if (function_exists('pixopoint_menu')) {pixopoint_menu();} ?>

Lo and behold, once I’d made that change the menu started working again.

Non-techie explanation

My current theory is that the banner graphic was obscuring the portion of the menu that recognised the mouse cursor and which was needed to show you the menu options, and then click on a page.  In effect, the menu didn’t know you were trying to bring up the navigation options because the banner graphic was somehow in the way (even though it didn’t look like it).

While this does resolve the issue – or at least provide a workaround – what it doesn’t do is explain why the menu stopped working in the first place…