Sending the form results by e-mail
We have a newsletter sign up form that works, but doesn't do anything. The simplest action to take when the form is submitted is to send an e-mail to the site administrator to say that a new form submission has been made.
Getting ready
You need the simple form that we created in the previous recipe, and to navigate to the ChronoForms Forms Manager view in the Site Administration area.
To actually send an e-mail successfully, your site must have access to a working mail server configured in Site | Global Configuration | Server | Mail Settings (see the Joomla! documentation at http://docs.Joomla.org/Screen.config.15#Mail_Settings).
How to do it...
1. We're going to use the Wizard Edit to add more to the existing form. Click the check box next to newsletter_signup in the Forms Manager, then click the Wizard Edit icon in the toolbar above:
2. When you open your form with Wizard Edit there's a warning message that says, Please note that any changes you made to the form HTML code in the Form edit page will be lost once you save new changes in the wizard! We've made no changes to the Form HTML so we can click the x at the top right to close the warning window.
Note
ChronoForms saves the "source" code for the Wizard completely separately from the Form HTML that you will see in the Form Editor. And it isn't clever enough to re-interpret all the possible manual changes that could be made. One way to work is to use Wizard and Wizard edit to rough out a form, then add the finer details by manually editing the Form HTML, but then we can't use the Wizard on that form again.
3. Once the Wizard is open, click Step2 Choose Email(s) Settings and you will see a similar workspace, though with different entries in the Toolbox. There is also an "envelope" icon instead of the screen and an extra "garbage can" icon to delete an unwanted e-mail setup.
Notice that the Toolbox entries all relate to e-mail headers — To, From Name, Subject, Reply to, and so on. But at the moment we can't drag them into the workspace.
4. First, click the envelope icon to create a new e-mail setup. An Email Setup is a set of instructions to tell ChronoForms to send an e-mail using this particular set of headers.
Note
You can have more than one e-mail set up in this space by clicking the envelope icon again. So, for example, you could send one e-mail to the site admin and another, quite different one to the person who completed the form.
Now we have an e-mail setup workspace coloured red.
5. Drag the following elements from the Toolbox into the red box in the workspace:
To
Subject
From Name
From Email
Two things have happened here. The Email Setup workspace box is no longer red, it's a yellow-green, and the Email Properties box now has some content.
Note
We've added the elements in the order To, Subject, and so on, but in practice the order doesn't matter. You can also use other elements but we'll come to them later.
If the workspace stays red, then you do not have the correct four elements in the workspace! Also notice that when the workspace is red the Enabled? option in the Email Properties box is greyed out.
6. We now need to add entries to each of these four boxes. Unlike the Form Design workspace where the boxes are left empty, in Email Setup they must be completed.
The preceding screenshot shows a completed Email Setup. Notice that the To and From Email boxes have valid e-mail addresses in them. If they are not valid the e-mail will fail — ChronoForms does not check these, it's up to you to get them right.
Note
We will use
example.comas a generic domain throughout this book. You will need to replace this with the domain of your site as appropriate.In the Subject and From Name boxes you can add any text string that you like, provided that it's not too long (the box will accept 150 characters, but a practical limit is around 50).
While you can put any valid e-mail address that you like in the From Email box, we strongly recommend that you use an address that has the same domain as your website. Many ISPs check e-mails being sent to make sure that the domains match. If they do not then the e-mail may be flagged as spam, or just dropped.
Note
We have used
admin@in the To box andinfo@in the From Email box. It should be possible to use the same e-mail address in both boxes but we have seen a few cases where e-mails with identical To and From Email addresses have not been delivered.7. To finalize the Email Setup there are a few more small things to do.
Set the Enabled? drop-down to Yes, and then click Apply to save the Email Setup.
Then click the "floppy disk" icon above the workspace to save the form again.
When you click the "save" icon you will be asked the name of the form that you want to save. This field defaults to the name of the form that you were currently editing, but if you wanted to save a new form, you could change the name of the form in the input box. We will just leave the form name that we are editing and update this form.
8. Back in the Forms Manager you can see that the Emails column has changed and now has an entry that says Enabled:0 / Disabled:1.
9. So we have our e-mail setup but it is still disabled. To enable e-mails we need to open the form for editing not in the Wizard Editor but in the standard ChronoForms Editor. To do this click the newsletter_signup link (over to the left in the image):
10. There are a lot of tabs here and many settings options, but we only need to change one. On the General tab find Email the Results? and change the setting to Yes.
11. Now click the Save icon (the floppy disk) to the top right of the screen to save the Forms configuration.
Note
This option turns "all" e-mails on or off, while the setting in the Email Setup | Properties box turns just that single Email Setup on or off. Of course, if you only have one Email Setup these are the same but it's useful with more complex forms.
Back in the Forms Manager view you can see that the Emails column now reads Enabled:1 / Disabled:0. Perfect!
12. We just need to test our form to check that the e-mail works correctly. Click the form "link" entry to open the form in a new browser window or tab; enter an e-mail address in the Email box and click Submit.
Note
If you still have the form open in your browser that's fine, but please click the Re-Load button in your browser to refresh the code before you test.
When you click Submit the form is submitted and you are left looking at an empty Joomla! page, that is unless you get an error message. We'll put a "Thank You" message on here in the next recipe.
And here's the e-mail I received after submitting. Notice that ChronoForms has built the email using the information we put into the Email Setup (I've blanked out the real e-mail address I used to send it to).
And it has taken the information submitted from the form and included that in the e-mail body. That's clever!
There's also the IP address of the submitter; you can turn this off in the Email Setup | Properties if you don't want it.
13. Congratulations! Now you have a working form that carries out an action when it is submitted. My guess is that around half of all web forms work just like this, though maybe with a few more fields.
How it works...
ChronoForms has taken the information we input in the Email Setup and taken the form HTML to create a default body template for the e-mail, and combined all these together behind the scenes to create a rather basic but completely functional e-mail.
See also
Chapter 2, Emailing Form Results for more advanced e-mail features and functionality. The Getting your emails delivered safely recipe has some useful hints for trouble-shooting problems with e-mails and Email Setups.
Chapter 8, Uploading Files from your Forms has recipes on Attaching files to e-mails and Displaying images in e-mails and articles.
Chapter 7, Adding Features to your Form includes the recipe Adding a barcode to an e-mail.
Chapter 12, Adding Advanced Features has an advanced recipe on Controlling e-mails from from inputs.
