Greyhead.netHow-to docs and tutorials

ChronoForms v4 : Basics 1 with Jon Wilkin

CHRONOForms

This is a first 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.

X Written with ChronoForms v4 RC3.3 v4

1 Constructing a Contact Form in v4

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 find 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:

X You’ll need ChronoForms installed to follow the rest of this tutorial which was written with ChronoForms v4 RC3.3

2 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, we’ll click that now to get a clean workspace. You’ll see a ‘screen’ icon at the top right to get back.

3 Constructing a Contact Form in v4

Greyhead.net

First, click the ‘Form Settings’ tab because it’s 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 ele-ments divided into two groups Basic and Advanced. We’ll say a bit about each of the Basic elements next even though we’ll only use a few of them in our contact form.

4 The Basic Elements

Greyhead.net

The Basic Elements

Text inputThe Text Box element is the work-horse of web forms. It is used to input a single line of text; in our Contact form we’ll 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. We’ll use it for the question/comment input in our Contact form.

5 The Basic Elements

Greyhead.net

Submit and Captcha (anti-spam)The Submit Button element is used to submit the form. You can config-ure this element to change the name of the button and to show Reset and Back buttons as well as the Submit button.

X You can use more than one Submit button in a form as a way of let-ting 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.

X The Captcha Input works together with the Load Captcha and Check Captcha actions.

HeadersThe 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.

6 The Basic Elements

Greyhead.net

User SelectionsThese 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 first and simplest of these. It is most often used to have the User confirm 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 op-tion is clicked clicking another option de-selects the first 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.

7 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.

8 The Basic Elements

Greyhead.net

Special elementsThe DateTime Picker element is a text box linked to a JavaScript calen-dar that can be used to select dates and/or times.

This is a very flexible element that can be configured in many different ways to make date and time selection simple and reliable.

X You 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 file from the form.

9 Constructing the form

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.

X You 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.

Don’t worry if you mess up the order, it can quickly be changed later.

10 Configuring elements

Greyhead.net

Configuring 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 configure 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.

11 Configuring elements

Greyhead.net

The Header Text elementClick the ‘spanner’ icon to configure the Header element. A modal win-dow will open with the configuration options.

This is one of the simpler configuration windows with only two main op-tions so it is easy to understand.

The first 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 don’t 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 we’ve typed in the header text for our form.

! To save the configuration click the Apply tab at the top right. This is important, if you don’t do this your changes will be lost!

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

12 Configuring 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 edi-tors, Tiny MCE in this case.

X The Header element is OK for short text snippets but there are some-times problems with longer text or HTML. Using a Custom Element from the Advanced Group may be more reliable in this case.

X Avoid using double straight quotes " in the Header element as they seem to cause problems, single quotes ' or curly quotes “” are OK.

13 Configuring elements

Greyhead.net

The Text Box elementThe next two boxes for the user name and email are very similar. They require a name, a label and validation setting.

As an example we’ll look at the Email Text Box element.

Click the ‘spanner’ icon to open the configuration 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.

X Name and ID entries can only use letters, numbers and underscore ‘_’ and must begin with a letter (no spaces, dashes or other special characters).

14 Configuring elements

Greyhead.net

The Label Text is the label that will appear next to this input on your form so we’ll change this. Because this will be a required input we’ll 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 configure the Name Text Box element.

Lastly configure the Message Text Area element the same way.

X You 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 won’t make any changes there in this tutorial.

15 Saving your form

Greyhead.net

Saving your form

It is time to save the form. Your changes you have made will not be finally 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.

16 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 won’t 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. We’ll 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.

17 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 specification we started out with.

Here we’ve 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.

18 Saving your form

Greyhead.net

First, we’ll 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 configuration 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.

19 Adding actions to events

Greyhead.net

Adding actions to events

We now have a form that displays in the browser but it doesn’t ‘do’ any-thing except show the Form HTML in the browser.

To get the form to ‘do’ things we need to add some Actions. We’ve 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 we‘ll look at Actions and Events in more detail, here we‘ll 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.

20 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 first an Email action, then a Show Thanks Mes-sage 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:

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

21 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 configuration 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.

X Note that this will only work after the form has been saved.

22 Adding actions to events

Greyhead.net

Now click the Static tab and notice that the first 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 we’ll use a address for a site admin.

X 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.

23 Now test the form

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 five or ten minutes to arrive (and sometimes longer).

If the email doesn’t arrive check the Email configuration 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.

X There 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.

24 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 conflicts that you need to resolve.

Tidy up, run a final test and your form is complete.

Jon Wilkin Bob Janes

17 April 2012

25 Version history

Greyhead.net

The ChronoForms Book

The ChronoForms Book is the miss-ing manual for the Joomla! Chrono-Forms 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, down-load a sample chapter or to buy a copy

Bob Janes

I am always interested in innovative web projects.

I specialise in developing Joomla! based pro-jects using ChronoForms and ChronoCon-nectivity to create customised web applica-tions.

I'm also available for interactive ‘chat’ sup-port to developers using ChronoForms and ChronoConnectivity. A quick message can save you hours of hunting through docu-ments and forums.

I’ve also worked on Joomla component de-velopment; 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

26 Version history

Greyhead.net

Version history

v1.0 17 Apr 2012 first published

27 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 Chrono-Forms 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. Chrono-Connectivity 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-No-Derivs 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 ChronoEn-gine.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.

28 Version history

Greyhead.net