Some Quick Thoughts On LoopConf

I was super lucky to be able to attend LoopConf last week. Ryan Sullivan and his team put on an amazing conference. I’ve never been to a fancy developer conference before, and I had a blast. Thanks Ryan for having me! I just wanted to share a few observations about what made LoopConf special and share my recommended videos playlist.

Before I go on, I should point out that while I don’t usually stay in hotels when I travel — I prefer AirBnB –Me and Roy Sivan being super classy by hotel fireplace– the Little America hotel in Salt Lake City where they put us up was classy AF. I didn’t know what to do with myself in such a big fancy room, but I super enjoyed sitting by the fire in the lobby and being classy.

One side of the fireplace had statues of dogs. The other side had a painting of wolves howling in the snow. Apex Classy.

Our REST API Workshop And Something New

Caldera Learn BannerRoy Sivan and I gave a 6 hour workshop on using AngularJS and the WordPress REST API. Honestly, we were worried we couldn’t fill 6 hours, but we actually ran out of time at the end. We had almost 40 attendees and people seemed to get a lot out of it.

I have embedded our slides below, and we also put all of the example code to Github. There is a ton of practical examples in there, some not finished to provide a start point for your own work. Some examples are running live on CalderaForms.com right now.

If you’re wishing you could attend an in depth workshop about the REST API from Roy and I too, don’t worry. We recently announced Caldera Learn. This new site will offer live webinars, recorded courses and code communities for anyone looking to level up their WordPress development skillset. It’s going to be awesome.

The Main Event

Photo by:  Anna Anikina

Our workshop was the day before the main event. LoopConf was a single track conference with excellent talks. They also did a great job of accommodating the hallway track. The room that meals were served in was open all day with the live stream playing. This was a great way to network and watch the talks. I wish WordCamps would do this.

The talks were a lot more focused on philosophy of code, then code. Not that there were not code examples. I really liked this trend for non-workshops.

For example, KAdam White talked about why the WordPress REST API was important for JavaScript developers and why he built his node.js client for the REST API, before showing code for a React app using both tools. Similarly, Natalie MacLees and Nathan Tyler shared their experiences learning React. They provided tons of React and general JavaScript resources in context of using the WordPress REST API.

John Jacoby Jones (JJJ) didn’t really show any code at all. Instead, he talked about lessons from Unix Philosophy that could be applied to WordPress. Andrew Norcross talked about improving our community by acknowledging and dealing with unacceptable conduct that happens in our community.

All the nerdy talks on how to code something or why to code something a certain way were book-ended by business-focused keynotes. Josh Koening of Pantheon talked about how the web has trended away from open source recently as companies have packaged what we created for the open web  in better experiences. He made an excellent point that most people can’t afford what free software costs — time and education.

Jason Cohen of WPEngine spoke about building a bootstrapped business. While he talked about pricing and product design, the best part of his talk was about managing yourself. This especially rang true for me when he talked about focusing on 2xing revenue over shiny features.

I’ve been working on both, and beating myself up over not delivering all the shiny new features I want for Caldera Forms. Those would be done if I wasn’t also working on a new tool that we’re testing right now. Then again, February is looking like a 1.5-2x growth for us versus January, so yah.

I really appreciated both of their talks and spending time talking with both Jason and Josh during the event. I was imagining LoopConf would be all out nerdy-codefest with out a ton of networking. But I got both.

Next Generation WordPress

Photo by: Alexey TopolyanskiyIn 2014 I went to WordCamp Milwaukee and saw two talks on the future of WordPress. Ryan McCue and Rachel Backer presented the beta of the WordPress REST API and Andrew Nacin talked about the WordPress REST API and the WordPress fields API being the basis for a modernized WordPress.

I was super-excited for the vision they shared, and got on the REST API bandwagon pretty hard. Of course, things turned out a bit differently then we expected then. At LoopConf Ryan gave a talk called “Next Generation WordPress”.

He talked about going from the blog era of WordPress, to the CMS era of WordPress and now the platform era of WordPress. Echoing what Matt Mullenweg said in the State of the Word about what got us here is not going to get us where we are going, Ryan suggested a new direction.

While State of The Word was all about user experience, Ryan talked about developer experience. I loved this obviously, as there is a reason I prefer to develop most things in Laravel than in WordPress these days — the developer experience — there has to be a balance here.

WordPress is a user-centered platform and that should never change. But, for users to get an improved experience, both from core as well as plugins and bespoke sites, we need to make it easier for developers to fit those needs. Ryan is, per usual a man with a plan. Definitely watch his talk, do what you can to contribute and let’s hope he gets a reasonable fraction of what he’s asking for there.

Vegan Food, Also Videos

I didn’t expect their to be such excellent vegan food in Salt Lake City, but I was impressed. If you’re ever in Salt Lake City, which I recommend strongly, check out The Vertical Dinner.

I’m still working my way through videos of talks I missed, but I created a highlights playlist from both LoopConfs for you. Check it out:

 

Fun Challenges With Recent Caldera Forms Updates

cropped-CalderaWP_Icon_512x5121.pngLast week, we release a new version of Caldera Forms and a new form translations add-on for Caldera Forms. These were both fun projects to work on and I wanted to share a more technical overview of some of what I did on those projects than I gave in the official release post.

I hope this post is interesting and useful to all WordPress developers, whether you are a Caldera Forms user or not. But if you’re not, maybe it’s time to try it 🙂

