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
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
2
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!
3
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:
4
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
5
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
6
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
7
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
8
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
9
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
10
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.
11
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.
Picture 25: Form action title
Set the type of this first form action to “Thankyou – A simple thank you text”
Picture 26: Select proper form action type
12
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.
13
Picture 29: Form action title
Set the type of this first form action to “Send an email”
Picture 30: Select proper form action type
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
14
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 This group of options consists of the following options: 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: phil@phil-taylor.com bill@microsoft.com testing@dev.com 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. Example: phil@phil-taylor.com bill@microsoft.com testing@dev.com BCC: A List of Email Addresses These are the email addesses this email will be sent to, using the BCC: part of the email. Example: phil@phil-taylor.com bill@microsoft.com testing@dev.com 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#
15
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 This group of options consists of the following options: 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 This group of options consists of the following options: 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
16
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
17
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 â&#x20AC;&#x153;Send an emailâ&#x20AC;? form action.
Picture 36: Email example
18
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 mihha@inet.hr.
19