The despair, by Pabak Sarkar

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:

Screenshot of Nelio Content's Dialog for Adding new Social Messages
Screenshot of Nelio Content’s Dialog for adding new social messages.

and this is what he was seeing in his WordPress:

Broken Dialog because of a Third-Party Plugin
Nelio Content’s Dialog is rendered completely unusable because of an incompatibility issue with a third-party plugin.

?? 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:

Screenshot of CSS rules applied to one element in a Nelio Content's dialog
Screenshot of the CSS rules applied to one element in a Nelio Content‘s dialog.

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:

Deactivating CSS rules in Chrome's Web Developer Tools
You can easily activate, deactivate, edit, add, or remove CSS rules in Chrome using its Web Developer Tools.

And this is the result:

Partially Broken Dialog because of a Third-Party Plugin
After deactivating some CSS rules added by PageFrog, Nelio Content‘s Dialog is finally usable. There are still a few issues to address, though.

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:

Default look and feel of a jQuery UI Dialog
Screenshot of jQuery UI page, where you can see the default look and feel of a dialog.

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):

PageFrog adds its own copy of jQuery UI
Screenshot of the HTML source code. In the head section, you can see that jQuery UI libraries are added twice.

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 admin/class-pagefrog-admin.php:

PageFrog registers and enqueues its own jQuery UI style
PageFrog registers and enqueues its own jQuery UI style.

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:

  1. One of our customers was about to leave us because our plugin wasn’t working.
  2. After confirming the issue and being able to reproduce it, I detected that the issue was generated by a third-party plugin.
  3. 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”.
  4. 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.

The Solution

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.

2 responses to “When WordPress’ Freedom Kills Your Business”

  1. […] When WordPress’ Freedom Kills Your Business – Nelio Software […]

  2. […] 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?)… Read original article here…. […]

Leave a Reply

Your email address will not be published. Required fields are marked *

I have read and agree to the Nelio Software Privacy Policy

Your personal data will be located on SiteGround and will be treated by Nelio Software with the sole purpose of publishing this comment here. The legitimation is carried out through your express consent. Contact us to access, rectify, limit, or delete your data.