Tutorial: PHP easiForm, easiCaptcha actions & Freeway Pro 





Home | Buy easiForm | easiForm actions | Contact Us | [1]








PHP easiForm is a suite of actions to take all the coding out of your web forms in Freeway, * 100% code free *. PHP easiForm will offer protection for your form against spam usage out of the box but using PHP easiForm with the PHP easiCaptcha action will give you even more protection. (Current: easiForm v1.83)

The 'PHP easiForm' and 'PHP easiCaptcha' actions for use with Freeway will make secure form creation in Freeway a breeze, the actions create the scripts to your preference and then upload them to correct place on your server.

This is a short tutorial showing how quick and simple it is to set up secure forms in Freeway with the 'PHP easiForm' and 'PHP easiCaptcha' actions.

Note that 'easiCaptcha' cannot be used with other form scripts unless they are altered for it's use, easiCaptcha has been written to be compatible with easiForm.

easiForm pricing See here








Download: Freeway easiForm action Example forms






What do I need to use the easiForm or easiCaptcha actions in Freeway?






1# A copy of the 'PHP easiForm' action suite. (If using a captcha then the 'PHP easiCaptcha' action also).

Download the 'PHP easiForm' actions from: The easiBase Freeway actions page.

2# You need a web form page and a success or thanks page, you can put these together in Freeway, use one of the ones in our examples and edit it to suite your needs if you like.

NOTE: The easiForm actions do not create your form or thanks page, it just takes all the work out of getting the form to work.

3# A loader file to decrypt the scripts that the 'PHP easiForm' and 'PHP easiCaptcha' actions create, the loader used depends on the system and server type that the form is used on. If you do not have the 'ioncube' decoder folder on your server then you can download one of the action download options that include this folder with loaders for both windows and linux servers.

If you need a loader for another server type such as OSX, FreeBSD, Solaris or other then those loaders can be downloaded from the ioncube loaders download page. If you are unsure as to which loader to use or have other questions you can Download a folder that will check the loader you need, or if you are having problems you can Contact us.

Note: The form page generally needs to end in .php, so this following name would not work: 'myform.html' it would need to be: 'myform.php' or 'somethingelse.php' unless the form page notation is set to be parsed as php on the server you are using your forms on.

5# A copy of Freeway 4 or 5 Pro - Softpress

You can set up and test your easiForms in Freeway before buying, in fact we advise you to do this so as to guarantee that your server permits use of the ioncube loaders and you have no other issues, most do or will allow their use but there is the odd provider that may not accommodate.

Two hosting companies that support ioncube loaders are have-host.com (James Wilkinson) and ineedwebhosting.co.uk (David Owen), an added advantage is that both companies owners are also Freeway users.

Download a detailed in depth, step by step process for using all 5 of the actions included in the PHP easiForm actions suite.

If there is anything you don't understand or need help with while trying to implement these actions on your form than feel free to Contact us






QUICK START GUIDE: A Rapid guide to adding the 'PHP easiForm' actions to your Freeway form.






If you want to go through each step with explanations, details of the action value options and images then go to 'Step 1' after this section, otherwise you can use this short 'Quick start' guide to get your forms up and running without all the added information you you may find irrelevant. If you have not already installed the 'PHP easiForm' action in Freeway Pro 4 'or above' then double click the action file and follow the prompt.
Note that any single quotes in the guide or tutorial should be ignored unless otherwise stated.






1# Create a thanks page and call it whatever you want.



2# Create your form page and name it 'somename.php' (note php extension).



3# Add the form elements to the page (fields, radio buttons, checkboxes and submit button etc.)



4# Name each element and add the 'PHP easiForm Element' item action to each one, (the e-mail field needs to be called 'email' as written without quotes). No spaces (Use an underslash '_' for a space), do not start names with a digit.



5# Add the 'PHP easiForm Element' action to the 'Submit' button as well. (Not needed on a 'Reset' button).



6# Add an HTML item above the form elements and add the 'PHP easiForm Errors' item action to it.



7# Make sure the form page is selected and then add the 'PHP easiForm' page action.



8# Enter the recipient email address in the actions window for the 'PHP easiForm' action.



9# Upload the 'ioncube' folder to the root or home folder on your server using an ftp client'



10# Select 'Upload' from Freeway and then enter the URL of your form page into a browser.






OK, if you have done the above you should be up and running.

You can read on if you want to go through each step with images and more detailed information.







Step 1: Build the thanks page:






Create a page in Freeway and call it something like 'thanks.html' or 'success.html'

Add some thanks text to the thanks page.


OK, the thanks page is now ready, move on to Step 2...







^-- Top







Step 2: Build the form layout:






Build your form by placing the different elements on the page and positioning them as you want.

