I’m not the first to write a post like this, nor will I be the last. But Jetpack, the ubiquitous plugin from Automattic, is likely one of the most polarizing collections of code in the WordPress universe. And in recent days it has occupied its own special level of hell for me.
Sharing
Let’s start with Jetpack Sharing, né Sharedaddy. Sharedaddy is but one of many standalone plugins that Jetpack has consumed since its inception. To use it, like the rest Jetpack, you are “required” to connect to WordPress.com, even though there isn’t any functionality about Jetpack Sharing that needs it. (WordPress.com connections are needed to make some other modules work, but Sharing isn’t one of them. And technically, Jetpack has a debugging mode which allows for non-connected use, but that mode isn’t recommended on production environments.) WordPress.com connections are a whole other level of complaint, but not actually related to the problems I’ve been having with Jetpack for this project.
My problems started when I wanted to update the styling for the “Sharing label”. If I used the CSS that was included with Jetpack, specificity problems forced me to use the “!important” flag in my CSS to override it. That’s because Jetpack uses IDs as CSS selectors, a practice that I highly discourage because of the specificity issues. I don’t like using the “!important” flag either (whenever that’s an answer for how to write CSS, it’s the wrong answer), so that ultimately left me with one viable solution: check the “Disable CSS and JS” option, and pull those into my theme manually.
But if only it were so easy. At first, I thought this would be better. I could roll the CSS into my Sass structure, and the JavaScript into my Grunt concatenation and minification tasks, and save some HTTP requests in the process. The CSS worked well enough (despite, sigh, the ID selectors), but moving the JavaScript broke the email sharing, a vital feature for the client. A lot of head-vs-desk later, I finally found in the sharing-service.php the two lines of code that set the translation for the recaptcha_options. Nothing in the “Disable CSS and JS” option warned me about this. Copy those into your functions.php file along with your valid wp_enqueue_script() function call to activate your version of the JavaScript, and you’re in business. But that’s a few hours of my life I won’t get back.
One last problem related to sharing: one of the client requirements for this project is insertion of the “via @twitterhandle” flag in every tweet sent via Jetpack Sharing. I had no clue how this could be accomplished easily, since there was no setting in the preferences to handle this. My fear was I would have to extract Sharing out of Jetpack (fortunately — or not, depending on your point of view — someone else has done this already), hack that to create that option, and save it as a separate plugin so that my efforts would not disappear on the next Jetpack update.
Fortunately, and pretty much accidentally, a little grepping through the code revealed the jetpack_sharing_twitter_via filter. Googling that led me to this article on WPSpeak, a WordPress help site that I had never heard of before. Four lines in my functions.php file, and hours of work saved. I guess it all balances out?
well, if my whole debacle with jetpack on tuesday taught me anything, look for filters that will do what you need! #WordPress
— tracy rotton (@taupecat) January 23, 2014
I’m a fairly seasoned WordPress developer, and even a minor core contributor, and it took serendipity and a knowledge of WordPress filter hooks to find and implement that. How is your average “I just want a simple blog” site owner supposed to? There’s a settings API for a reason.
Infinite Scroll
There’s even more issues I had with Sharing, but even if you’re still reading this, I’m pretty sure you’re probably sick of that topic. So let’s talk Infinite Scroll. Pretty popular tool and while I’m not a particular fan of that paradigm on any site, again we’re talking client requirements. My memory on the problems with this is a little hazy since I worked on this piece before New Year’s, but what I do remember is it just wouldn’t work. Try as I might, following all the tutorials, I simply could not get Infinite Scroll to work as advertised.
As with the sharing issues, I resigned myself to the fact I was going to have to roll my own. I’m not an Ajax guru, so the thought daunted me, until I found this. It’s not great code. It uses query_posts(). The jQuery is a bit sloppy, and it doesn’t take into account custom taxonomies.
But you know what? It worked. Immediately. Yes, I had to spend a few hours dealing with code issues and my client’s requirements, but I got farther with this in half an hour than I did with Jetpack in half a day.
I’ll take crappy code that works over pristine code that doesn’t any day. #webdev
— tracy rotton (@taupecat) December 27, 2013
Because really, when all is said and done, we need things to work.
Conclusion
These are only the specific problems. I have a lot of conceptual problems with Jetpack as well, many of which have been covered ad nauseum elsewhere. How it consumes other solid standalone plugins (I called it a black hole of standalone plugins). How it requires a WordPress.com connection to do things that don’t require WordPress.com. Lack of documentation. Lack of organization in its own special dashboard area. You get the idea.
Jetpack is a victim of its own hunger to be all things to all people. As a result, it gets in its own way, and challenges developers to get their sites working despite it, rather than because of it. I use it because in its modules there are legacy plugins that I need and can no longer be obtained on their own, but I wish that weren’t so often the case.
Nice post! Jetpack support team member here.
I’ll start by saying that you shouldn’t have to deal with this alone: if you have a question or get stuck with a specific Jetpack module, reach out to us! You can contact us via email, ping us on twitter, on Facebook, or post in the Jetpack support forums. I prefer the forums since your questions become useful to other Jetpack users later on, but that’s really up to you.
Let me see if I can help with the issues I mentioned here.
Feel free to use Jetpack’s Development mode in your production environments. It won’t break anything, it’s totally fine to use it on any site using Jetpack.
As I mentioned in the forum thread you referred to, you should be able to overwrite CSS styles by being more specific in your CSS declarations. For example, to change the colour of the sharing label on this site:
#primary .entry-content div.sharedaddy div.sd-sharing h3 {
color: red;
}
If you run into issues that cannot be solved without using
!important, let us know about it! We’ll be happy to take a closer look and see if we can help or maybe fix Jetpack.This tutorial is probably what you were looking for. It allows you to enqueue Sharedaddy’s JS file back after disabling it in the sharing screen. This way you don’t have to keep a separate copy of that file, and you don’t have to deal with
wp_localize_script.I’ve added a link to that tutorial in our Sharing documentation. That’s a bit too late for you, but hopefully that will help others!
Do you have any suggestions to improve this option? To be honest, I’d rather remove that checkbox from the sharing screen since it’s obviously something very few people use in Jetpack today and will break the sharing buttons unless you add some code back to your site. I’ve created an issue here so we can start chatting about it. Feel free to let me know what you think there!
That’s a quite common request; a bit of googling reveals quite a few threads in the Jetpack support forums, as well as this plugin. But you’re right, this should be more obvious; I edited the sharing support document to include a link to the plugin.
That’s probably going to change in a future Jetpack update. You can join our discussion here if you’d like!
Yes, we could add settings for each one of the options we’ve added to Jetpack; that would make the plugin considerably more complicated though. More options is not always a good thing. Decisions, Not Options, and all that.
We do want people to be able to customize Jetpack, though. That’s why we keep adding filters to the plugin (293 as of today).
The average site owner won’t know how to use these filters, but they can use plugins that extend Jetpack’s functionality, like the one I mentioned earlier. They can also search for what they need on Google; with a bit of luck, they’ll find a thread in the Jetpack support forums with the snippet they need. If they don’t feel comfortable editing PHP files, they can contact us and we’ll wrap the code snippet they need in a small plugin. Or they could get in touch with a WordPress developer like you and you’ll help them like we do!
George Stephanis (one of the Jetpack devs) also started working on a “Jetpack Extra Options panel” (#); this plugin would give you access to some of these filters without playing with code. Other developers have done similar things to answer their own needs; Rocketeer and Jetpack Extras are 2 good examples. You can also check my WordPress.org profile for more examples. If you use Jetpack a lot when doing client work, you could build your own plugin too!
When people have trouble adding Infinite Scroll support to their themes, and if the support docs don’t help, I sometimes point them to one of the default themes, to _s or to one of Automattic’s themes. I find it easier to understand how your template structure should be built if you have working examples in front of you.
But really, if you get stuck on something, don’t hesitate to contact us! We’ll be happy to see what we can do to help!
That’s clearly the underlying issue behind the problems you’ve mentioned in this post. And that’s my fault.
It seems like we should expand the existing support documents to add more information about all the filters and ways to tweak Jetpack’s default behaviour. But I’m afraid that would be too much information, and wouldn’t be useful to most users.
Maybe we should create some kind of codex to list and document all Jetpack functions and filters. Would that be helpful? I’d love to hear your ideas on this.
Thanks so much for the reply, Jeremy! There’s a lot in both the original post and in your reply, so let’s see what we can hit…
Debugging Mode
I believe when this option was first introduced, it was implied that it was for testing only. Either way, “JETPACK_DEV_DEBUG” doesn’t exactly scream “Safe for production use.” But it’s good to know that that is an accepted usage.
CSS
To be more specific would require using IDs as selectors. Not a practice I’m fond of. So it was choosing between the lesser of two evils, and I picked door number three. And mixed my metaphors.
Broken Email
Thanks for the link. That would’ve come in handy yesterday, but I figured it out anyway. Say, here’s a thought, ever think of putting a search field in Jetpack.me? 🙂 I’ll take a look at that issue thread later and add more thoughts.
via @twitterhandle
In his SEO plugin, Yoast manages to find a way to include many options without going full-on Weaver II. Certainly there are a number of ways that Twitter can be configured, and there’s another instance where I’m going to need to do something similar for our agency site. Having a few fields in the Sharing settings (perhaps in another tab) isn’t going to destroy Western civilization.
Trust me, I’m all for Decisions, Not Options. I quote Kovshenin’s talk about that at WordCamp SF in the book I’m writing. But in this case, it was the client making the decision.
Pluginception
You mention several times about plugins that enhance and expand Jetpack’s native capabilities and options. I ran into a similar instance while working on the Mailchimp portion of this project, where I found plugins who literally had in their feature list “bug fixes for other Mailchimp plugins.” That kind of pluginception feels, if not icky, then at least slightly absurd, maybe?
But you are right in that as a developer, I do have the power to go into the code, find these filters, action hooks, and other pieces that are configurable and change them for my clients, whether through writing my own plugin (which I do anyway since invariably these projects end up needed custom post types, which should not be in the theme, but I digress), or finding something someone else has put together. But some of these things seem so basic, I wonder why they’re not native to Jetpack to begin with.
I look forward to seeing George’s efforts, and will look into the others that you mention.
Infinite Scroll
Otto has already mentioned his tutorial about using infinite scroll, and his was what I was referencing when trying to get mine to work. I just don’t know if I was too dense to understand what I was doing wrong, or if my setup was too specialized for Jetpack to handle, or somewhere in between.
Documentation
Saving the best for last.
If you’re going to have 293 filters, then I’d say yes, you need a codex. Perhaps most of the users who simply download and install Jetpack and then forget about it wouldn’t need it, but that’s only part of the WordPress community. Certainly the WordPress codex has “beginner” information, as well as “super-ninja” information, and everything in between. Better to over-document than to under-document, and I think The Sass Way does a good job segmenting its guides into “Beginner,” “Intermediate,” and “Advanced” sections, listed right up top in the main navigation. Perhaps an option to explore?
Thank you again for your comment. I think we can all chip in to make Jetpack somewhat less of a hair-pulling experience.
P.S., the pull request stuff I mentioned on Twitter didn’t even make it into this post. I’ll bring that stuff up in the GitHub repo later.
You can only search when on the Support page at the moment, but I guess we could add a form to the home page as well. I’ll see what we can do!
Check the Pull Request I mentioned earlier. It does just that, and I hope it will be included in a future Jetpack release!
I don’t know, I like the idea. It allows you to extend a plugin without touching the original plugin files. I guess I would compare this to Child Themes extending Parent Themes.
I think that’s also where the Jetpack “child plugins” prove useful: if someone releases a child plugin and if it proves to be successful, it becomes easier for you or me to make the case for adding this feature to Jetpack.
That’s what happened with a child plugin I released last year that added a subscription widget shortcode; we saw that it was popular, and decided to add it to Jetpack.
Pitching that idea to my colleagues right now! 🙂
I examined the Infinite Scroll code in great detail once, and ending up writing this tutorial about it:
http://ottopress.com/2012/jetpack-and-the-infinite-scroll/
If you’re still having problems getting it to work for your theme, email me and I may be able to take a look at the theme and give you a hand.
Yours is the tutorial I relied on heavily in my attempts to get things working. I still don’t know if it was a problem with the clients’ requirements (it’s a heavily custom-taxonomied custom post type archive page), or just my lame attempts to integrate it. When deadlines aren’t such an issue (i.e., when I have some time to play with this on this site), I will make a more concerted effort to learn how to get it working.
For now, however, the alternate method I found is “working”, even though it also has some serious problems.
Thanks for the comment!
I really do wish there were better documentation for Jetpack. It gets very frustrating having to search around for answers when it should be quite easy. There are a few things WordPress does not document well enough and I think the community could benefit from better explanations.
Jetpack is giving tough time with my hosting server because of the automatic backup.How do i disable it?
I would take all support issues on Jetpack to the WordPress.org support forums: https://wordpress.org/support/plugin/jetpack
Thanks Tracy for this post, and everyone for the replies. My sharing email button still isn’t working, despite Tracy’s localization, or enqueuing using the sharing plugin constant Jeremy pointed out.
But most importantly, Tracy’s main point is still very strong, Jetpack’s architecture and scope are basically misconceived and counter-productive. The project could be re-aligned in a way that is less centralized and totalized, and more progressive and elective, like the WordPress community itself.
If Automattic wants to make a plugin that installs a core list of high-quality, vetted plugins, great – it’s a very good idea. But the very idea of my having to sign in to wordpress.com to get infinite scroll or Sharedaddy is absurd and a little offensive. Sorry! it is. Not to mention the fact that Jetpack is just too fat, I’d never choose to install the whole thing. Thank goodness people have broken the modules back out.
However, the idea of Jetpack as an installer for a list of Automattic-vetted plugins is very appealing. That’s what I think Jetpack should become.