Greyhead.net

ChronoForms has the built-in ability to send e-mails. Sometimes though you need something more immediate—like a text message sent to a mobile phone. This isn't a built in feature, but it's not hard to add.

Getting ready

You'll need to find a web service that will send SMSes for you. It's possible that your phone provider has a service; but for this example we'll use the API from Clickatell (http://www.clickatell.com) who claim to cover over 800 networks in more than 220 countries.

You'll need to sign up to a service and find the specific details of its API. Clickatell offers ten free credits for testing.

You'll need a simple form to test with; if you don't have one then our standard newsletter form will do perfectly well.

How to do it…

1. We are going to use the ChronoForms cURL plug-in for this recipe. This is one of the ChronoForms plug-ins that comes with the installation and is accessed from the left hand column of the Forms Manager. The cURL and ReDirect plug-ins are siblings. Both enable us to send form data to other websites. Use the cURL plug-in when only the data needs to be transferred and the ReDirect plug-in when you need to send the user to the other site as well. You usually need to send the user when they have to authorize something, for example to sign in to a payment site like PayPal.

Here, we just need to send data to Clickatell so the cURL plug-in is the one to use.

2. You can access the plug-in configuration by checking the box beside the form name and clicking the plug-in name in the left hand column. Here is the cURL plug-in configuration dialogue.
   

   We have no connection with or experience of Clickatell and they are used here as an example, not in any way as a recommendation.
   API (Application Programming Interface) is a set of functions that are made available to allow external users to interact with the service.

   

   Notice that there is a message at the top of the dialogue telling us that the cURL function was found on the server. cURL is an optional part of PHP and though most sites will have it installed, a few may not and will not be able to use this plug-in. (If this happens to you, talk to your ISP who can probably arrange to turn it on.)

   This tab—one of four in the dialog—contains a section at the top with inputs that ChronoForms has created, matching the inputs in our form. (Here "button_2" is the submit button.) Below that is a text area where we can add other data that we want to send.

3. If you click the cURL params tab and take a quick look, you will see that the top box is "Target URL" which is where we will tell ChronoForms where we want to send the data.

   With that in mind, let's get some information about the Clickatell API.

   Let's assume that we have a client who wants to receive a SMS message saying "Form submitted, check your mail now" when this form is submitted on their website. In this case we need to call the same phone number every time.

   Clickatell have a range of ways that you can connect to their service. We'll use the simplest here—connecting through a URL, their HTTP/S service. We're going to use the test instructions from their site which say:

   • Have the number you wish to send to ready in international format, for example 448311234567
   • Open your browser (for example, Internet Explorer), and type in your info in the address bar in the following sequence:http://api.clickatell.com/http/sendmsg?user=xxxxx&passwo rd=xxxxx&api_id=xxxxx&to=448311234567&text=Meet+me+at+ho me
   • The text of your message must be formatted so that + signs replace spaces between words as shown here

   We need to break that long URL up into its separate parts. The formal structure of a URL is formally defined in a document called RFC3986. Here's an example from that document:

        foo://example.com:8042/over/there?name=ferret#nose
        \_/   \______________/\_________/ \_________/ \__/
         |           |            |            |        |
      scheme     authority       path        query   fragment
   
   

   In the Clickatell URL we have the scheme and path before the ? and the query after it.

4. In the cURL plug-in dialogue put the scheme and path—http://api.clickatell.com/http/sendmsg in the Target URL box on the cURL params tab and, while you are there set the Flow control to After Email.
   

   The only reason for doing so in this case is that if the plug- in is set to Before Email it will not run unless Send Emails is set to Yes on the Form General tab.

5. Then we break the query part up into separate parameter+value pairs by splitting it at the & signs. We get this list:
   

   user=xxxxx
   password=xxxxx
   api_id=xxxxx
   to=448311234567
   text=Meet+me+at+home
   
   

   The user, password, and api_id will take the values you got when you signed up at Clickatell; the value of to is the client's phone number in international format (44 is the UK country code, it would be 1 for North America, and so on); and the value of text is the message.

   All of these values stay the same each time a form is submitted. As they have constant values, we can enter them all into the textarea part of the General tab in the cURL plug-in configuration, remembering to replace the spaces in the message with +.

   Here's an example we can use for a first test; those used previously aren't real values, so the test won't actually send a message though:

   user=greyhead
   password=mysecret
   api_id=987xx123
   to=1234567890
   text=Form+submitted+–+check+your+mail+now
   
   

   Remember to keep the message all on one line:

   

6. Set Debug to On for the plug-in so that we can see the output, save the plug-in configuration, enable the plug-in in the Form Plugins tab if necessary, and then go to the form and submit it.
7. Here's the result from submitting exactly the data used previously:



8. Now we haven't got a valid api_id for this test, so the message is not sent. But we do get an error message back from Clickatell (see the last line of the debug listing) so we know that we delivered our data successfully to their API.

How it works…

The cURL functionality is a set of PHP code that is built to allow just this kind of interaction between one computer and another over the internet using some standard protocols, in particular the HTTP POST protocol used by forms.

The ChronoForms cURL plug-in provides a simple way to use a small part of the cURL functionality with our forms and form data. There are many cURL options, most of which aren't accessible through the plug-in (see the PHP documentation at http://php.net/ manual/en/book.curl.php for much more information).

---

There are different styles of laying out both JavaScript and PHP and sometimes fierce debates about where line breaks and spaces should go. We've adopted a style here that is hopefully fairly clear, reasonably compact, and more or less the same for both JavaScript and PHP. If it's not the style you are accustomed to, then we're sorry.