Joomla Forms Email Actions

bfForms for Joomla 1.5.x Creating new form and adding email action

This tutorial will show you how to create basic form in btForms and how to attach an email action to this form

Author: Igor Mihaljko

Date: February 2009

2

Table of Contents

Preface ....................................................................................................................................................................3

Introduction ............................................................................................................................................................3

Creating basic form .................................................................................................................................................4

Create new form .....................................................................................................................................................4

Review and modify the form configuration .......................................................................................................6

Add form fileds ...................................................................................................................................................7

Final example form .......................................................................................................................................... 10

Form actions ........................................................................................................................................................ 10

Save submission to database........................................................................................................................... 11

Thank you – a simple thank you text ............................................................................................................... 12

Send an email .................................................................................................................................................. 13

Email Header ............................................................................................................................................... 14

Addresing ..................................................................................................................................................... 15

Email Content .............................................................................................................................................. 15

Attachments ................................................................................................................................................ 16

Permissions .................................................................................................................................................. 16

Mail server ................................................................................................................................................... 16

GPG Encryption ............................................................................................................................................ 16

Joomla Global Configuration – Mail settings ....................................................................................................... 17

Final result ........................................................................................................................................................... 17

Conclusion ........................................................................................................................................................... 19

3

Preface

bfForms is a Form generator for Joomla! CMS and is available for Joomla 1.5.x only. It runs in native mode and does not rely on the legacy plugin - It has been designed to meet all your form needs and provide a whole load more than just forms! (Submissions Management, Uploaded File Manager, Export Options).

In first series of tutorials for btForms I explained how to install btForms on your Joomla based web site.

This tutorial will teach you how to create basic form and make it to send user submission to your email address.

Introduction

Creating forms on websites is hard, real hard - so we have taken the burden for you and created a VERY EASY TO USE form builder for Joomla 1.5 that anyone can use.

Build on 4 years of experience developing form creators (Phil-A-Form) for CMS's such as Mambo and Joomla - bfForms has been written from scratch and provides many powerful integrated features such as Spam Controls, Validation Rules, Filters, Custom elements, Export Options and much more.

The extension hosts a huge number of great features. Let us just highlight some of them:

Specifically designed for Joomla 1.5.x

Allows you to create unlimited forms, with unlimited fields and actions

All forms are xHTML and CSS2 valid

Joomla Forms is written by a very experienced Joomla/PHP Developer who has been awarded the Zend PHP 5 Certified Engineer award!

Once purchased, you get free upgrades for life - with a smooth upgrade path at all times.

All forms can be enabled/disabled with a single click

Speedy configuration of forms using a 100% xAJAX admin interface

SECURE FORMS - you can force forms to only show on SSL Secure pages

Quick Start Guide To Creating Great Forms included

Complete Control Over Form Page Titles

Set a maximum number of submissions allowed on a per form or per user basis

Complete control over the text on the submit, preview, reset buttons

Form Preview mode, before submitting the form!

Complete form layout control using Smarty Templates and simple placeholders

Built-in, Transparent, spam controls - NO CAPTCHA AT ALL !!! (We do not believe in CAPTCHA)

3rd party Spam Plugins (Akisment and Mollom)

IP Banning

Blacklist Word Banning

Spam Idiot Checks!

Feature to allow you to add custom JavaScript and Custom CSS to the page

Over 30 different, standard and custom, field types to choose from

Multiple form actions to apply to submitted data

Form Fields are 100% CONFIGUABLE

Over 24 different validation rules can be applied to each individual field

Or create your own with Regex!

4

7 Different filters can be applied to change the submitted value

You can specify a default value for each field - or allow it to be overridden by a string in the URL

Fields can be set as disabled

You have complete control over the class and style of each individual form element

Each field has its own access level and can be enabled for only Public, Registered or special users

On a per field basis you can restrict the allowing of the value to be sent by email or not.

All submissions can be saved to a built in database - or not! depending on your wishes

All submissions can be emailed to unlimited people - including the submitter

You can configure unlimited types of emails, each having their own content

You can set files that will always be attached to the emails sent (Like distributing terms.pdf)

You can allow uploaded files to be attached to the emails

You can encrypt any of these emails using GPG Encryption just by providing the public key

You can use any submitted value in the subject or body of any email with the use of simple placeholders

Creating basic form

Basic form that I will show you in this tutorial will consist of three simple text fields:

Name field name of this field will be fullName

Email field name of this field will be emailAddress

Message field name of this field will be message

I will show you how to create such form, how to attach an email action to this form and how to configure

Joomla to send data filled in form’s elements to your email address.

Create new form

Let’s start by choosing “Joomla Forms for Joomla” from Components menu:

Picture 1: Start “Joomla Forms for Joomla” interface

When the new screen shows up, click on “Create New Form” link on the left side menu:

5

