Using Awesome Forms for WordPress

Awesome studio framework for WordPress provides two ways of working with Awesome Forms in WordPress and they both submit the form data using Ajax.

  1. Awesome JS forms, if you just need to capture the form data to a single CPT. It is the easiest way to handle a form.
  2. Advanced forms, when you need to capture the data into multiple CPT’s as well as send mails, or integrate with 3rd Party APIs.

Using Awesome JS form

awesome-form-js-lib

For first option of using awesome forms, you need to install ‘Awesome Forms JS Library‘ part from awesome studio parts catalog.

Once you have installed this part you will have a module ‘awesome form handler’ and a hook ‘Awesome Form’.

Now you are ready to create your forms. For creating them you have two options, if you know HTML you can write your own form, or you can use drag and drop form builders like http://getfuelux.com/formbuilder.html.

We did not provide our own drag n drop form builder because they put way to many limitations on how you can layout your form fields, which is a big turnoff for us.

For our tutorial we are going to use following form code

Our Awesome Form JS library, needs following conventions to be followed when creating the form.

  • Form tag must contain ‘js-awesome-form‘ class as shown in the line 3 above. It is required to indicate and activate our awesome form library.
  • Once form is submitted, to show any thank you message etc. you can have a div tag with  class ‘js-awesome-form-message‘ as shown in line 5 above.
  • All other form fields needs to have one of classes ‘js-post-field‘,’js-meta-field‘,’js-taxonomy-field‘ to indicate our JavaScript library that only these fields needs to be considered. see line 7,15
  • All the input fields should have their names indicating, where the data from that field will be saved, i.e. will it be part for post, or meta or taxonomy.
  • We need to indicate which custom post type this form must submit it’s data in, you can do so by using a hidden filed as shown in line 7-10, and giving the name of the field as ‘post_type‘, and value as custom post type slug where you want to save the data, in our case it is’enquiry‘.
  • Also, while not shown in this form, if you put a filed named ‘post_status’ you can specify the value ‘published‘ or ‘draft‘. So when this form is submitted the data will be saved as value specified in post_status, if it is missing it defaults to ‘draft’.
  • By using ‘js-meta-field‘ class, name of the field will become the meta key, and value will become meta value of the post.
  • By using ‘js-taxonomy-field‘ class, name will be slug of taxonomy and the value will become the term to set for that taxonomy.
  • By using ‘js-post-field‘ class, name of the field can be any of the post fields like post_name, post_title, post_content etc.

Once form is setup with these things in mind, your data will get saved without you having to write any form handler code.

Advanced Form

If you want more flexibility within your WordPress forms, so that you can split the form data between various  custom post types, taxonomies, send that data to 3rd party services like mailchimp or email then you need to use this method of using Awesome Forms for WordPress.

It has two steps

  • Creating and setting up the form
  • Writing form handler

Setting up the from

Here is the sample HTML form that we have created for this demo

Your form need to follow the convention as shown in line 9 and 19, so the form field name needs to follow the convention as ‘post-type-slug|post/meta/tax|field-name‘.

So in our example at line number 9, ‘enquiry|post|post_title‘, post type is enquiry, this field needs to be saved as post_title of the post, and for line number 19, the field will be saved as meta key ’email’ for the post type enquiry, in this way you can indicate which field goes where, when form is submitted.

Finally, the magic that enables this form is at line number 63, aw2_spa which is required, for this form to submit data. The spa_activity has to be core:form_submit, we have to specify when the form would be submitted, and also slug which indicates the module that will be used to handle the submission of this form data.

Our form is now setup and we are ready for next step, of handling the form

Writing form handler

Below we have a sample form handler module code, and to continue with our example form above, we have named the module as ‘contact-form-submit‘.

Inside form handler you can do whatever you want, as you can see, from the code above, we have done four things

  1. Saved the data in the post type ‘enquiry’
  2. Added email to mailchimp list
  3. Sent an email about form submission.
  4. Send the response back to user, indicating success and clearing the form fields.

To save the form data we have used aw2_save_form_data shortcode, where tag is used to  identify the various fields related to post type, and ID of the newly created post is saved to the parameter specified in set_id_as_param field. You can specify, other properties using JSON object.

We used aw2_mailchimp to save part for data to a mailchimp list, and used aw2_wp_mail to send email out.

Finally we have used aw2_spa activity ‘core:insert_html‘ to send message back to user that form has been received successfully.