Fun Challenges With Recent Caldera Forms Updates

Josh Pollock - November 15, 2016

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.