Picture 2: Create New Form link

Enter the name of this form filed “Form Title”, the name which will represent the best this form and its

content. After that, click on a button “CREATE NOW!” to create new form.

Picture 3: Set form title and create the form

Now that the form is created, select it by clicking on a check box next to its name and click on Edit button or

just click on its name in form list.

Picture 4: Select created form

6

Review and modify the form configuration

The next screen will show up with further steps explained. Our first step is to review and modify the form

configuration so we can be sure that everything is set up as we wanted.

Picture 5: Review and modify the form configuration

New screen will load up with just two options. Friendly name is the name that will distinguish this particular

form from the rest of the forms you might have on your website. Second option is the place where you can

setup page title on frontend of your web site. This page title will be shown in browser when your visitors

choose to fill in this form fields.

Picture 6: Setup general settings for selected form

When you are finished with setting up those basic options, press Save button in top right side of the page.

Picture 7: Save form’s basic options

7

Add form fileds Now that we saved this form’s basic setting, it is time to add some form fields to this form. Click on the

following link to add new form field:

Picture 8: Add form fields

First you have to give some title for this field. This title will be presented to your visitors so choose the title

that will show your visitors what you expect from them to put in this field or how to react on the options that

this field might have. For our example form, we will ask our visitor to put full name in the first field of this

form so we will put the text “Your full name:” here

Picture 9: Name properly your form field

Next thing that we must do is to select what kind of form field this filed will be. For our example, we will

choose this field to be Textbox:

Picture 10: Choose field type

8

When you are finished with those two options, press “CREATE NOW!” button:

Picture 11: Finish creating form field

New page will show up with multiple tabs. Those tabs contain large amount of options, which we can use to

further customize our field. There are many options, validation rules, filters, permissions and style rules that

can be set and configured for every field in the form. For this basic example, we will just set up few options.

The rest of those options and rules will be explained in advanced tutorial.

Picture 12: Options and rules for specific form field

First, we will set up friendly, internal field title. This title will help us to distinguish this form field in the list of

other form fields for particular form.

Picture 13: Set friendly form field title

Public field title is title that will appear to your visitor. This is the place where you can adjust this field title

again, if you made some mistake during initial field creation.

Picture 14: Set public form field title

9

Next thing that you should do is to setup this form field internal name. This name is used to create HTML

template for email confirmation, thank you email that can be sent after your visitors complete the form

submission etc.

This must be unique in this form; this means you cannot have two elements with the same system name!!!

You should also keep this quite short, for example: "lastname"

Picture 15: Set form field name

Finally, enter description of this particular form field. This description will be placed beneath form filed title

on your live form. That description is used to convey instructions to the visitor.

Picture 16: Set form field description

For this example, we will leave all other options on their default values. There is only one thing that is needed

to be done and that is to save this form field by pressing on Save button.

Picture 17: Save form field

10

Final example form Here is how this example form should look like after few more form fields placed on it:

Picture 18: Finished example form

Form actions Our form would be just nice add on to our site and nothing more if there wouldn’t be something else that

would actually bring life to this form. That something is called “Form actions”.

Form actions are a way to communicate with our visitors when they fill in our form. You can use form actions

to save submissions to database, say “Thank you” to your visitors, and send them an email confirmation that

their submission if saved and that it is being processed or just redirect them to some other web page after

submission.

Let’s add some form actions. We will start by clicking on “Submit Actions” link on left side menu.

Picture 19: Start defining form action

11

Save submission to database We will define form action that will save data entered in form to a database table so we can browse those

data afterwards. First we have to give some title to this form action. This is our internal title so we can

manage multiple form actions with ease.

Picture 20: Form action title

Set the type of this first form action to “Set submission to database”

Picture 21: Select proper form action type

Now, all we have to do is to click on “CREATE NOW!” button to confirm our selection.

Picture 22: Create form action

This is very basic form action so we will leave the options on their default values by clicking on Save button.

12

Picture 23: Save form action options

Thank you – a simple thank you text Let’s define another type of form action. This time we will define a simple “Thank you” page that will be

shown to our submitter after successful submission. Since we are already on “Submit actions” page we just

have to click on “New” button to create new form action. So, click on “New” button:

Picture 24: New form action

Again, give some title to this form action.


Set the type of this first form action to “Thankyou – A simple thank you text”


13

Click on “CREATE NOW!” button to confirm our selection.

We will see the following screen. On that screen, you can type short message and thank you text that you

would like to present to your form submitters.

Picture 27: Thank you text

When you are satisfied with the thank you text layout and message itself, click on Save button

Picture 28: Save form action options

Send an email Finally, we will define yet another form action that will allow us to send submitted data to an email or group

of emails.

14


Set the type of this first form action to “Send an email”


Click on “CREATE NOW!” button to confirm our selection.

Since this form action is the most advanced one, we will have many options that we can set up for this action.