We have just used a very simple layout without any design for example purposes only, but you feel free to design the form page as you like.

You can use an image as the submit button if you prefer that method over a normal submit button. If you use an image for the submit then you still need to apply the 'PHP easiForm Elements' item action to that image.

It can be really helpful to build your form within a table structure (we have not done that here), using a table will hold everything together neatly and keep things lined up. When you add your text and elements to the table cells then it can help to align them to middle (vertically).

Note: This form page needs to have a .php notation and not .html, if you see code * when the form is uploaded to your server * then not naming the page with .php will probably be the problem.

.php pages are not WYSIWYG in Freeway, if you select 'Preview' then you will see a page of code in Freeway, this is normal.

OK, the form page has it's elements apart from one, move on to Step 3 to add that element...

^-- Top







Step 3: Add an HTML item for the user error text:






The other element we add is a HTML item, we place it at the top of the other form elements and this will be used for the text to alert the user to any error they made on the form.

Note: If you are using a table then a cell can be used for the error text, you will just treat the cell the same as the HTML item as directed in the next step.

Tip: You can also add a style to the HTML item or cell while it is selected, that way the error text returned will be styled relatively to the style you set it to. You should add styles to any other element that has text, then again the text will be styled relatively.

If you are using layers then you need to position this item where any user error text will not overlap the items or elements below it, a way of avoiding this would be to make the form items non layered items so they adjust downwards to compensate if user errors are returned.


^-- Top











While we are here we may as well add an instance of the 'PHP easiForm Errors' item action. We add this action while the HTML item 'or cell' is selected:

Item > Actions > PHP easiForm Errors

This action will add some code to the selected item that outputs any error the user might make if maybe not filling in a REQUIRED value on the form.

Be aware that if the form elements below are layered items any error text may overlap the items below, so bare this in mind when building your form layout. A simple solution is to build you form page using non layered items. Also Freeway can set a default 1px style to html items and cells that it thinks are empty, as far as Freeway is concearned an html item or cell with the PHP easiForm Errors action applied is empty, to avoid having the error text unreadable at 1px high you simply need to add/type a space in the item or cell the PHP easiForm Action is applied to.

You can also set some default text in this area such as:
Fields marked in bold are required. There is an option in the actions inspector window to set this automatically or set some other text if preferred... apply a style to the HTML box so any text that is output is styled.

OK, moving on to Step 4...

^-- Top








Step 4: Add the PHP easiForm action:






Now we add the 'PHP easiForm' action to the form page, so select the form page and then add the action:

Page > Page Actions > PHP easiForm

Now that you have added the 'PHP easiForm' action to your form you will need to enter and select some options from the actions inspector palette. The first one is the 'Recipient email', this is the email address the form should be sent to.

This action will create the easiForm_mail and easiForm_config scripts that Freeway will upload to your server. It will also take care of the forms '<form action=' and '<form method=' values. The '<form action=' will be set to point to the same page as the form 'to it'self' and the '<form method=' to POST.

The 'Perform POST on easiForm variables' checkbox is selected by default and will add code to retrieve the values of the passed variables.

OK, while we are here we need to select a couple of other options in the actions palette, so onto Step 5 for this...

^-- Top







Step 5: Set some options in the PHP easiForm action palette:






Depending on the option you select from the 'Configuration options' menu will depend on the settings available to you from the configuration file.

# For the default setting of 'Basic':

OK, you should have already entered the 'Recipient email' in the last step, if not then enter it now.

'Action on success' Set this to 'Divert to page...' if not already.

'Success page' Select the 'thanks' page from the menu, the one you created at the start of this tutorial.

