ChronoForms 3.1 for Joomla! site Cookbook
上QQ阅读APP看书,第一时间看更新

Choosing e-mail addresses from a list

You don't always want to send the e-mail to the site administrator. Sometimes you want to send it to different people depending on the information in the form. One example might be customer support where some queries are technical, some are sales related, and some are about billing queries.

We'll create a form that uses a set of radio buttons to choose a department to receive the e-mail. One easy way to do this is to put the e-mail addresses in the form code but we really, really don't want them to appear anywhere on the website (even if they aren't visible to human readers, the bots will find them). So we'll also add code to look up the correct e-mail address after the form is submitted and use that in the e-mail that is sent.

Note

Note: This recipe uses some PHP and Joomla! code and is more advanced than the earlier recipes.

Getting ready

We'll use that same form again, our old friend newsletter_signup.

Open it up in the Form Editor | Email Setup tab and disable the second e-mail setup if you have one; we don't need it for the moment and that will save you sending out random messages by mistake while we are testing.

Save the form and return to the Form Manager view.

Tip

If you have made any changes to the Form HTML without using the Wizard Edit, then you may want to work on a copy, as the changes in the form will be lost.

How to do it...

  1. Open the form with the Wizard Edit again. Remember that Wizard Edit is accessed from the icon on the toolbar.

    Tip

    If the form that opens up is empty then you may have used the Form Wizard (used for creating new forms) instead of the Wizard Edit.

    Note

    ChronoForms keeps two completely separate copies of the Form HTML. One "encoded" version is used for the Wizard Edit, the other for the plain Form Editor. When you save from Wizard Edit both versions are updated, but changes in the Form Editor are not saved in the "encoded" version.

  2. When the form opens at step 1, drag a Radio Button element into the workspace above the Submit button.

    Tip

    Dragging into the workspace is sometimes a little erratic, and if the element gets misplaced you can drag it up or down inside the workspace to get it back into place. Note that depending on your browser you may need to select the green "curly arrows" icon to drag an element.

    The default RadioButton element has three buttons labeled Radio 1, Radio 2, and Radio 3. In the Properties box is a text area where you can edit these labels, and also add more buttons if you need them, each on a new line.

    How to do it...

    While you are in the Properties box change the Label element as well.

  3. Click Apply to save the updated element, then save the form. It should now look like this in the front-end:
    How to do it...
  4. That looks good. Now we need to add the code to be run when the form is submitted to add the right e-mail address.

    To do that we need to know what the name of our radio box input is. Unlike the text inputs, ChronoForms didn't show us this when we created it (it might in a future version).

    There are several ways to do this, and we're going to turn on ChronoForm's useful Debug Report to find the answer.

    Tip

    If the form that opens up is empty then you may have used the Form Wizard (used for creating new forms) instead of the Wizard Edit.

    Go back to the ChronoForms Form Manager view and open the form in the Form Editor by clicking on the title of the form you want to edit.

    On the General tab there is a group of Other Form Settings and Debug is about a third on the way down. Change the drop-down to ON and Apply or Save the form.

    How to do it...
  5. Now go back to the form; it really helps when working like this to keep the form and the Form Manager open in two browser tabs or windows. Enter some values and Submit the form.

    You should see a screen full of rather odd looking output:

    How to do it...

    Breaking this into chunks:

    • Section 1 is a "dummy" version of the e-mail that the form will send
    • Section 2 is the "thank you" page that will display if there is no ReDirect set
    • Section 3 is a series of Debug messages that track the progress of the form processing

    Message 5 in Section 3 is the $_POST Array. This shows you the values that are submitted from the form back to the server. These are the "raw materials" that we will work with, save, and process in more complex forms. Here's what we see, with some added line-breaks for clarity:

    $_POST Array: Array ( [text_2] => Testing [text_0] => test@example.com [radio0] => accounts [button_1] => Submit
    [39070f8a69c53b3579887a872c0c01d9] => 1 [1cf1] => d8b3cb29d8773a9c33002ba4bcb63a35 [chronoformname] => newsletter_signup )
    

    Note

    A little jargon: Arrays are coder-speak for a group of pairs, each pair consists of a 'key' and a 'value' and the syntax here is [key] => value.

    The first two entries in the array are the name and e-mail fields that we've been working with (notice that the name field here is text_2 rather than text_1). The third entry is the one that we want here [radio0] => accounts tells us that the "key" or "name" for our radio button is radio0.

    That's all we need from here.

    Tip

    If this was a live site, we'd go straight back and turn off Debug now, but this is a test site so we're going to leave it turned on for a while longer.

  6. Go back to the Form Editor (open the form from the Form Manager if necessary) and select the Form Code tab. You should see a page like the following:
    How to do it...

    There are three blocks here again:

    • Main onLoad/View Code contains the Form HTML with associated JavaScript and CSS - this block structures the visible form.
    • onSubmit Events Code contains code that is run after the form is submitted.
    • Extra Code contains code that is used for special purposes. Really, you can use this for whatever you want; we shall use one of these boxes for an AJAX interactive form later on.

    For now click the [+/-] link after On Submit Code - before sending email (we'll call this OnSubmit Before from now on), and a text box will open like this:

    How to do it...

    Note

    If you look at the Form HTML or OnSubmit code - after sending email boxes in the same way, you will see the results of code that we created using Wizard Edit.

  7. We're going to be entering some PHP code in here. PHP is the programming language that Joomla! is written in. If you aren't familiar with programming then some of this will look a little cryptic but you should be able to copy and paste the code and make the small edits that you need to get it to work for you.

    PHP code is marked out by PHP tags <? php and ?>; anything between these is PHP and will be "processed" by the server. Anything outside these tags, and any output from the PHP will be treated as HTML and is usually sent to the browser as part of a web page.

    So we'll start out by putting a pair of PHP tags in the box:

    <?php
    ?>
    

    We need to get the value of radio0 from the $_POST array. Joomla! provides us with a way to do this which also offers some protection from malicious users entering potentially dangerous code into our forms. Wherever we can, we'll use this Joomla! code to get our form results.

    <?php
    $radio0 = JRequest::getString('radio0', '', 'post');
    ?>
    

    Note

    In PHP, variable starting with $ so $radio0 is a new PHP variable. JRequest::getString(. . .) is a Joomla! function to get a text string result from a form (it will filter the result to remove anything that doesn't look like a text string, or that might be malicious). radio0 tells the function which result to look for and "post" where to look for it.

    There's a possibility that the user didn't select anything so radio0 will be empty, or not be there at all. We still want to send an e-mail if this happens so we'll set a default value, and it can go to the administrator for them to sort out.

    <?php
    $radio0 = JRequest::getString('radio0', 'admin', 'post');
    ?>
    

    We also need to set an e-mail for each department and we'll do this with an array where the "key" is the department name from the form, and the "value" is the e-mail address:

    <?php
    $radio0 = JRequest::getString('radio0', 'admin', 'post');
    $emails = array (
    'accounts' => 'accounts@example.com',
    'technical' => 'technical@example.com',
    'sales' => 'sales@example.com',
    'admin' => 'admin@example.com'
    );
    ?>
    

    Now we know that $radio0 must match one of the four keys so we just have to find out which. We select an array value by setting the "index" to $radio0.

    <?php
    $radio0 = JRequest::getString('radio0', 'admin', 'post');
    $emails = array (
    'accounts' => 'accounts@example.com',
    'technical' => 'technical@example.com',
    'sales' => 'sales@example.com',
    'admin' => 'admin@example.com'
    );
    $email_to_use = $emails[$radio0];
    ?>
    

    Lastly, we have to pass this e-mail to ChronoForms to use. We're going to do this in two steps. First, by creating a new entry in the $_POST array using the Joomla! code JRequest::setVar(), which is like JRequest::getString() in reverse.

    <?php
    $radio0 = JRequest::getString('radio0', 'admin', 'post');
    $emails = array (
    'accounts' => 'accounts@example.com',
    'technical' => 'technical@example.com',
    'sales' => 'sales@example.com',
    'admin' => 'admin@example.com'
    );
    $email_to_use = $emails[$radio0];
    JRequest::setVar('email_to_use', $email_to_use);
    ?>
    

    The two parameters in the function are the key and the value of the new pair.

    Note

    Note: We could simplify the last two lines into JRequest::setVar('email_to_use', $emails[$radio0]);

    Apply the form to save our code entries in this box.

  8. To tell ChronoForms to use this value we need to edit the Email Setup, so open that tab in the Form Editor. At present the Admin Email Setup looks something like the following:
    How to do it...

    We now need to switch that To field from static — that always goes to the same address — and replace it with a Dynamic To linked to the 'email_to_use' input.

    Click the red cross in the corner of the To element to delete it. Notice that the Email Setup turns red because we've removed a required element.

    Drag in a new Dynamic To element; it will go to the bottom but that is fine, as the order isn't important. Then, the Email Setup will turn green again.

    Tip

    When you click on the Dynamic To element, Chrono Forms will display a version of the form, so that you can click a field to use in dynamic element. Just ignore this screen and enter the text directly into the element.

    Now add the input name email_to_use into the Dynamic To box. Enter the string without any quotes or brackets.

    How to do it...

    Check that the e-mail is "enabled" in the Email Properties box (ChronoForms may have disabled it when it turned red), set to Yes, and Apply if you need to. Then save the form in the editor, go to the form in the Front End and submit it to test.

  9. Turn Debug on and complete the form, selecting Technical in the Radio Buttons. Here's the dummy e-mail:
    How to do it...

    And there's the e-mail address for the technical department in the To field.

How it works...

In this recipe we've ventured a little deeper into the use of ChronoForms and we've added a few lines of PHP to "do something" with the results submitted from the form.

We'll see more complex examples of this as we go further.

There is a blurry edge between ChronoForms and the core Joomla! code. You might think of ChronoForms as a window into the core. You can use it "out of the box" to do quite a lot, or you can dig deeper and do "almost anything". How far you go really is up to you — your needs, knowledge, and experience.

There's more...

We chose to use radio buttons here because they are visually clear and straightforward. If you have more than a few "departments" then a drop-down may be a more useful interface. This will work just as well.

You could also keep the To field as well as the Dynamic To. Then the e-mail addresses will both end up in the e-mail To field, so the administrator will get every e-mail and each will also go to the selected department.

Tip

You'd probably want to remove the default e-mail in this case so that the administrator doesn't get two copies.

See also

  • Chapter 12, Adding Advanced Features looks at how you can enable and disable whole Email Setups in a similar way.