Awesome studio framework for WordPress provides two ways of working with Awesome Forms in WordPress and they both submit the form data using Ajax.
- 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.
- 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
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 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.
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
- Saved the data in the post type ‘enquiry’
- Added email to mailchimp list
- Sent an email about form submission.
- 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.
Finally we have used aw2_spa activity ‘core:insert_html‘ to send message back to user that form has been received successfully.