ChronoForms 3.1 for Joomla! site Cookbook: 80 recipes for building attractive and interactive Joomla! forms

1. Go to the ChronoEngine website (http://chronoengine.com/) and click the Downloads link. Follow the folder tree ChronoForms | ChronoForms J1.5 Files | Component and download the current release. Right now this is ChronoForms_V3.1_RC5.5.zip.

2. Download the file to your computer. Now open your browser and go to the administrator page for your Joomla! site, for example http://www.example.com/administrator, and log in.

3. Once the Administration page is open go to Extensions | Install/Uninstall and open the Joomla! Extension Manager.

4. Click the Browse... button and navigate to the downloaded ChronoForms ZIP file.

5. Click Upload File & Install and the installation process will begin. ChronoForms is quite a large extension and it may take a little while to upload.

6. Once the installation completes you will see the following screen:

7. Congratulations, ChronoForms is successfully installed.

8. While we are in the Extension Manager window, click on the Components link and look for the Chrono Contact entry. It tells you that this version — 3.1 RC5.5 — was created on 04 Aug 2009 by Chronoman (also known as Max). This version information is important when you want to upgrade ChronoForms in the future.

9. Before we finish, click the Components | ChronoForms | Forms Management menu to go to the Forms Manager.

10. The Forms Manager is the "Control Panel" for ChronoForms and we'll be working with it more in other recipes later on.

1. Go to the ChronoForms Forms Manager and click on Form Wizard, or choose Components | ChronoForms | Form Wizard from the Administrator Menus.

The Form Wizard tab opens up looking like this:

2. There are four steps that the Wizard can help with, though we're only going to use Step 1 Design your form here. There's an empty work area with Preview and Save icons to the top left and a Toolbox to the right with a Properties box below it that is currently empty. To the top right of the image is a Cancel button in case you change your mind.

3. For our form we want a textbox for the e-mail address. Use your mouse to drag the Textbox entry from the Toolbox into the empty workspace.

4. Once you drop the textbox into the workspace, you can see a new form element. When that is clicked, the Properties box for the form element opens up under the Toolbox.

This isn't the world's easiest screen layout but it will be fine once you get used to it.

5. There are a whole row of properties that you can set, but we're only going to change one right now. Click the form element so that the Properties box is open, then go to the input marked Label and delete the Click Me to Edit text; instead type Email. Then click Apply at the bottom of the Properties box.

Although you can type into the input box in the workspace at the left, that has no effect. So, just leave it empty. You should only make changes in the Property box.

6. When you've relabeled the element, drag a Button into the workspace.

The button is automatically labelled as a Submit button. You can change this in the (much smaller) Properties box, but we'll leave it just as it is for now.

7. Now click the "blue screen" icon at the top left of the workspace to see a preview of our form.

The preview opens in a "modal" window over the working area. While this is open you will not be able to access the administrator menus or tools. The preview is shown in the following screenshot:

8. Perfect, now we just need to save it. Close the Form Preview window from the close link at the top right-hand corner, and then click the "floppy disk" icon to save the form.

9. Type a name in the box. Let's use "newsletter_signup" and click Save.

10. When you click Save, you'll be taken back to the Forms Manager, where there should now be a form in the list.

Reading across the form row, the entries are :

11. Click the publish icon now to make this form available and, after a moment, the icon should change to a green tick to show that the form is now published.

12. Go back to the Link column and click on the form link there. This will open the form in a new browser window or tab showing the form as it will appear on your website.

13. And there we have it, our first fully-functioning ChronoForms form.

You can submit it, but nothing will happen yet. We have to set up a little more code to tell ChronoForms what to do when the submit button is pressed.

1. We're going to use the Wizard Edit to add more to the existing form. Click the check box next to newsletter_signup in the Forms Manager, then click the Wizard Edit icon in the toolbar above:

2. When you open your form with Wizard Edit there's a warning message that says, Please note that any changes you made to the form HTML code in the Form edit page will be lost once you save new changes in the wizard! We've made no changes to the Form HTML so we can click the x at the top right to close the warning window.

3. Once the Wizard is open, click Step2 Choose Email(s) Settings and you will see a similar workspace, though with different entries in the Toolbox. There is also an "envelope" icon instead of the screen and an extra "garbage can" icon to delete an unwanted e-mail setup.

Notice that the Toolbox entries all relate to e-mail headers — To, From Name, Subject, Reply to, and so on. But at the moment we can't drag them into the workspace.

4. First, click the envelope icon to create a new e-mail setup. An Email Setup is a set of instructions to tell ChronoForms to send an e-mail using this particular set of headers.

Now we have an e-mail setup workspace coloured red.

5. Drag the following elements from the Toolbox into the red box in the workspace:

Two things have happened here. The Email Setup workspace box is no longer red, it's a yellow-green, and the Email Properties box now has some content.

If the workspace stays red, then you do not have the correct four elements in the workspace! Also notice that when the workspace is red the Enabled? option in the Email Properties box is greyed out.

6. We now need to add entries to each of these four boxes. Unlike the Form Design workspace where the boxes are left empty, in Email Setup they must be completed.

The preceding screenshot shows a completed Email Setup. Notice that the To and From Email boxes have valid e-mail addresses in them. If they are not valid the e-mail will fail — ChronoForms does not check these, it's up to you to get them right.

In the Subject and From Name boxes you can add any text string that you like, provided that it's not too long (the box will accept 150 characters, but a practical limit is around 50).

While you can put any valid e-mail address that you like in the From Email box, we strongly recommend that you use an address that has the same domain as your website. Many ISPs check e-mails being sent to make sure that the domains match. If they do not then the e-mail may be flagged as spam, or just dropped.

7. To finalize the Email Setup there are a few more small things to do.

Set the Enabled? drop-down to Yes, and then click Apply to save the Email Setup.

Then click the "floppy disk" icon above the workspace to save the form again.

When you click the "save" icon you will be asked the name of the form that you want to save. This field defaults to the name of the form that you were currently editing, but if you wanted to save a new form, you could change the name of the form in the input box. We will just leave the form name that we are editing and update this form.

8. Back in the Forms Manager you can see that the Emails column has changed and now has an entry that says Enabled:0 / Disabled:1.

9. So we have our e-mail setup but it is still disabled. To enable e-mails we need to open the form for editing not in the Wizard Editor but in the standard ChronoForms Editor. To do this click the newsletter_signup link (over to the left in the image):

10. There are a lot of tabs here and many settings options, but we only need to change one. On the General tab find Email the Results? and change the setting to Yes.

11. Now click the Save icon (the floppy disk) to the top right of the screen to save the Forms configuration.

Back in the Forms Manager view you can see that the Emails column now reads Enabled:1 / Disabled:0. Perfect!

12. We just need to test our form to check that the e-mail works correctly. Click the form "link" entry to open the form in a new browser window or tab; enter an e-mail address in the Email box and click Submit.

When you click Submit the form is submitted and you are left looking at an empty Joomla! page, that is unless you get an error message. We'll put a "Thank You" message on here in the next recipe.

And here's the e-mail I received after submitting. Notice that ChronoForms has built the email using the information we put into the Email Setup (I've blanked out the real e-mail address I used to send it to).