'Required names' Enter any of the form element names into this field that you want the user to enter or select values for. (We haven't got to naming the elements yet but we will on the next step).

'Agree names' If you need to add an option like 'I agree with the terms...' etc. then add 2 radio buttons and name them both say '1_agree_with_terms' (Without quotes), give then both some text like 'I agree with the terms of the web site' and the other 'I do not agree...', then give the one that related to agreeing a value of 'yes' and the other a value of 'no'. Now enter the name of these radio button into the 'Agree names' field, in this case '1_agree_with_terms' (Without quotes) and the form will return an error if the user does not select the agree radio option.

This can also be used for age over 18 etc. any additional option like this should be added separated with a comma into the 'Agree names' field, DO NOT use the 'Required names' field for this type of option.

Because of the way the values are handled with php it seems the simplest way of implementing this option and for also returning a specific error type when the user does not select the 'Agree' option, do not use a checkbox for this type of request, use 2 radio buttons as directed above.

'Subject' A subject for your form message sent to the recipient.

'HTML filter' We advise a selection of 'Disallow html' so your form fields cannot be used to send code or links.

# For the 'Advanced' setting:

'CC Emails' The email sent from the form can be sent to a total of 4 email addresses, the 'Recipient' address and up to 3 others that can be entered into the CC emails field, addresses should be separated with a comma.

'Set -f parameter' Some servers require that the 5th parameter in PHP's mail() is set, from action v1.42 this is set to the 'Required' email by default although you can set this to another email address or not at all using the menu for this option.

'-f parameter email' The email address if 'Other' is selected from the 'Set -f parameter' menu. Depending on the server this probably needs to be set to a valid email address from the server domain the script is used on, others require nothing more than an address of 'noemail@thedomain'. This address is used only for the -f parameter and is a security requirement from some servers.

'Random subject tag' If used Emails will be sent with a random subject number for thread tracking purposes.

'Block domain' For reasons I do not known a spammer trying to use your form might enter an invented email address from the domain the form is on, select 'Yes' to prevent this. Note: if you are testing your form and this is set to yes then you will not be able to use an email from the same domain for the form email field when sending any test message.

'Block badwords' Select any preset bad words you want blocked from email messages.

'others...' Enter any badwords you may want to block that are not listed in the 'Block badwords' list. This is handy if you start to receive spam with certain words you want to not allow, adding them to this field will stop the user from sending messages that contain those words.

'User confirmation' Select if a confirmation copy of the email should be sent to the sender. Use the following 'Footer' fields to enter a web address and email address as the footer in the confirmation email if selected. Note we advise using the URL of the contact form as the email address although just an email address can be used.

'Add date stamp' Select if a date stamp should be added to the emails.

'DS time zone' Select the time zone of your server so the date stamp is correctly formatted to the server time.

'User errors' Set to full to return user errors in the 'PHP easiForm Errors' action, set to 'Basic' if you just want to use the default error as a flag for maybe changing the color of the title of an error field.

'Number errors' Set to 'Yes' to precede any user error with a number, i.e. 1, 2, 3, 4 etc. Note: if you name a field 'your_name' (Without the quotes), then make this a required option and the user does not fill in a vague before sending the form then a variable called '$your_name_err' will be set to true, so you can now use this to flag any hand set code for changing the title text colour rather (or as well as) setting the text error in the PHP easiForm Errors action location. (The action suite now comes with PHP easiForm Titles action which sets the following code for you but I have left it here in case you want to set it yourself).

if ($your_name_err) {
echo "<font colour=red>Name</font>:";
} else {
echo "Name:";

'and / or' Set to the char you want to follow the number or if no number is used a char to start the error line with if required.

'Textwrap fields' Set to the names of any fields that you want to wrap the text on, separate names with commas then enter the number of chars to wrap the text to. Fields names as 'message' or 'comments' are auto wrapped to 75 chars, this can be shorted using these options and others can be added.

OK, onto Step 6 to name the form elements...

^-- Top







Step 6: Names and Values for form elements:







Go through each element on your form and give it a name.

Name values can be written as 'yourname' or 'your_name' (without quotes), do not use any spaces in the name although you can use an underslash for a space which the action will remove later... see tip below in this step. You do not need to start element names with a capital, easiForm will convert the value to start with a capital letter in the email you receive.

Note: Radio buttons have the same name for the cluster group but a different value needs to be given to each radio and checkbox value. Text fields and text areas do not need a value entered in the Value field as the action will handle this for you.

The e-mail field name needs to be called 'email' in lowercase and without quotes.

Using a confirmation email field (Available from action version 1.42b):

To add a confirmation email field set up with your easiForm you simply need to add a field below the email field, give it a name of email_confirm (exactly that, case sensitive) and add that name to the 'Required values' field of the PHP easiForm action window, add it after email e.g. 'email,email_confirm' (without quotes). Now easiForm will check that the email and email_confirm fields match.

It is important * not * to use special chars such as á, é and ñ etc. in the element names, full stops, commas and spaces are not accepted either, but you can use - 'hyphens' and or _ 'underslash'. So the characters: a-z, A-Z, 0-9, - and _ are valid while other characters are not.

Element names should be started with a a-z or A_Z character and not be started with a digit, for example a name such as '8ways' is not valid while 'ways8' or 'way8s' is.

Tip: Use a name for each item that is relative to the information to be entered, for example if you have a field for senders name and use the text 'Your name' beside the field then set the Name field in the Text Field Inspector as 'your_name' (without quotes), now if you make that field a required value in the Action palette and the user does not fill it in an error will be returned for the 'PHP easiForm Errors' action, the error would be to the effect of "Error! the 'Your name' value was not entered.", easiForm will remove the '_' (underslash) from 'your_name' and return 'Your name'

OK, onto Step 7...

^-- Top








Step 7: Add the PHP easiForm Elements action to each of the form elements:






Select each form element including the Submit button and add the 'PHP easiForm Elements' action to it.

Note: If using an image as a submit button: apply the 'PHP easiForm Elements' action to it as you would for a basic submit button. There is no need to select 'submit' for the image used as a submit button, the PHP esiForm Elements action will take care of this for you.

This action will change the name and value of the element it is applied to, you will not see these changes in Freeway but they will exist in the code Freeway produces. For example, if you name a text field element as 'your name' the 'PHP easiForm Elements' action will change it's name to 'f[your_name]' and set the value to '$f[your_name]'.

When applied to a submit button the button name will be set to 'submit' and the value set to whichever value you have set, if you have not set a value then it will be set as 'Submit'. This action will override any name you give the Submit button but you can change or set the button value to what ever suites your form.

Onto Step 8...

^-- Top








Step 8: What the final form looks like:







OK, if you followed the above steps your form should look something like the image to the right.

Now when you publish your form the actions will add any of the code needed to use easiForm into the page html code, the actions will also tell Freeway to create the scripts needed for your form or forms.

You can now upload the website to your server using Freeway, any relevant scripts created by the 'PHP easiForm' action will also be uploaded by Freeway.

Last step, onto Step 9...

^-- Top








Step 9: The 'ioncube' folder:







Basically everything is done on your form side but one thing does still remain if not already undertaken, the server that hosts your form or forms will need a copy of the 'ioncube' folder to be uploaded to the root or home directory. You will probably find this 'ioncube' folder was included in the download of the PHP easiForm actions, if not you can download it from here: ioncube loaders

Once you have done this you should find your forms will be up and running. A license file is needed to remove any demo alerts from your form, if and when you receive the license file for the domain that your forms are being used on you should upload it by FTP to the same directories as any of your forms using the PHP easiForm actions.

If you want to add a math or image CAPTCHA to your form then there is the 'PHP easiCaptcha' action for this purpose, now your captcha can be added to your easiForm simply by adding one instance of the action to an item on your form. If you want to see how to add the 'PHP easiCaptcha' action to your Freeway form that uses the 'PHP easiForm; actions then read on...



Optional Step 10: Adding PHP easiCaptcha action to your Freeway easiForm:







To add a captcha to your Freeway form is very simple with the 'PHP easiCaptcha' action. In this Step 10 we add a Math type captcha to the form you have just created.

Add some text to ask the user to answer the math question.

Add an HTML item just below it.

OK, lets move onto next image in this step below...








Now with the HTML item selected add the 'PHP easiCaptcha' item action to it, your form should now look like the image to the right.

Now select 'Math' from the 'PHP easiCaptcha. action palette and make any changes in the selections if needed.

If using a table for your form the 'PHP easiCaptcha' item action could actually be applied to a cell between the text and the Submit button.

Tip: Don't forget to select and add a style to the HTML items so the text will be styled to suite your form. Add a style to the HTML item or cell that has the 'PHP easiCaptcha' item action as there is text output there also.

Well that's it, you just need to upload the site to your server with Freeway and all the relative scripts will be created and upload.

If you want to see how to use an Image captcha rather than a math captcha then read on...








To change the captcha type from a Math to an Image captcha then simply select 'Image' from the 'Captcha type' menu. There are a different set of options available, make any changes if you feel you need to. Upload the site to the server again and your form will have an image captcha.

If you use an image captcha then you probably don't need the 'Please answer...' text so either don't add it or if using the form we created here then just delete it and move the HTML item and button up a little.

The action will place the 'easiCaptcha' field for the user entered image text just below the image, if you want to place this field in a different position then select the 'I will be inserting the text field manually' checkbox and you can then place a text-field for the captcha text where you like.

Note: If you add the easiCaptcha field yourself then this field needs to be given a name of 'easiCaptcha' case sensitive and without the quotes, do not enter a value. You do not need to apply the 'PHP easiForm Elements' action to it as this easiCaptcha field.

All done apart from uploading it to the server.

Good luck with your forms.











The easiForm actions have quite a lot of spam protection built in but adding a math or image easiCaptcha to this will make your forms even more secure. easiForm and easiCaptcha are available as a bundle and the same licenses cover the Freeway actions.

A license for easiForm is $20 per domain (Not IP Address) or $30 as an easiForm and easiCaptcha or easiCaptchaM bundle, this allows as many copies of easiForm to be used on the same domain it is registered for. Once bought a license cannot be used for any other domain than the one it has been registered for.






^-- Top









Freeway 4 Pro PHP easiForm and PHP easiCaptcha examples here.










Copyright © Mike Brackenridge 2006 - 2022 || Freeway is a registered trademark of Softpress Systems Limited.