Last week one of our customers opened a support ticket describing a weird issue—when he tried to use our plugin, its UI was broken, rendering it completely unusable. Since I’m the one who usually takes care of incoming issues, I’m quite familiar with the problems our customers face… but this was the first time I heard about “a broken UI that makes our plugin unusable” 🤔 Indeed, a weird issue.
Just so you know, this is how our plugin’s supposed to look like:
and this is what he was seeing in his WordPress:
😨😱 What the heck?! Our customer was completely right—our plugin can’t be used at all! Just look at the previous screenshot: the editor’s toolbar is over the dialog, the dialog’s layout is completely off, the look and feel is changed (who added this orange bar?)…
Reproducing the Issue
Whenever a user reports an issue, the first thing you need to do is (try to) reproduce it in your development environment. Sometimes reproducing an issue can be very complicated (for instance, they may involve AJAX calls on slow Internet connections). At other times, it’s as easy as activating a setting or installing a third-party plugin. Users will usually offer some information about the circumstances in which they encountered the problem, so that you can reproduce it yourself—if they don’t, ask them for more information until you do.
In this particular case, the issue was super easy to reproduce—I simply had to activate another plugin (Facebook Instant Articles & Google AMP Pages by PageFrog) in my local environment. For those who don’t know anything about PageFrog:
The PageFrog plugin allows you to easily publish and manage your content directly from WordPress to Facebook Instant Articles (FBIA) and Google Accelerated Mobile Pages (AMP) with full support for ads and analytics.
In principle, there’s no reason for our plugin being incompatible with PageFrog’s. So, why do things go wrong when both plugins are active?
Determining the Source
At this point we’ve already confirmed that an issue exists and we’ve been able to reproduce it locally 💪. So far, so good. Now we need to know why this occurs and find a solution. Unfortunately, there are no guidelines or tips I can give you to help you solve these issues—you’ll have to rely on your experience.
In this case, my gut told me the problem was clearly related to the CSS rules that were applied to Nelio Content’s dialog, which somehow were overwritten by PageFrog (or something like that). Remember how we reproduced the issue:
- If PageFrog isn’t active, our dialog looks beautiful.
- If PageFrog is active, our dialog gets broken.
so the problem must be introduced by PageFrog, and it’s probably related to its CSS rules.
In order to validate this hypothesis, I simply inspected some HTML elements in my dialog using Chrome’s Web Developer Tools and looked for a rule added by PageFrog. For instance, when I inspected the
textarea for writing the social message, this is what I saw:
Remember that Chrome sorts the rules from more concrete to more generic. See the rules at the bottom (that is, the “most generic” rules) of the previous screenshot? These ones:
They are inserted by a script named
pagefrog-admin.css. Is it possible that these rules are the ones responsible of breaking the look and feel of our plugin? There’s only one way to tell—let’s deactivate them and see what happens. You can easily deactivate the rules in Chrome’s Developer Tools:
And this is the result:
Not bad! Now Nelio Content’s dialog looks “quite good”—its layout is no longer broken and a user can use it. However, we haven’t fixed the issue completely:
- TinyMCE’s toolbar is still over the dialog (even though it should be below it).
- The black overlay that darkens the background when a dialog is open isn’t over the Dashboard menu.
- The look and feel of the dialog itself (not its content) doesn’t match the look and feel of WordPress. Its colors look different, the style of the bar is different, the buttons are different…
Clearly, there’s a lot of “weird things” going on in this dialog. If you don’t know it, let me tell you that these dialogs (and other WordPress UI Components) are powered by jQuery’s UI library, whose dialogs by default look like this:
Look at the title bar, the close button, or the rounded corners, and compare them to their counterparts in Nelio Content’s broken dialog (the one modified by PageFrog’s plugin). They look very similar, don’t they? Sure, Nelio Content’s has a few differences (for instance, the title bar is orange instead of grey), but still, the resemblance is surprising. What’s going on here? 🤔
Again, you’ll have to hypothesise a possible explanation based on your gut and experience. In this particular case, I thought that, maybe, the developers at PageFrog were adding their own jQuery UI styles, overwriting WordPress’ defaults. A quick scan of the HTML source code confirmed this hypothesis (look at line 45):
The offending script is identified by
jquery_ui-css. If the script was enqueued using WordPress default functions, we should be able to find in the plugin’s source code a snippet where a script named
jquery_ui is being registered and/or enqueued. Guess what? We found it in
If we comment out this custom script, the custom appearance disappears and our dialog looks beautiful again.
When WordPress’ Freedom
Kills Saves Your Business
After discovering what caused the issue at hand, I couldn’t help but think that WordPress’ Freedom was somehow killing our business. These were the facts:
- One of our customers was about to leave us because our plugin wasn’t working.
- After confirming the issue and being able to reproduce it, I detected that the issue was generated by a third-party plugin.
- I had to dive into this plugin’s code to find out what was amiss and propose a solution, spending some of my time “working for somebody else”.
- The problem occurred because WordPress doesn’t have any limits whatsoever on the scripts and rules you add (and overwrite), allowing one plugin to mess with the behaviour and appearance of another plugin.
So it was clear to me: when developers are free to do whatever they want, they (we) will end up messing with other people’s code. We don’t mean any harm, of course, but the end result is the same—we screwed you.
But it turns out, WordPress’ freedom (and its developers’) doesn’t kill your business—it’s exactly the opposite. Because of WordPress being open source, I was able to explore the source code of the plugin causing an incompatibility issue and find a solution for it. I was able to contact the developers and ask them for a fix. And if they aren’t able to produce it, I’m free to implement this solution all by myself and make sure that our customers can use both plugins safely. Just as Yoast did, for example.
Now, don’t get me wrong. I still think that we developers should be more careful when it comes to writing code. Knowing how WordPress and the web work, we must be tidy and responsible. For example, if you add your custom admin pages in the Dashboard, enqueue your own styles and scripts on those pages only, not on every other page.
The issue I described today occurred because two different plugins (Nelio Content and PageFrog) were both modifying the same page: the post editor screen. Each plugin needs its own scripts and styles, so it’s always possible that one plugin overwrites the other unintentionally. They key here is that every plugin should use its own scope.
PageFrog can easily fix the issues we identified. On the one hand, its developers should change the generic CSS rules with a more specific rule set. For example:
On the other hand, they shouldn’t add jQuery UI’s stylesheet and overwrite WordPress’ default styles. Again, they should probably modify that stylesheet so that it only applies to jQuery components generated by their own plugin.
We’re an open source community. We’re here to help each other and to learn from each other. I contacted the developers at PageFrog a couple of days before this post was published, and at that time I was still waiting for their response. I hope they’ll help us overcome this issue. And if they can’t, I’m not worried, for I know how to fix it 😆
And you, have you ever encountered an issue like this in your own plugins? Or, alternatively, has one of your plugins caused trouble to somebody else’s work? Share your thoughts on this topic!
Featured image by Pabak Sarkar.