Greyhead.

net
ChronoForms v4 : Basics 1 with Jon Wilkin
This is a rst introductory tutorial for ChronoForms v4 describing how to build a simple contact form. It also includes a description of all the basic form elements supported by ChronoForms and an introduction to sending an email. There is a series of videos on the greyheadnet channel at YouTube that cover similar topics. XX Written with ChronoForms v4 RC3.3

HOW-TO DOCS AND TUTORIALS

CHRONO

v4

Forms

Greyhead.net

Constructing a Contact Form in v4

Here we create a contact form using the ChronoForms v4 Form Wizard. This Wizard allows you to use HTML when you want or need to, but never requires that HTML is used. You will nd it useful to know what you want in your form before you begin constructing the form using the wizard. A sketch of your contact form might look this way:

XXYoull need ChronoForms installed to follow the rest of this tutorial which was written with ChronoForms v4 RC3.3

Constructing a Contact Form in v4

Greyhead.net
When you open the ChronoForms Forms Manager and then click the Form Wizard edit , you should see a screen like this:

Notice the Full Screen icon in the toolbar, well click that now to get a clean workspace. Youll see a screen icon at the top right to get back.

Constructing a Contact Form in v4

Greyhead.net
First, click the Form Settings tab because its easy to forget this step later. Give your form a name using letters, numbers and underscore _ only and no spaces; and check that Published is set to Yes.

Notice that on the left side, below the Elements is a list of form elements divided into two groups Basic and Advanced. Well say a bit about each of the Basic elements next even though well only use a few of them in our contact form.

Constructing a Contact Form in v4

Greyhead.net

The Basic Elements

Text input
The Text Box element is the work-horse of web forms. It is used to input a single line of text; in our Contact form well use it for the Name and Email inputs.

The Password Box element is exactly the same as the Text Box element except that the contents are hidden and replaced by asterisks ********. The Text Area element is used to input longer text on more than one line. Well use it for the question/comment input in our Contact form.

The Basic Elements

Greyhead.net Submit and Captcha (anti-spam)

The Submit Button element is used to submit the form. You can congure this element to change the name of the button and to show Reset and Back buttons as well as the Submit button.

XXYou can use more than one Submit button in a form as a way of letting the user choose different options. The Captcha Input is a special element used to insert an anti-spam Captcha input into a form. Usually it goes near the end of the form just before the Submit button.

XXThe Captcha Input works together with the Load Captcha and Check Captcha actions.

Headers
The Header Text element (and the Custom Element element in the Advanced Group) can be used to add headers or short blocks of plain text into your form.

The Basic Elements

Greyhead.net User Selections

These are a group of elements used to let the User make one or more selections from a group of options. The Checkbox element is the rst and simplest of these. It is most often used to have the User conrm that they have read and accepted some Terms and conditions. It is a simple Yes/No choice.

The Radio Box element offers two or more options. The user can click only one option or, sometimes, leave them all unclicked. Once an option is clicked clicking another option de-selects the rst so there can only be a single selection.

The Drop Down element also offers a list of options and typically the user is only allowed to select one of them.

The Basic Elements

Greyhead.net
The Checkboxes Group element offers a list of options but in this case the user can select more than one of them.

You can also enable the multiple option in a Drop Down element so that the user can select more than one option from the drop-down list. Which you use typically depends on the number of options. Drop-down lists are more convenient if there are many options to display like a list of countries. If the user needs to choose: one option from a list of two e.g. yes or no then use a Checkbox, a Radio Box or a Drop Down. one option from a list of options then use a Radio Box, or a Drop Down. one or more options from a list of options then use a Checkbox Group or a Drop Down with multiple enabled.

The Basic Elements

Greyhead.net Special elements

The DateTime Picker element is a text box linked to a JavaScript calendar that can be used to select dates and/or times.

This is a very exible element that can be congured in many different ways to make date and time selection simple and reliable. XXYou can use a plain Text Box element to input a date or time but validation and formatting can end up being very complicated. The DateTime Picker avoids of all that. Lastly, the File Upload element is used when you want to allow the user to upload a le from the form.

The Basic Elements

Greyhead.net

Constructing the form

To construct our Contact form we can drag the elements we want from the Elements column on the left side into the Preview box on the right. XXYou can drag more than one element of the same type if needed. We drag over each type of element we need in the order they show in our form: Header Text, Text Box, Text Box, Text Area, Submit Button.

You can drop the element anywhere in the Preview box and it will be added as the last item. Dont worry if you mess up the order, it can quickly be changed later.

Constructing the form

Greyhead.net

Conguring elements
At the right of each element in the Preview box, you will see three icons:

The red x icon is used to delete this element; The yellow and blue spanner icon is used to congure this element; and The green arrows icon is used to drag the element up or down inside the preview box to change its position. When you move your cursor over the icons it will change from an arrow into a hand when they are active.