Those options are separated in tabs as you can see on the following picture:

Picture 31: “Send an email” form action options

I will list all the options for “Send an email” form action.

Email Header

This group of options consists of the following options:

This Actions Friendly Name This is an internal title and is never shown on the site or email Email From Name This is your real name (not an email address) and is used in forming the email's From: header. You can also enter the name of a form field where the submitter will put their name. For example, if your

form element was called "myname" then you should enter #MYNAME# and Joomla Forms will replace this

with the submitted value

Email From Email Address This is your real email address and is used in forming the email's From: header

15

You can also enter the name of a form field where the submitter will put their email address. For example, if your form element was called "myemail" then you should enter #MYEMAIL# and Joomla Forms will replace this with the submitted value

Addresing


How to send emails to the form submitter You might want to send an email to an email address the form submitter has entered. To do this simply go back to your form elements, and write down the "Name" (HTML Field Name) of the element, then enter it in one of these boxes, in uppercase, and surrounded by # signs

Example: #EMAILADDRESS# or #ENTERYOUREMAILHERE#

To: A List of Email Addresses These are the email addesses this email will be sent to, using the To: part of the email. Note that if you enter more than one email in this box they must be one per line, and also each person will see the other persons email addresses. To Avoid this use BCC instead.

Example: [email protected] [email protected] [email protected]

CC: A List of Email Addresses These are the email addesses this email will be sent to, using the CC: part of the email. Note that if you enter more than one email in this box they must be one per line, and also each person will see the other persons email addresses. To Avoid this use BCC instead.


BCC: A List of Email Addresses These are the email addesses this email will be sent to, using the BCC: part of the email.


Email Content

The body of the emails will be parsed by the action to replace placeholders with the values the visitor has just

submitted.

These placeholders are the HTML Field Name (Name) of the element, in uppercase, surrounded by #'s

Example: Dear #NAME#, Thanks for sending me your address, you

entered #ADDRESS1#, #ADDRESS2#

mailto:[email protected]

16

Plain Text Email Body If you would like to send a plain text portion of the email please add it here.

HTML Email Body If you would like to send a HTML text portion of the email please add it here.(Remember this should include

any HTML Markup!!)

Example:

<h1>Thankyou!</h1><p>Your details have been received</p>

Attachments


Send submitted files, which have been uploaded, as attachements to this email This relies on the file upload field having the permission to "send by email" set to yes

Attach these files always Specify in this box a list of files you wish to attach every time. They should be with the full path and file name.

E.g. /home/phil/public_html/myreport.pdf.

Enter ONE filename per line.

Permissions


Joomla Access Level A visitor needs to be this level or below to trigger this action Publish this action Toggle this action published/unpublished

Mail server

Configuration for outgoing mail In Joomla, all outgoing email is controlled by the configuration options set in your Joomla Global

Configuration.

If the configuration you have set in Joomla Global Configuration is not compatible with your server then we

will never be able to send form submissions, Please check with your web host for the correct settings

We highly recommend SMTP with Authentication, as the most reliable and secure email transport - ask your

web host if this is available to you...

GPG Encryption

GnuPG is the GNU project's complete and free implementation of the OpenPGP standard as defined by

RFC4880 . GnuPG allows to encrypt and sign your data and communication, features a versatile key

17

managment system with public key directories. GnuPG is also known as GPG. If you want your emails to be

encrypted - and very secure - then you might want to learn more about GPG

Public Key To Encrypt To If you specify a public key here, and leave the html message blank, opting instead for a plain text message,

Joomla Forms will encrypt mail sent with this action to the supplied public key before sending

Joomla Global Configuration – Mail settings As I mentioned before, Joomla Forms for Joomla depends on your Joomla mail settings. Be sure to set up mail

settings in Joomla global configuration and test sending emails from Joomla. If you are able to send emails

from Joomla than your email form actions will work for sure also.

Picture 32: Joomla global configuration – Mail settings

Final result When everything is finished and your form tested here is how the result of form actions looks like (for our

example form):

Picture 33: “Thank you” simple text

18

If you click on Submissions link in left side menu, you will see all saved submissions that your visitors

submitted by filling out and submitting your form details:

Picture 34: Submissions link on left side menu

Picture 35: List of submitted data saved in database

Email sent by “Send an email” form action.

Picture 36: Email example

19

Conclusion

This concludes my tutorial about creating basic form and attaching email action to it.

I hope that this tutorial will be useful to some of you.

If you have any questions regarding this extension, please, check our FAQ section or contact us by using Contact link on our web site.

Author is working for Blue Flame IT company as freelancer in charge of writing extension documentation. You can reach him through contact form on his web site http://www.mihha-vision.com or by writing him to email [email protected].

http://www.mihha-vision.com/

mailto:[email protected]

Documents

Joomla Forms Email Actions