https://calderawp.com/2016/11/caldera-forms-translations-and-more/

 

Caldera Forms Translations

Photo by: Ben MoorePreviously, When using Caldera Forms or most other form builders on a multi-lingual site, you had to have to create multiple forms, one per language. That is a pain to manage. Making one change meant editing multiple forms.

Caldera Forms Translations is our new translations add-on. One forms, many languages. I originally was planning this as a feature of the core plugin since we didn’t want to make it a paid add-on. That said, figuring out if a form has translations, then if each field has a translation, and then if that translation is in the right language introduces a bit of overhead to form rendering.

It’s not that much, and its worth the trade-off in exchange for the functionality. But this is one of those features that is great for certain users and not worth it for many, so an add-on makes perfect sense.

The interface for this plugin was a lot of fun to build. It’s actually the first time that we’re using the new Caldera Forms REST API. I will be blogging more about the challenges of implementing the WordPress REST API in a legacy project soon.

I actually did the first pass at this plugin using admin-ajax. I thought it was just going to be one ajax action I need for the admin UI. Turned out I needed three.

You can see the commit where I deleted those callbacks here. But I can best summarize how messy things become validating and authenticating these type of HTTP requests get with this:

if( cf_translate_can_translate() ){
        if( ! empty( $_POST[ 'language' ] ) &&  ! empty( $_POST[ 'form_id' ] ) && ! empty( $_POST[ 'fields' ] ) && is_array(  $_POST[ 'fields' ] ) && ! empty( $_POST[ CF_Translate_AdminForm::nonce_field_name() ] ) ){
            if( CF_Translate_AdminForm::verify_nonce( $_POST[ CF_Translate_AdminForm::nonce_field_name() ] ) ){

That’s terrible and doesn’t even get into sanitization. I think it was the third time I had to refactor that when I decided to add the Caldera Forms REST API infrastructure to Caldera Forms 1.4.4. Previously I had infrastructure and some implementation on the 1.5.0 milestone.
The REST API routes for this plugin has three endpoints. One is for saving settings. The other two are for adding and saving languages.

This add-on supports more than a hundred languages. I don’t want each field to by default to support all of those languages. So, in the UI, there is a selector for languages and an add button. This makes an API call to get the field data, and insert it into the local variable that tracks the languages of the form.

The JavaScript for this interface is a bit experimental and doesn’t use our normal UI framework. I’m playing with new ways to build UI. This add-on was an experiment in using a more structured system. I ended up with a pretty modular system that separates each part of the UI into its own closure. That’s good, because I will probably replace each part one at a time as I continue to use this add-on for experimenting with UI systems and figure out which JavaScript framework we will use in the future.

I will admit that some of this modularity was a bit of overkill and I definitely broke some of my self-imposed rules in order to finish it. Still, I think it would take minimal refactoring to pull one part of the system out if I wanted to replace it with something else, or reuse it elsewhere. Also, it works, which is the point.

One thing I am very happy with is how the class that handles translating fields during rendering works. You can read the source here. This class is a good example of using dependency injection — it takes the form configuration through its parent’s constructor — and using inheritance to create a reusable system. Its parent class is a system for conditionally adding a filter. I might add a similar system to Caldera Forms itself, I’m not sure yet.

Caldera Forms 1.4.4

Photo by: petradr

The new version of Caldera Forms is mainly a bug fix release, with a few enhancements. Most of the bug fixes were to resolve accessibility issues, as we continue to work towards our goal of being the most accessible WordPress form builder. Mainly the new improvements are infrastructure for add-ons and custom development. The REST API infrastructure will get its own post soon.

The biggest improvement in this new version is how file and advanced file fields handle uploads. One of the trickiest thing about building a form builder is dealing with the fact that most form submissions use more than one HTTP request. A validation error means another request may be made. Also, our advanced file field uploads multiple files via multiple AJAX requests and then the main submission happens.

As a result, when the main submission is being processed for a form with an advanced file field the $_FILES super global is empty. These fields allow for saving files to the media library and/ or attaching the files to an email.

If both options are selected, that’s easy. We upload the file to the uploads directory, add it to the media library and then attach that file to the email. When the file needs to be attached to the email, but not saved to the media library, that’s where it gets tricky. The file needs to be saved to the server so it can presit between sessions, but users are right to expect the files to not stay there forever. That creates a privacy issue and disk space usage issue.

My solution for this scenario, which is based on a conversation I had with Micah Wood when we had dinner last time I was in Atlanta, was mainly written in my my car as my wife and I drove back from Atlanta. I introduced a new class to Caldera Forms for handling file saving and implemented it in the existing callback for file fields.

This new class manages files on the server and introduces a concept of a private file. Private files are stored in an almost randomly named sub directory of the uploads directory and deleted later. That dub-directory names is named using a hash that can be created predictably, but only by the server, not an outside observer. As a result I can find the directory later and delete it.

Choosing when to delete that file is also a challenge. It should be deleted after form submission, but it needs to be available when the email is sent, though that email may be disabled. In addition, I had to account for files uploaded to form submissions that failed validation, and were never completed.

So, I wrote two ways to delete it. The first was to set a single CRON to delete the file(s). If form submission is successful, the files will be deleted by the time it runs, but its a good fallback. The other method hooks in at the last action that would be run if no email is set. It checks if the email should be sent. If not, it deletes the files. If an email should be sent, it adds a hook to run after the email is sent, to run basically the same callback.

Read The Source Luke

I hope you found this article useful and that you dig into the source code I’ve shown. Reading the source is the best way to learn.

Writing articles like this is something I’d like to do more of because most of my articles on development are a bit divorced from the real world. That’s fine, I’m teaching a principle most of the time and contrived examples are needed.

The real world is a lot messier than a tutorial. Improving a large code base and fixing bugs without breaking more than 30,000 websites running that code is a challenge. It’s a lot of fun, and its a great way to learn.

 

WordPress Authentication (over) Concerns: A Quick Case Study

A big push back against the WordPress REST API has been a feeling that a lack of authentication system makes these endpoints not useful. This is strange to me, since the content endpoints use the exact same permissions system as the rest of WordPress.

I think a lot of this confusion comes from the excitement about building cool apps that connect from outside of WordPress via the REST API. In those cases, WordPress’ cookie-based authentication does not work. Therefore a different solution is needed. oAuth1, oAuth2, JWT, a custom system, etc.

I like JWT a lot by the way in those scenarios. This plugin makes it very easy.

But what about when we are using the REST API to improve WordPress from inside of a WordPress theme or plugin? Or what if — presuming the content endpoints make it into WordPress 4.7?

In those cases, cookie-based authentication, which is super easy to use, is all we need. This is especially exciting for core. I’d love to see the REST API used for content editing in the front-end and/ or the customizer. Also, what about new ways we could work with terms or custom fields in the post editor, or combine editors for multiple content types, or build dynamic list tables?

Today I made up a quick prototype of a front-end revisions browser for posts. It took me about an hour, and most of that time was spent figuring out how revision endpoints worked — I had never used them before — and working through a bug in the REST API that was quickly resolved.

I’d like to briefly show you how it works, and discuss using cookie authentication, as well as why that was the best choice.

If you want, you can check out the code here. Also, if you want to learn more about authentication using the REST API, I have a section of my REST API course that covers this topic.

Photo by: Philipp Reiner

Why Use Cookie Authentication?

The first question is why use cookie-based authentication for this type of problem. The short answer is “why not?” I mean, why does having a REST API in WordPress mean that we have to suddenly start using a second authentication system? We don’t do that with admin-ajax?

The REST API does force us to use a nonce, in a way that admin-ajax does not, which complicates this by 2-5 lines of code. If only admin-ajax had been designed the same way, we probably could have skipped a few thousand XSS and CSFR vulnerabilities in plugins and themes.

How Does Cookie Authentication Work?

Cookie authentication works exactly the same way as it does in any other WordPress request, which is to say pretty much automatically, if we send the right nonce. That nonce, which must be created using the wp_rest action, can be sent as a header or as part of the query in a GET request or the body of a post request.

In the plugin I built as a proof of concept for the revision browser, I localized the URL for the current post’s revisions endpoint, and included the _wpnonce query argument, like this:

	$api = add_query_arg( array(
		'_wpnonce' => wp_create_nonce( 'wp_rest' ),
		'context' => 'view'
	), rest_url( sprintf( 'wp/v2/posts/%d/revisions', $post->ID ) )  );
	wp_localize_script( 'revision-browser', 'REVBROWSER', [
		'api' => esc_url( $api ),
		'nonce' => wp_create_nonce( 'wp_rest' ),
		'content' => $selectors[ 'content' ],
		'title' => $selectors[ 'title' ],
		'links' => $links
	]);

That’s pretty simple. Another approach would have been to put nonce as a key in the REVBROWSER object I was localizing. Then I would have had to add a header to my request. To make that work I would change my AJAX request from this:

$.get( REVBROWSER.api ).success( function( r ){ ...

To something like this:

$.ajax( {
   url: REVBROWSER.api,
   method: 'GET',
   beforeSend: function ( xhr ) {
      xhr.setRequestHeader( 'X-WP-Nonce', REVBROWSER.nonce );
   },

} ).success( function( r ){ ...

Either way pretty simple and works perfectly with WordPress as-is. No one who isn’t authorized to view revisions can see these revisions.

What About admin-ajax?

I could do that with admin-ajax (image meme)This is the point where someone mentions that I could have used admin-ajax. That’s totally correct, but let’s talk about what I didn’t do when I built this, but would have had to with admin-ajax.

I didn’t write any new code to collect revisions and convert them to JSON. The content REST API does that for me. This kind of efficiency is why we use open source software.

I also didn’t worry about authentication, authorization or cross-site forgery. That’s handled by the core API for me. I could do all of that myself, and hopefully not mess it up. But I didn’t have to. The next person who does this might be not as picky about security issues as I am. When we off-load those concerns to core, we get help from all of the other people working on the project. This is why we use open source software.

And it’s important to say again that not everyone exposing private content or allowing updating of content via admin-ajax has added the right permissions and nonce checks. Our ecosystem has been harmed by the fallout of those mistakes. The WordPress REST API will not make developer-errors that cause security vulnerabilities go away, but it will help.

By the way I did this once before for Lasso using the custom API I built for that plugin. It took Nick and I a long time. What I built today, needs some UI work, but could, if there is a content API in WordPress core, be polished patch for WordPress core without much more work. I’d love to do that if possible.

Being Loved Isn’t Enough

My dog Josie begging in my kitchen.
This is my dog Josie.

One argument for the REST API’s inclusion in core is that so many people are excited about it. I think that is a decent argument. We need people to be excited and passionate about building cool stuff with WordPress.

But that’s not enough. Having a standard way of working with WordPress content via a REST API is about creating new tools for end-users while following a standard and working together on improving the tool we all love. That’s why we use open-source.

The Core Team Wants To Know What You Think

Earlier today, Helen Hou-Sandi, a lead developer of WordPress and the release lead for 4.7 asked a question on Twitter that led to a bit of a discussion and then this proof of concept.  There has been several posts on the WordPress core development blog asking for comments on the REST API merge proposal and invitations to discuss further in Slack.

That’s awesome. This is a big decisive for a big project and I love that those making the decisions are so open to a public discussion.

Get involved y’all.

 

Learn Modern WordPress Development With Me

Cherry Tree

Photo by: Maja PetricSomewhere, in a parallel universe, I’m teaching high school science in an under-served New York City public school. At the beginning of the journey that led me to becoming a WordPress developer, I turned down an opportunity to join the New York City Teaching Fellows.

This was 2010 and New York City was balancing its budget by slashing education funding. It was the wrong time to go into teaching, but I do sometimes regret not becoming a teacher.

But one of the things that the WordPress community has given me is the opportunity to teach. It’s something I love to do — writing about WordPress development, speaking at WordCamps and creating my REST API course — it’s all something I just can’t get enough of. I’m always looking for ways to teach more.

Plugin Development For Everyone

Photo by: veeterzyToday, I’m super excited to announce a new course “WordPress Plugin Development With The WordPress REST API.” This course is what you need to get started with modern WordPress development. It’s not just about the WordPress REST API, but obviously that’s a huge part of what I will teach.

This course is not just for people who want to develop plugins for release, but also, for those who want do site development. You will learn how to create quality, reusable code you can implement on one or more client sites.

strawberriesWe will be offering this course as a one day workshop and as an online video course. The first workshop will be held in Pittsburgh on September 16th, the day before WordCamp Pittsburgh. The second workshop will be held in Tallahassee in October, date to be announced soon.

The workshops will offer both lecture-style instruction and hands-on work time to apply what you have learned. The video course, which will be available later this year will include all of the example code from the course, so you can practice what you have learned or use that code as a jumping off point for something of your own.

What You Will Learn

This is me, at WordCamp San Diego using the force to summon an object to me in the middle of my talk. Photo by Joe McDonald.
Photo by Joe McDonald.

I’m going to teach how to use WordPress hooks — the WordPress plugins API — using real object-oriented PHP. That way you can develop plugins that can work in traditional WordPress themes, via the REST API or both. Then I will show how to build a custom REST API, using object-oriented PHP.

Then we will finish with what you need to know about JavaScript to build a great user-interface that interacts with the WordPress REST API.

I hope you see the progression here. Solid foundation for a REST API and other APIs to a REST API to an interface that uses the REST API. That is what I think is necessary for modern WordPress plugin development.

A Big Thank You

LoopConf Logo

This course’s super-awesome level sponsors are WPSiteCare and LoopConf. It would not be happening with out that support. I’d like to say a big thanks to Ryan Sullivan, the founder of WPSiteCare and LoopConf for believing in the value of this course and backing us.

This is an introductory course that’s designed to get you leveled up fast and ready to start tackling serious WordPress development projects. If you purchase a ticket for the workshop, or pre-order the videos before September 1st, you will receive a $100 discount for LoopConf — the premiere conference for WordPress developers.

Those who sign up for the course will also receive 15% off the WPSiteCare Annual Protect Plan, which offers encrypted backups, 24/7 malware scanning, fully managed plugin, theme, core WordPress updates and more.

I hope to see you at LoopConf this year, giving an advanced Workshop on WordPress development with the REST API and AngularJS. That workshop will be a great follow up to the one I’m announcing today.

Stronger Communities

Downtown PittsburghFor me, WordPress is about community. I just wandered into this, but as soon as I went to my first WordCamp and got involved with Pods, I knew this community was special.

I learned early the mantra of “Add Value” and I’ve done my best to live that mantra. I know I’ve benefited from it and that others have benefited from my contributions in education, code and more.

Unless you know where I grew up — Pittsburgh, PA — and where I live — Tallahassee, FL — the choice of Pittsburgh and Tallahassee for our in-person workshops may sound strange. But community begins at home.

When I made the goal to teach more this year, I wanted to make sure I was contributing to growing Tallahassee’s technology industry. It’s my hope to provide young people in Tallahassee the training needed to make a career in WordPress and help meet the demand in the WordPress community for developers that know “The WordPress Way.”

Tallahassee SkylineAnd yes, I’d like to do more of these workshops in other cities, contact me if you want to make that happen in your community. But, I’m starting at home.

These workshop is a step towards that, while creating new video content that anyone can purchase, no matter where in our global community they live.

So, to my friends in the WordPress community, I’m asking you to support this new course. Help me grow these communities. Your purchase of this course is an investment in your own future, because you or whoever you buy it for can learn from it, but also, so we can keep this awesome community vibrant and growing for years to come.

The WordPress REST API As Connector

Earlier this year I gave a talk on what having the WordPress REST API means. I actually gave the talk twice, once I. Jacksonville and once in San Diego and both times I started by asking why we needed a REST API.

Both times I asked, someone in the audience said that the WordPress REST API would help us display content from multiple sites in one location. I agreed.

Both times I asked, someone in the audience said that the WordPress REST API would help us decouple content management form the front-end. I agreed.

Tomorrow, I will be at WPCampus, a conference for WordPress in higher-ed and this is what I am talking about. I’m talking about using the WordPress REST API to show content from multiple sites is one central location.

I hope this will help solve problems for educational institutions with many sites, managed by different departments, that want to share that content throughout their online presence. But, these strategies will also help organizations of any type solve scaling issues.

In addition, companies with multiple brands can use these strategies to share content between different sites and different brands. In fact, half of this talk is based on code I wrote to solve that problem for my own company, Caldera Labs.

Each of our brands has its own WordPress site. Our central site is a static HTML site, hosted on Github for free. It loads in about half a second, and has no database. Instead, we pull content via the WordPress REST API, using jQuery AJAX from multiple sites.

Photo by: Jakub SejkoraThe WordPress REST API is changing ways we use WordPress and ways we consume WordPress data. I look forward to learning more about how others use this new technology and continuing to teach about how to use it as well as using it.

As I prepare for my 6th WordPress conference so far this year, I’m reminded that WordPress is a connector. Yes, the REST API provides a way to connect WordPress sites together and WordPress to other technologies. But, more importantly, WordPress can help us reach our goals when we have the right tools, and helps connect us to awesome people in the community 🙂

Slides

 

Links

 

Learning AngularJS For WordPress Development

At WordCamp Miami this year, I showed how and why, I use AngularJS for building WordPress plugin admin interfaces. For our A/B Testing plugin Ingot we chose to build our interface in Angular beacuse it was the fastest and best way to build an interface that had to be highly dynamic.

I gave two talks, one on Angular basics, and then the second one dove into my specific use case. With this information & with a knowledge of how to extend the WordPress REST API you should be able to start creating new & exciting WordPress user experiences.

It was awesome to be a part of a day full of developers explaining why they made their choice in framework. I hope this type of sharing will lead people away from “What framework should I use?” to understanding the strengths and weaknesses of each framework and make that decision on a per project basis.

In Ingot, Angular is a thin UI layer on top of what is mainly a PHP codebase. I needed a really solid AJAX interface — sorry jQuery — that would allow the interface to have lots of different UI states easily available. Angular provides that.

I want to add that while the focus of these talks was Angular, building this way, in my opinion, requires an API-first approach to the PHP code. I wrote extensively about this before. The short version is that it requires keeping the code required for reading and writing to the database totally decoupled from the front-end use, and API code.

How The WordPress REST API Changes WordPress Plugin Development

This approach also requires having your own REST API endpoints. That part of the stack I covered in a talk I gave several times last year, in chapter 8 of my book and part 3 of my course.

http://learn.joshpress.net/downloads/customizing-wordpress-rest-api/

Slides

Video

 

Example Code

Learn More

Learn The WordPress REST API With Me :)

Josh Pollock WordPress REST API Course

The future of WordPress is the WordPress REST API. The future is here — it’s just not evenly distributed. The WordPress REST API is slowly maturing into a new and exciting tool, but it requires learning a whole lot of new skills and patterns.

I’ve had a blast writing and talking about what you can do with the REST API. In addition I’ve had the pleasure of presenting about the REST API at WordCamps all over the country. More importantly I’ve been putting it to use in my own work.

Today, I am releasing a four part video course about the REST API, with 17 videos in total. The premise of this course is that with the REST API, you can exceed expectations of what your users and clients expect from WordPress.

I genuinely believe that the WordPress REST API — once you master it — will allow you to deliver better more exciting, scalable and manageable results. It’s a new skill you need to learn, but it’s worth it. Don’t forget once you’re exceeding the standard of what people expect  that you start charging more.

Also, I made a 4 part video course about the WordPress REST API, that is available for sale today. Each of the four parts is a series of You can purchase the whole thing for $100, or each individual part of the course for $30 each.

You can learn more about the course, or download it on my shiny new “Learn with Josh” site. Expect to see more fun ways to learn WordPress development there, later this year.

BTW If you pre-ordered the course, check your email 🙂

What’s The Status Of The REST API?

Photo by:  Paula BorowskaPaula BorowskaAdding a REST API into a traditional web application, that was never intended to be API-first is no easy task. It’s going to take time and have ups and downs along the way. WordPress is all about progressive iteration and improvement.

The WordPress REST API is two parts. The first is infrastructure for creating RESTful APIs. The second is a set of default routes and endpoints for WordPress core functionality that uses that infrastructure. The infrastructure for the REST API was merged in to core WordPress 4.4. The second part was supposed to be merged into 4.5.

Unfortunately the second parts — the defaults — will not be included in WordPress 4.5. This does not mean that the REST API project is dead. The REST API team felt that everything besides the meta routes were ready to go, and proposed they be placed in a separate feature plugin, with the rest of the current feature plugin be merged. This proposal was not accepted.

The current issues that are considered blockers for the REST API are not huge. I would assume, but can not be certain, that the 4 routes — posts, users, comments and terms, with meta support for each — will be included in WordPress 4.6. In the meantime, the REST API plugin is still available for you to use.

The bright side, is that the plugin and the documentation are still being developed on Github, so it is easy for you to get involved with improving the plugin or the docs. If you’ve read my book, and watched the videos in my course, you are more than qualified to contribute to the docs.

Your Turn To Share

Photo by:  Maja PetricI first got excited about the REST API when I met Ryan and Rachel at WordCamp Milwaukee in 2014 and saw their presentation on the project. I went home both excited and worried. I knew this was the future of WordPress, if anyone could figure out how to use it.

So I wrote a bunch of articles for Torque, and gave some WordCamp talks, and wrote a free book, and now I’ve released this course. I love that I’ve been able to do all of that. If you’ve been following along and putting what you’ve learned to use, than you have something to share.
Free software is about the power of sharing what you’ve learned. The WordPress REST API is awesome. Some really awesome people put a lot of hard work into making it possible. Let’s pay it forward by sharing what we’ve learned about it.

How The WordPress REST API Changes WordPress Plugin Development

Over the last few months I’ve been working on creating a totally self-contained WordPress A/B testing plugin. It’s called Ingot, and we released version 1 right after christmas.

Since I did almost all of the development myself from scratch I was able to do it all “the Josh way” and refine what that even means. This allowed me to put a lot of my opinions on WordPress development to the test. I shared a lot of what I learned in yesterday’s post.

Lessons Learned Coding A Big, New WordPress Plugin

Ingot was in many ways written around around the REST API. The custom endpoints we built are used for the Angular app that Roy Sivan and I created for the admin screen. It’s also used in a very small front-end JavaScript file for tracking conversions, failed conversions and cache busting.

Today, I wanted to follow up yesterday’s post with what I think it means to create a WordPress plugin using the REST API. Next week, I’ll talk about the business and product design lessons I learned from Ingot. The design decisions that went into building the Ingot REST API will be a big part of that discussion.

How Things Change

As most people reading this know, I spent a lot of time over the last year or so thinking about how the WordPress REST API will change how we build WordPress plugins, themes and apps. I think this change is big and has to do with how the use of WordPress is changing.

WordPress didn’t get to 25% market share on blogs and it’s not going to get to 50% or whatever that way. The growth comes from eCommerce, publishing, membership sites, inbound marketers etc. These are all users that can benefit from being service providers.

Photo by: Jeff SheldonI think that those of us who empower these users by giving them the tool need to make their sites have to think API first. Your plugin’s interaction with the client is going to be more and more coming through the API.

That doesn’t mean WordPress plugins are suddenly all JavaScript magically. Your custom REST API routes are PHP code that you write around the rest of your plugin.

If the code they wrap must be solid and sufficiently decoupled from input method — if you call GET or POST in your CRUD still you’re not going to make this transition.

The hype around the WordPress REST api has been about the default routes and that might be exciting to you if you do front-end work. But the real potential in my mind is that your plugins can be repurposed SAAS service more easily and that your users can become service providers themselves.

The Developer End User


Photo by: Sonja LangfordToo often, when creating a plugin that is designed to be simple to use and not require technical knowledge, we forge that there are still developers as end-users. Keeping developer end-users happy is super important as they are often decision makers that choose whether or not their client uses your product or not. They are also likely, if happy, to become evangelist for your project.

The ability for developer end users to be able to customize and integrate with your plugin via your REST API as an alternative to learning the WordPress hook system is a big deal. It opens more doors and more opportunities. It means more integrations, more contributions and more potential developer evangelists.

Angular + REST API

I originally thought I would use the plugin generator that David and I use for CalderaWP plugins. I couldn’t make it work with the original DB structure I had. The first Ingot demo used a really bad UI I hacked together. I wrote a ton of PHP code full of admin-ajax callbacks and functions hooked to init in order to check for incoming form submissions. By all objective standards, it sucked.

So, I taught myself AngularJS.

Since I was trying starting at a Jon Snow-level understanding of AngularJS, I was bugging Roy Sivan for help a lot. Roy ended up doing a lot of the heavy lifting for me and now pretty much owns the Ingot UI. That’s awesome because I don’t like UI work and he’s better than me.


Photo by: Jonas NilssonBut, I did learn a ton about Angular. What I learned enabled me to write all the example code for the last section of my WordPress REST API course — Angular front-end for WordPress sites. I really like Angular and the angular-ui router. It’s a really great way to work. It almost makes me wish I made WordPress sites so I could make them with Angular.

Our admin doesn’t look very WordPress. It’s a very standard Bootstrap, which is a common pattern that I hope people are used to using. I would love to get a WordPress admin Bootstrap theme made soon though.

I’ve spent a lot of time in the past trying to force the MV* pattern on WordPress, which is insane for a lot of reasons. Using the WordPress REST API to provide data to Symfony or Angular is really great, and fairly simple.

A WordPress plugin, like any product is only as good as its interface. I’m convinced that working with Angular and custom WordPress REST API endpoints was the right decision in terms of UI/UX. It also means we have a solid REST API to use if we make an Ingot SAAS product or if end users want to use it.

This Is The New Way

At this point, I don’t think it makes sense to build a plugin without its own set of API endpoints. Doing so requires a PHP CRUD that is sufficiently decoupled from input to work seamlessly with the API. Writing your plugin knowing you will use the REST API makes dependency injection in your class design a necessity.

That’s going to be an issue for a lot of older plugins, and the backwards compatibility challenge is also there. I think it is worth the rewrite though, if this is an issue. This will make your plugin more easy to unit test, which is a great bonus.


Photo by: Jerry AdneyOlder plugins also have to deal with backwards compatibility concerns. Ingot requires WordPress 4.4 or later. It’s a new plugin so we don’t have a user base to worry about alienating. It’s a concern for me in my existing plugins, and we will see how that plays out as I modernize them to work around the REST API.

I will, because I think that plugins that do not embrace this new way risk being left behind. For new plugins, the REST API-first approach makes sense. It leads to better admin experiences, easier interfaces and allows your plugin to more easily become a part of  a stack that is not totally built in WordPress.

 

Lessons Learned Coding A Big, New WordPress Plugin

Over the last few months I’ve put a lot of time into writing Ingot — an automated A/B testing and conversion optimization plugin for WordPress. Because Josh, I did a lot of other things at the same time — but Ingot was my biggest project.

Ingot is probably the biggest plugins, in terms of lines of PHP code, that I wrote. I’ve worked on bigger plugins, but never as the primary developer. Pods and Caldera Forms are bigger, but my contributions code-wise to those are not huge.

For Ingot I wrote all of the PHP code. Roy Sivan helped me build the admin interface, which is an Angular app. He was also a valuable sounding board and bug catcher for the rest of the plugin.

I wanted to share some of the lessons I learned, as a developer, writing a big plugin. Writing this plugin from scratch allowed me to put to test a lot of my personal opinions on WordPress development. I’m going to follow this article with one specifically about coding a plugin around the WordPress REST API and another with some lessons I learned as an entrepreneur from the process.

ingot-logo

Separations of Concerns

Working with the WordPress REST API helps encourage separation of concerns because of the way defining routes breaks up the process of preparing, processing and responding to requests. In addition, knowing that some of your CRUD will happen via your REST API, but not means you either have to wrap your API callbacks around a standard set of CRUD classes, or you need to keep two ways of reading/ writing/ validating and sanitizing data in sync.

The latter of those two options is insane. I went for the first. Ingot has a CRUD class for each of the different data types — test groups, variants, sessions, click tracking, settings — each of which extends a base class. Having separate CRUD class keeps the validation, sanitization and DB writing separated from every place that CRUD is ever used, including the REST API routes, and objects that represent groups or tests.

This also led to having one class to handle read/writes and  establish a pattern for using CRUD, along with smaller extending classes to define what fields are needed. I liked working this way. Even though these classes are likely to be called multiple times, I used all static methods for them. Yes, there are objects for single groups, tests and sessions that are often needed, but CRUD is just a collection of functions and without any application for an iterator, having to instantiate multiple objects of these classes wouldn’t have provided any utility.

I think of these classes much like how WordPress core’s WPDB class, which might as well be all static methods since we always use one instance, relates to WP_Query. We use WPDB to inject post collections into specific WP_Query objects that we can then iterate over.

The way I worked wouldn’t have been doable without late static bindings. In non-static methods, $this refers to the current object. So if the class is extended, $this is the object of the extending class. The self keyword doesn’t work that way. self in the parent class refers to the parent class, not the subclass extending this.

On the long list of reasons why I didn’t hamstring myself with conventions of a language that is almost 8 years out of date (PHP 5.2) is late static bindings. Late static bindings allow for static inheritance. The keyword static functions like self, except it can refer to a subclass method or property if one exists.

One thing I’m really proud of in Ingot is that I stuck to very small classes. For example, I have a class that creates a conversion rates stats object. This is separate from the class that creates an object for stats for all of the variants in the group, which is a collection of the objects of my conversion rates stats class. This creates re-usable code — the conversion rate class is used for variant and group stats, easier testing, and avoids code reuse.

Small, reusable classes are not just neater and more testable, they make refactoring easier. I rewrote about half of Ingot in the week before release. Short story — CRUD was overcomplicated and the testing algorithm was going to require tons of traffic, which would be a problem for a big part of our target audience. That’s a different discussion, but my point for today is that small classes meant more saved code during that refactor since it was very easy to separate the parts that still had a job from those that didn’t.

This is a concern moving forward. I am considering whether it makes sense to break the plugin into smaller Composer packages that I can assemble into different, smaller, task specific versions. Doing so could also allow for implementing a CRUD system that uses the posts and postmeta table instead of custom tables.

Composer & Dependency Management

Photo by: Steven SpassovI used Composer for dependency management and providing a psr-4 autoload. There is a ton of blog posts out there on why I love Composer and dependency management in general. The PSR-4 autoloader forces a directory and class naming structure on the plugin that makes it highly organized. Between that logical organization and being meticulous about inline docs, I think the code is easy to follow. We will see as other developers get into it.

I did hit some stumbling blocks with dependency management. I used Composer’s file map for including PHP files that are not classes, which I found to be annoying. Classes are added automatically to the autoloader, since it is based on logic. File and class maps are static lists of files and adding to them requires a composer update, which I didn’t always alert Roy to, causing unneeded errors on his end. It also makes switching Git branches a pain.

I chose to use Bower for managing JavaScript and CSS dependencies. Bower is a pretty slick tool, but ZIP file for the first beta version after I started using Bower was 2 or 3 times the size of the previous version. This was because I was enqueuing the scripts from bower_componets.

My solution was to use bower-installer to copy all of the main files — IE the ones I needed — to a separate directory. This allowed me to exclude bower_components and all the extra stuff from the final zip.

I went on a bit of a quest to reduce the file size of the zip files I was creating for releases. Another big win was setting this command in my build script:

composer update --no-dev --optimize-autoloader --prefer-dist 

This pulls in the Composer dependencies without their Git repos, or unit tests and optimizes the autoloader. Even with just a few dependencies, the file savings were pretty nice — about 6GB. Git repos are big.

Since the plugin is in a public Git repository I don’t think removing all this extra stuff that most end users don’t need does anyone a disservice or reduces their rights to modify the software. If an end user is a developer and needs the whole package, they can get it on Github.

I actually used very minimal third-party dependencies. But my testing library, the one I switched to later on, started out as a third party dependency. The library I used was built to use Redis to store data. So, at the least I needed to add a way to store data using my CRUD system.

Photo by: Marta PawlikAt first I kept the testing library checked out from the original source — and that author merged my pull request to fix a bug I found. In order to facilitate this I kept my class to save data using my CRUD in Ingot instead of in the library.


As I found more places where my usage of that library wasn’t fitting well with the original design, I had to make more changes that didn’t make sense as pull requests. So, I started using my own fork and making changes directly there.

I will soon evaluate if my fork makes sense on its own, as a version of the original that stands on its own and is useful to have as a separate project or if it needs to be absorbed into Ingot fully. Either way, being willing to dive into a dependency, learn it, and modify was the difference between throwing it out and having to do another huge refactor and being able to ship the plugin on time(ish).

Iteration vs Throwing Shit Out

Photo by: Rick WaaldersI had a lot of fun with this plugin. Working on something that doesn’t have any users yet is really nice. Once a project is released backwards compatibility and stability are concerns. When you’re iterating on something pre-release, you get to break stuff and start over.

It’s funny how quickly I can fall into the “fix it, don’t break it” mode out of habit that comes with maintaining plugins with lots of active users or contributing to WordPress. I literally had to tell myself a few times “don’t work around that bad design decision, you wrote it yesterday.”

As I said before, I re-did the base A/B testing algorithm pretty late in the process. This led to re-doing a lot of the CRUD and re-working the REST API and a lot of other parts of the plugin.

The lean startup mindset dictates the idea of getting to a minimal viable product quickly and improving it from there. WordPress preaches the idea of continual iteration. I agree with these mindsets and think that they work together well.

That said, neither of them can be an excuse for putting out something bad. When I started on Ingot I create a minimal viable A/B testing algorithm assuming I’d get it right — statistically speaking later — once I had everything else working.

stained-glass-110788_1280This made sense to me, and once I had everything else working I sat down to write the code to do the math. I could have done it and I wrote a lot of it, but I realized that my approach was wrong. Not only that, I was adding it on top of some mistakes I made in the structure of my CRUD — separating price testing from content testing.

So, I spent “two days” throwing out half of the plugin and starting over. It was painful to throw out that much code — OK, I enjoyed it because Josh — but I’m glad that I corrected my mistakes before version 1.

There are somethings you can only do right, by doing them once in a way that is sub-optimal. Knowing when to throw out tons of code that works, has unit tests and documentation is hard. It’s not worth doing when it’s because you could have made the code cooler.

End-users don’t care about how fancy the code is, they care about results and they care if you can keep it working over time. Refactoring in order to meet your product design goals better, and to ensure your code will be more easily maintained over time is worth it.

Give It A Read

A yellow flower in out-stretched hands.I hope you learned something from this post. I’ve resisted the urge to put in big code examples, as I wanted to keep it abstract. That said, you should feel free to read the source code. I’m happy to discuss these decisions I made, or how you can integrate with Ingot. Leave a comment or tweet at me.

Tomorrow I’ll post my feelings on what the WordPress REST API means for plugin development moving forward. It’s obviously something I’ve thought a lot about and putting my own theories into practice was one of the most valuable parts of this whole experience.

How The WordPress REST API Changes WordPress Plugin Development

 

Learn The WordPress REST API With Me

API Wapuu by Michelle Schulp.
API Wapuu by Michelle Schulp.

I’ve had so much fun teaching myself the WordPress REST API for the last year or so. Part of what has made the experience so great is sharing what I’ve learned a long the way — tutorials, WordCamp talks, Podcast appearances, a free ebook.

I can’t decide what I love more — using the REST API to build custom APIs the WordPress way or sharing what I’ve learned. So, I’ll just keep doing both.

That’s why I’m happy to announce I’m working on a four part video course, teaching you how to use the WordPress REST API.

The REST API Is The Future Of WordPress

Actually, it is already in use by those doing the coolest stuff with WordPress.

Infographic on how awesome the WordPress REST API isWordPress just hit 25% market share among content management systems. That’s awesome, the more growth in our industry the more potential customers or clients there are for people like you and me who offer WordPress services and products. We know that there are a lot of negative opinions about WordPress out there. Some of them are fair, some of them are not.

The more times we can exceed the pre-conceived opinions about WordPress, deliver more “You can do that with WordPress?” moments, the more our industry will grow. I want you to be the one to deliver that “wow” moment to your clients. I want you to be able to give more to your clients than they expect from a WordPress site. Don’t forget to raise your rates 🙂

But Wait There Is More!

And more!!

The course will be available in December 2015. But if you sign up today you will get a special discount. Don’t delay — once the course is ready for download, the price goes back up.

Want to learn the REST API one on one with me? I’ve got a special bundle that includes the course and a one on one consult call via Skype or Hangouts.