10

Conguring elements

Greyhead.net The Header Text element

Click the spanner icon to congure the Header element. A modal window will open with the conguration options.

This is one of the simpler conguration windows with only two main options so it is easy to understand. The rst is a Pure Code checkbox with the a slightly cryptic help text below it. If you leave this box un-checked then ChronoForms will wrap the content in set of HTML <div> tags in the same way that it does other form elements. If you dont want this check the box to get pure code. The second is a Code textarea where you can type in (or copy and paste) code. Here weve typed in the header text for our form. To save the conguration click the Apply tab at the top right. This is important, if you dont do this your changes will be lost!

!
11

Then close the modal window by clicking the x icon on the corner above the Apply tab.

Conguring elements

Greyhead.net
While we just put a sentence of plain text in the Header box there are other ways to use it. You can use HTML tags in your text to format it. For example:
<h2>Query form</h2> <p>Complete this form with your question and/or comment, then submit it If you request a response, we will do so as soon as possible All fields are required.</p>

If you click the little Add/Remove editor link the text area will be converted into a Rich Text Edit area using one of the installed text editors, Tiny MCE in this case.

XXThe Header element is OK for short text snippets but there are sometimes problems with longer text or HTML. Using a Custom Element from the Advanced Group may be more reliable in this case. XXAvoid using double straight quotes " in the Header element as they seem to cause problems, single quotes ' or curly quotes are OK.

12

Conguring elements

Greyhead.net The Text Box element

The next two boxes for the user name and email are very similar. They require a name, a label and validation setting. As an example well look at the Email Text Box element. Click the spanner icon to open the conguration dialogue in a modal window. The image here just show the parts that interest us now.

You can leave the Field Name unchanged if you like - it is the name that ChronoForms will use to identify this part of the form data. I prefer to make the name meaningful and so will change this to email, and add the same entry into the Field ID box. XX Name and ID entries can only use letters, numbers and underscore _ and must begin with a letter (no spaces, dashes or other special characters).

13

Conguring elements

Greyhead.net
The Label Text is the label that will appear next to this input on your form so well change this. Because this will be a required input well add an asterisk too, The entry is E-mail * Here is the result:

Now click on the Validation tab, where we check required and email. Save this element in the same way as the Header Text element above. Repeat this process to congure the Name Text Box element. Lastly congure the Message Text Area element the same way. XXYou will see an extra Editors tab in the Text Area element, you can use that to add a Rich Text editor to the element but we wont make any changes there in this tutorial.

14

Conguring elements

Greyhead.net

Saving your form

It is time to save the form. Your changes you have made will not be nally saved and will not appear until you save the form. Apply and close any modal window that is open. If you are in Full Screen mode click the little screen icon at the top right to return to the Forms Manager. In the Forms Manager ToolBar click the Save icon (you can also use Save and Close but that will also close the Wizard).

Once the form is saved, you will see your new header and label text are visible in the Preview box.

15

Saving your form

Greyhead.net
Now that the form is saved you can try clicking the Test Form icon in the Forms Manager toolbar to open a copy of the form in a new browser tab. If we try the browser tab opens but all that we see is a page that is empty apart from the ChronoForms strap-line (though if you have a validated version of ChronoForms you wont even see that).

We need to do one more important thing to get our form to display. Open the Form Wizard and click the Events tab. Well talk more about this a bit later. For now, just drag a Show HTML action from the left hand column and drop it into the yellow On Load box.

Save the form again.

16

Saving your form

Greyhead.net
Reload the Test Form view and the whole form should display like this:

This is a good point to do a quick check back and compare the form with the specication we started out with. Here weve missed out the Request a response checkbox; the Text Area element looks a bit big; and the elements are spaced out a bit too much. We can go back to the Form Wizard and make some corrections.

17

Saving your form

Greyhead.net
First, well drag a Checkbox element into the Preview box. It drops in below the Submit button element so we can use the green arrows icon to drag it up above the Submit button. Open the conguration and set the Field Name, Field ID and Label Text; set the Label Position to Right Click Apply to save the element. Next open the Textarea element and set the Field columns to 30 and the Field rows to 8. Click Apply to save the element. Lastly, click the Form Settings tab and set Tight Layout to Tight. Save the form and click the Test Form toolbar icon to see the results:

That looks good enough for the moment . . . While you are in this view click Submit and check that the validation is working OK.

18

Saving your form

Greyhead.net

Adding actions to events

We now have a form that displays in the browser but it doesnt do anything except show the Form HTML in the browser. To get the form to do things we need to add some Actions. Weve already seen one, the Show HTML action we used to get the form to display. We dragged that into the yellow On Load box, also known as the On Load event. Actions and Events are the key building blocks in creating interactive forms. Actions do something; Events control when the action is run. In another tutorial well look at Actions and Events in more detail, here well keep it simple. We would like our form to do just two things: Send an email to the site admin with the contents of the form Show a thank you message to the user. We want both these actions to happen after the form is submitted so we will use the On Submit event for them.

