Let me preface the following post by saying this: I am sorry if your site was affected by the WP 4.2.3 update. I’m sure nobody on the core team wanted things to break and if they could go back in time and do things differently, then I think they would.
So for the uninformed, on July 23, 2015 the WP core team released a security update that was installed to millions of websites via automatic updates. For a lot of people, this was fine and they weren’t affected by the change. However, another group of sites (some would argue a large portion) were broken due to breaking changes in the WP Shortcode API. This isn’t a post about the shortcode API or the vulnerability though. You can read about the update on the Make WP Core blog.
Why things should not have broken.
Take this section as a grain of salt, and recognize it as my opinion. You don’t have to agree, and I don’t expect everyone too.
I have been developing on the WordPress platform for about 3 years now. I currently work for a small digital marketing agency in Northern Kansas as the sole developer creating websites for our clients. Before I started working here, the previous developer had built a lot of sites using premium themes from Themeforest, which as we all know, usually include a bunch of shortcodes for inserting content and functionality across the site. After doing support for a few of these clients, I quickly realized that shortcodes were not a solution for displaying content for our clients. Not only were they messy and difficult for clients to understand (in some instances) but they created a dependency that I was not comfortable with on such a widespread scale. A client accidentally deactivating a plugin could remove some core pieces of content; it was something I just wasn’t comfortable with.
I started to build out themes for our clients using _S and designs from our in house designer. I jumped onto the ACF bandwagon just before the release of v5 and have been using the Pro version on all of our clients’ sites with great success (Elliot’s commitment to backwards compatibility is another post for another time). ACF allowed me to create highly customized interfaces for our clients, while utilizing an API that would work regardless of if ACF was activated or installed (check out Bill Erickson’s post about removing dependencies from ACF). Over time, I have migrated some clients over to a more customized solution when they would come to us after having difficulty manipulating shortcodes and they have loved it.
Now I know what you’re thinking, “But Daron, using ACF ties you to a theme and that’s bad if you’re a blogger who likes flexibility!” And you’re right. Tethering some clients to a specific theme just isn’t an option, but that isn’t an excuse to build solutions that are fundamentally flawed. One of the use cases that really blew my mind, was how people were outputting and manipulating URLs via shortcode. A much better approach would have been to use custom fields and post meta and then calling that data from the theme. Another alternative would be to build a custom plugin with a simple admin interface and some custom metaboxes.
In the Make WP post, Andrew mentioned how people were using the shortcode API in ways that it was never intended for. You don’t need to look any further than the default
[gallery] shortcode to see what the core team was talking about. The gallery shortcode is completely self contained. It outputs it’s own HTML and any attributes needed to attach styling to. If you’re building shortcodes to output a link to an image or to a URL, then you’re fundamentally using shortcodes in the wrong way. Using actions and filters, you can display all sorts of things in and around
the_content. If you need to link a background image, you should be using the customizer or a custom field/metabox. For one, using a custom metabox is a vastly superior UX as well as giving you the peace of mind that sites won’t break because of a fundamentally flawed implementation. The shortcode codex entry does not mention using shortcodes as a replacement for HTML attributes and it probably never will. If you’re site needs to be that customizable, you should be using custom fields and metaboxes.
If you want to remove the theme dependency from solutions like ACF and CMB2, use a hook and display that data programatically. This is a totally valid way to show custom content:
Just pop that into a plugin file and you’re off to the races. If you need more programatic control over where content is displayed, then you should look into developing a custom theme or using a more inclusive shortcode. Note, the
$extra_content variable should include all of the HTML necessary to support itself. You can enqueue CSS as needed from the plugin as well.
Here is another example that was specifically mentioned in the Make WP article and a workaround that doesn’t require hacking a theme.
Using the above snippet, you can wrap
the_content in a div and apply a background image to that div. Using CSS you can further position the image how you want. You can even include that CSS in the same plugin, thus removing any theme dependency.
We as developers are responsible for when things break and it’s only in our best interest to use the tools that we are given to build applications and solutions that will stand the test of time. Hacking APIs is never a good solution to a problem and it’s up to us to use some common sense and read the documentation on the intended uses of the software that we leverage everyday. Sure, people will always find new ways to use software that the developers never intentioned, however, you do not have the right to be upset when you’ve implemented an unofficial workaround for a problem that is easily solved by utilizing other techniques and APIs. The core team did everything they could to avoid breaking things. Problem is, it’s impossibly to foresee every possible unofficial use-case for every API in the software. Stop giving them flack for your experimental implementations of the API.
I know this probably seems like a disorganized rant, and in some ways, it probably is, but I needed to get it out there and off of my mind. Leave a comment if you want to continue the discussion or you can tweet me @Daronspence