And it has taken the information submitted from the form and included that in the e-mail body. That's clever!

There's also the IP address of the submitter; you can turn this off in the Email Setup | Properties if you don't want it.

13. Congratulations! Now you have a working form that carries out an action when it is submitted. My guess is that around half of all web forms work just like this, though maybe with a few more fields.

1. From the ChronoForms Forms Manager select the newsletter_signup checkbox and click the Wizard Edit icon in the toolbar, close the warning message, and click Step 4 After Form Submission.

Again we have a different workspace. There's a new icon we'll come to later — a ReDirect URL box, a rich text editor and, down in the bottom left, some links to turn the editor on and off.

We are just going to enter a little thank you message in the rich text editor:

Put in what you like but here's the message I've used. You can also use the editor functions to make the message prettier if you like.

2. When you are done click the floppy disk icon to save the form again, then click Save on the modal window to save the form with the same name.

3. Back in the Forms Manager, click the form link to open it and submit the form. Here's what I see:

4. Mission accomplished!

1. From the ChronoForms Forms Manager select the newsletter_signup checkbox and click the Wizard Edit icon in the toolbar, close the warning message, and click Step 1 Design your form.

2. Drag a new TextBox element over from the Toolbox into the workspace and drop it near the top of the workspace. We want it before the e-mail element.

3. Click the element to open the Properties box and change the Label field to Name.

4. Apply the changes to the properties, save the form again, and open the form window.

You should now see that we have two fields in the form:

Just like that we've successfully added a second field to the form.

5. Unfortunately, when we submit it, the Email template has not been updated for us, it only shows the value of the e-mail input.

We can update this easily enough though. By now the process is familiar. Use Wizard Edit and this time go to Step 3: Design your Email(s).

Here you can see the template that ChronoForms has created for your e-mail. It has similar syntax to the "Thank You" page with {text_0} as a place-holder for the input value.

We have the same Add Field icon too.

6. Put your cursor in the text editor field and use the Add Field icon to get the place-holder for the name field; it will probably be {text_1}.

Let's make this e-mail a bit more meaningful though and enter the following text:

Dear Admin,

Just to let you know that {text_1} whose email address is {text_0} has subscribed to the newsletter.

Regards

The Example.com Website team

7. Save the Form again, submit it, and check the e-mail that is sent. Here's what I received:

Beyond this the world is your oyster; you can construct a fully customized e-mail with as much HTML as you like.

1. From the ChronoForms Forms Manager select the newsletter_signup checkbox and click the Wizard Edit icon in the toolbar, then close the warning message. This time go to Step 4 - After form Submission.

2. In the Redirect URL box, just type index.php or, if you prefer, http://example.com/index.php (but using your domain name in place of example.com).

3. Save the Form here, go back to view the form in the browser, and submit it. Now, instead of the "Thank You" page we are redirected to the site home page. You could choose to write a "Thank You" page as an article on your site, or take the user to some other page that you think might be relevant or interesting to them.

1. Open the ChronoForms Forms Manager in your browser. Notice that towards the right of the Toolbar there is a group of three icons labeled Backup Form, Backup Forms, and Restore.

2. Next to the name of each form in the Forms Manager list is a checkbox that we use to select forms for actions like Backup. Check the box by newsletter_signup, and then click the Backup Form icon in the toolbar.

3. The Save File dialogue from your browser will open and you can save the form backup file in a convenient local folder.

4. Now let's restore the form back into ChronoForms again. This will create a second form with the same name which is a potential problem, but we'll sort that out.

Click the Restore Form icon in the toolbar and you'll see a new screen:

5. Click the Browse... button, navigate to the newsletter_signup.cfbak file that you just saved, and click the submit file button to restore the form.

6. When the form is restored you are returned to the Forms Manager; there is a System Message saying Restored Successfully and there is a new entry in the Forms list. However, the new entry is almost identical to the previous one.

ChronoForms can tell the difference between these two forms here because they have different Form IDs (here it is 1 and 3; yours may be 1 and 2). However, when the forms are in use on your site the names are used to distinguish them, not the IDs; so having two forms with the same name can be a real problem.

7. You can change the name by using Wizard Edit and resaving with a different name, or you can click the Form name link to open the Form Editor, change the name in the first box in the General tab, and resave the form.