19

Adding actions to events

Greyhead.net
In the Form Wizard, click the Events tab on the right (or the Actions tab on the left) and drag rst an Email action, then a Show Thanks Message action into the On Submit event (the yellow box).

Open the Show Thanks Message action using the same spanner icon as we used with the elements earlier. You will see a Code box like the Header Text element where you can add a thank you message:

XX Note that there is also an Add/Remove editor link to enable the Rich Text editor if you need it.

20

Adding actions to events

Greyhead.net
As with the elements you need to click the Apply tab to save the action settings before closing the modal window. The Email action Now open the Email action conguration dialogue in the same way. Notice that the dialogue is much more complicated than the Show Thanks Message dialogue. We will only look at the basic settings here.

On the General tab set Enabled to Yes. Then click the Template tab and click the Generate Auto Template button at the top of the tab to create a basic email template from the Form HTML. XX Note that this will only work after the form has been saved.

21

Adding actions to events

Greyhead.net
Now click the Static tab and notice that the rst four options are all required: To, Subject, From name and From email.

The To email option is the address you want the email sent to. Here well use a address for a site admin. XX If you want the email to go to more than one address, use a comma separated list: such as jon@example.com,jane.doe@example.org The Subject is the subject of the email; you can add any text string. The From name can be any text string. The From email should be a valid email address, with the domain matching the site domain and not the same as the To email address.

22

Adding actions to events

Greyhead.net

Now test the form

Apply any open actions and Save or Save & Close the form. First test the form in the Now you must test the form using the Test Form window. Complete the form and click the Submit button. It should submit correctly and display the Thank you message you wrote. Check the mailbox for the To email address to see if the email has been correctly delivered. This may take a ve or ten minutes to arrive (and sometimes longer). If the email doesnt arrive check the Email conguration settings: Is the To email address correct without any typos? Does the From email address match the site domain? Are the two addresses different? Is the To email address a Hotmail, Live, Yahoo or AOL address? If so try something different for testing. XXThere are more and more spam checks on emails and these settings are intended to try to avoid your email being marked as spam and possibly dropped.

23

Now test the form

Greyhead.net
If the form is working OK in the Test Form view, then you can click the Frontend View link in the ChronoForms Forms Manager to view the form with the template. The main difference here is that the template is now loaded so you should check the page layout and the validation to see if there are any CSS or JavaScript conicts that you need to resolve. Tidy up, run a nal test and your form is complete. Jon Wilkin Bob Janes 17 April 2012

24

Now test the form

Greyhead.net

The ChronoForms Book

The ChronoForms Book is the missing manual for the Joomla! ChronoForms extension. In 350 pages of clear, practical guidance it tells you everything that you need to know to create forms on your Joomla! website, email the form results and/ or save them to a database table and much more. Click here to see the full contents list, download a sample chapter or to buy a copy

Bob Janes
I am always interested in innovative web projects. I specialise in developing Joomla! based projects using ChronoForms and ChronoConnectivity to create customised web applications. I'm also available for interactive chat support to developers using ChronoForms and ChronoConnectivity. A quick message can save you hours of hunting through documents and forums. Ive also worked on Joomla component development; and on custom site functionality in Joomla! and in WordPress. Drop me a line if you think that I could help you develop your project or site with less hassle and less of your time. Bob Janes bob@bobjanes.com

25

Version history

Greyhead.net

Version history
v1.0 17 Apr 2012 rst published

26

Version history

Greyhead.net
Bob Janes is the author of the ChronoForms 3.1 for Joomla! site Cookbook published by Packt Publishing. He provides support on the ChronoEngine forums and works as a developer of custom applications (often using ChronoForms and ChronoConnectivity) for Joomla! and WordPress. Bob can be contacted at info@greyhead.net ChronoForms is a Joomla! Component for creating interactive forms including the ability to email the results, save them to a database table and much more. ChronoConnectivity is a Joomla! Component that works with ChronoForms to allow the easy display of lists of records from a database table. ChronoConnectivity and ChronoForms are published by ChronoEngine.com. This help-sheet was written for ChronoForms v4 RC3.3 and/or ChronoConnectivity v4 RC2 ChronoEngine Tutorials by Bob Janes are licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License Disclaimer To the best of our knowledge and belief the information in this tutorial was substantially correct at the time of writing. Neither the author, nor ChronoEngine.com shall have neither liability nor responsibility in respect of any loss or damage caused, or alleged to have been caused, directly or indirectly, by the information contained in this document.

27

Version history

Greyhead.net

28

Version history