Before we get started it’s important to note that widgets are not a standard EE add-on type. To use them you first need to install the open source dashEE module which is a complete alternate dashboard with drag-and-drop functionality as well as saved layouts and a handful of other useful features. The module comes standard with about 10 included widgets but the true power lies in the ability to create your own custom widgets. Once created you can then distribute them either as stand alone widgets or package them with your modules to add extra functionality to your existing code.

Getting Started

Just like other EE add-ons, Widget file names are always preceded with wgt. and then the name of your file and followed by .php. In our example we’re going to build a widget that displays the most recent tweets from a selected Twitter feed. So if the name of our widget is Tweets then our file name will be wgt.tweets.php.

Widgets also require a language file. If the widget is being packaged with a module then you can use the modules language file. But if the widget is being distributed on it’s own you will either have to instruct the user to use dashEEs or include a language file with your widget. Each widget requires two language variables that follow your chosen naming convention: wgt_tweets_name and wgt_tweets_description. These variables are important to remember because they are used when displaying your widget in the widget listing of the module.

class Wgt_tweets
{
     public $title;
     public $settings;
     public $wclass;

     private $_EE;

     /**
      * Constructor
      */
     public function __construct()
     {
          $this->title      = 'Tweets';
          $this->wclass     = 'eedefault';

          $this->_EE        =& get_instance();
     }
}

The code above shows the beginning of our widget file. Following the standard EE add-on naming conventions, our class name will always begin with Wgt_ and be followed by our file name which in this case is tweets. Each widget file should have at least two public class variables defined: title and wclass. The title variable is used to display the name of your widget in the widget title bar (across the top of your widget) and wclass is a placeholder for any additional CSS class names you wish to assign to your widgets container div. You can also add a settings variable if your widget has settings but we’ll discuss that later in the post. Beyond those three you will likely want a variable for the EE object and then any additional variables that you choose.

Index Method

The only real required method within your widget file is index(). This is the method that gets called by dashEE when a user has installed your widget. After loading the widget file dashEE calls the index method and packages it’s return value within the CSS wrappings of a widget and puts it together with the other widgets to assemble the dashboard. So this method is required and it’s expected to return an HTML string. Back to our example, we’ll be using the Twitter API to get the most recent tweets from a chosen Twitter user for display and then returning them as formatted HTML.

public function index()
{
     $tweet_count    = 5;
     $twitter_user   = 'chrismonnat';
     $twitter_url    = 'https://api.twitter.com/1/statuses/user_timeline.json?screen_name=' . $twitter_user . '&count=' . $tweet_count;

     $ch = curl_init();

     curl_setopt($ch, CURLOPT_URL, $twitter_url);
     curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
     curl_setopt($ch, CURLOPT_HEADER, 0);

     $twitter_data = curl_exec($ch);

     curl_close($ch);

     $tweets = json_decode($twitter_data);

     $display = '';
     foreach($tweets as $tweet)
     {
         $display .= '<p>' . auto_link($tweet->text, 'url', TRUE) . '</p>';
     }

     return $display;
}

That’s it, we’re done. For the sake of testing our example go ahead and add the two language variables to the dashEE language file and upload the widget file to the widgets directory of the dashEE module. Click the Widgets button and you should see Tweets listed. Click Install and you should see the widget added to your dashboard.

Permissions

One topic that has caused some confusion is permissions. Obviously if a members group doesn’t have permission to access a given module then they shouldn’t be able to access that modules widgets either. To solve this problem there is an additional method you can add to your widget file called permissions(). For our example we only want Super Admins to have access to this widget so we’ll check the users group and return FALSE if they are not a Super Admin.

public function permissions()
{
     if($this->_EE->session->userdata('group_id') != 1)
     {
          return FALSE;
     }

     return TRUE;
}

A widgets permissions method is called every time the widget is loaded which ensures as a members or modules settings/permissions change the dashboard will be adjusted appropriately. You can do whatever permission checking in this method you wish, all dashEE expects in return is a boolean true if the user should be able to access the widget or false if they shoudln’t. While it is recommended that you include a permissions method with your widget it’s not required.

Widget Settings

Back to our example, the widget we have created is functional but not necessarily usable if the user has to modify the code every time they want to change the Twitter account they want to watch. To assist with this we can add a settings_form() method to our widget file to allow the user to modify the widgets settings from within the dashboard.

public function settings_form($settings)
{
     return form_open('', array('class' => 'dashForm')).'

        <p><label for="username">Twitter Username:</label>
        <input type="text" name="username" value="'.$settings->username.'" /></p>

        <p><label for="num">Number of tweets:</label>
        <input type="text" name="num" value="'.$settings->num.'" /></p>

        <p><input type="submit" value="Save" /></p>

        '.form_close();
}

If your widget file has a settings_form method then an additional icon will be displayed when users mouse over it’s title on the dashboard. When clicked dashEE calls the settings_form method for the widget in question and displays it’s return value within the widget. It’s expected that this method return a form containing the settings that you want to allow the user to change.

For our example that’s going to be the Twitter username and the number of tweets the widget should display. It’s worth noting that it’s not necessary to specify the form action because the module will handle it’s submission via ajax and as for field names those are up to you. Just remember what you named your form fields because you will use those same names when referencing those settings back in the index method.

When adding settings to your widget it’s also important to declare default values for the settings in the widget constructor so your code has something to go off of when initially installed.

/**
 * Constructor
 */
public function __construct()
{
     $this->title      = 'Tweets';
     $this->wclass     = 'eedefault';

     $this->settings = array(
          'username' => 'chrismonnat',
          'num'      => 5
          );

     $this->_EE        =& get_instance();
}

Now that we have our settings_form method squared away we can update the index method to reference our newly saved settings. dashEE saves all widget settings as a JSON encoded value along with the widget in the DB and that value is then decoded and passed to the index method through the $settings variable as an object. To learn more about settings you can reference the wgt.feed_reader.php and wgt.blank.php widget files in the Widgets directory as both have settings of their own or refer to the documentation.

public function index($settings = NULL)
{
     $tweet_count   = $settings->num;
     $twitter_user  = $settings->username;
     $twitter_url   = 'https://api.twitter.com/1/statuses/user_timeline.json?screen_name=' . $twitter_user . '&count=' . $tweet_count;

     $ch = curl_init();

     curl_setopt($ch, CURLOPT_URL, $twitter_url);
     curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
     curl_setopt($ch, CURLOPT_HEADER, 0);

     $twitter_data = curl_exec($ch);

     curl_close($ch);

     $tweets = json_decode($twitter_data);

     if(isset($tweets->error))
     {
          $display = '<p>' . $tweets->error . '</p>';
     }
     else
     {
          $display = '';
          foreach($tweets as $tweet)
          {
               $display .= '<p>' . auto_link($tweet->text, 'url', TRUE) . '</p>';
          }
     }

     return $display;
}

That’s it, you’ve created your first dashEE widget. Feel free to download the completed code to refer to for help. Hopefully this has peaked your imagination and gotten you thinking about other cool things you can develop for dashEE. Visit the Widget Directory to see what other developers have created or submit your own widgets for others to download. As always post a comment with any questions or problems.

Wufoo users will be able to access their forms, fields, entries and reports all from within the EE control panel. The module ships with a full featured control panel interface (see video above), an accessory so you can access your form data anywhere from within the control panel, a custom fieldtype for relating your Wufoo forms with channel entries, template tags for displaying forms and entries on your website and dashEE compatible widgets so you can access your forms and reports right from your EE dashboard.

Visit devot-ee.com for purchase information or check out the documentation to learn more.

Not Just Any Old Framework

There are A LOT of open source PHP frameworks on the web today. Some of them are pretty nice tools and some of them aren’t. When evaluating a framework you need to look at several factors: community, documentation, features, support options and learning curve. Depending on your individual requirements you might have some additional criteria but I think that’s a decent baseline. Let’s see how CI stands up:

Community

Last look at the forums puts registered members at 190,000. Now that’s not necessarily active users, but that’s the number of developers who thought enough of the framework to get a forum account and join in on the conversation. EllisLab places a very high premium on their developer community and a number of the additions in 2.0 were added at their request.

Documentation

I have played around with a number of different PHP frameworks and you will be hard pressed to find a framework with better documentation than CI. The users guide is complete, easy to understand and up to date with all the latest bells and whistles. Any PHP developer with a basic understanding of object oriented programming (OOP) should be able to pick things up pretty easily.

It’s worth noting that with the release of 2.0 some new sections of the users guide are still being fleshed out, but there is enough there to help get you started.

Features

This is the true question: “can the framework do what I need it to do?” This question really depends on what it is you need it to do. But CI has most of the standard framework features including model view controller (MVC) architecture, database abstraction, form validation, session handing, error handling, flexible/scalable architecture and libraries to handle tasks like uploading files, displaying event calendars, implementing carts for e-commerce sites and much more. If that’s not enough CI also lets you add any additional functionality you want/need by building your own custom library or extending core libraries that are already there.

Support Options

So you invest all this time and effort into learning a framework and building your business around it, what do you do if things suddenly stop working? While CI doesn’t offer any kind of commercial support, the community is full of folks on the forum waiting to lend a hand when necessary. There are also a number of bloggers out there who share their CI knowledge and can be tapped for help from time to time.

The other thing worth mentioning here is that CI is backed by a successful commercial company in EllisLab (makers of ExpressionEngine CMS). So it’s a pretty safe bet that it’s not going anywhere anytime soon.

Learning Curve

We’re all on a timeline, so how long will it take to get up to speed? As I mentioned under documentation, CI is very well documented and has an active and vibrant community. With that said, anyone with a fair understanding of OOP should be able to pick things up pretty quickly.

New to Version 2.0

So now that I have your attention, let’s take a look at the exciting new additions to CI in version 2.0:

2 Flavors: Core and Reactor

As I mentioned above, CI is backed by a commercial company and is used by that company to develop their commercial products like ExpressionEngine and MojoMotor. That means that the development of the framework was limited to the needs of their products and the community got a little frustrated feeling that the development of the framework had stalled over time. In true EllisLab fashion they listened and in version 2.0 have released two different lines of development: Core and Reactor.

You now have the option of working with CI Core (maintained by EllisLab) or CI Reactor (maintained by the community). Core is the version of CI that EllisLab uses and will only change when they need to make a change for their products. This version should be used by those looking for true stability and backward/forward compatibility. Reactor, on the other hand, is maintained by a team of community engineers who collectively monitor community needs/wants and incorporate new features on a more frequent basis.

Since all changes made to Core will be incorporated into Reactor and that Reactor will be the more active of the two code bases it’s recommended that everyone use Reactor from this point forward.

PHP5 Support

A common point of contention with previous version of CI was that it wasn’t native PHP5 meaning the framework was backwards compatible with PHP4 and certain PHP5 features didn’t work or were not used. With the release of 2.0 this is no longer the case. PHP4 is no longer supported and you must be running PHP 5.1.6 or higher in order to use the framework. So feel free to start taking advantage of the OOP improvements of PHP5.

Packages

Distributing code for reuse or releasing complex libraries (for things like authentication) to the community has always been a somewhat clunky process. You would typically need to copy and paste certain files into certain places within your install in order for everything to work correctly. Config files in the config folder, libraries in their respective folder, etc. CI 2.0 does away with this issue by introducing a new way of collecting and distributing code called packages.

Packages are similar in theory to modular development in that all the resources you are distributing are self contained. All packages will have their own libraries, models, helpers, config, and language files collected in their own directory which can then be placed into the application/third_party directory of the framework for use. This provides developers with a much easier way of sharing/releasing code for use by the community. This also opens the doors for more module based application development with CI.

Drivers

In previous versions of CI there hasn’t been an elegant way of creating classes that all share a common parent class and not their sibling classes (handy in certain situations). You can now accomplish this with a new type of library called a driver. Drivers allow you to create a parent class with unlimited child classes that have no access to their siblings (for things like DB abstraction). This is a nice architecture for providing the same type of functionality only using different tools or implementation methods.

Along with being able to create your own drivers, CI 2.0 identifies three drivers in the documentation: Cacheing, Database and Javascript.

Javascript Library

Saving the best for last, the item I was most excited about with this release was the Javascript Library. CI 2.0 now gives you the ability to plug your favorite javascript framework into CI using drivers so you can incorporate javascript into your apps more easily. jQuery is being distributed with the framework by default but you can be sure there will be other drivers released shortly for other javascript frameworks.

Upgrading

So far this post has been mostly about what’s new and exciting in version 2.0 but there have also been some changes to the framework that might trip up seasoned developers and those of you looking to upgrade from an earlier version. First and foremost, all CI core classes are now prefixed with CI_. This means that all controllers, models, etc. now need to extend CI_Controller, CI_Model, etc. respectively. You will want to be sure to update your code accordingly when upgrading to version 2 (this already tripped me up once).

Second, some old features and functionality have finally been removed for good like scaffolding, plugins and the validation library. Plugins never really gained much traction with CI developers and have been deprecated for some time now. The CI core CAPTCHA plugin has been converted to a helper and any plugins you have developed should be converted to helpers also. The validation library, which has been replaced for a while now by form_validation, is gone. So if you have been putting off updating your code to use the new form_validation library now is the time to do it.

Finally, a number of improvements have been made to the encryption library which will prevent you from decrypting data that you have encrypted with a previous version. To deal with this, you will have to run an update on your data using the new encode_from_legacy() method which will decode your data and return a re-encrypted string using the new method for storage.

Those are the big things to look out for when upgrading from a previous version. Visit the users guide for complete upgrading instructions.

Is that it?

This is just a quick list of my top 5 changes/additions to the framework that have been released in 2.0. There’s a lot more where that came from like new cache drivers with APC, memcached, and file-based support, new security library and over 50 bug fixes. You can see the complete list of what’s new in the change log. So what are you waiting for? Take CodeIgniter 2.0 for a spin today!

What is Forrst?

For those unfamiliar with the site, Forrst is a private community for web designers and developers. A place where we can go and ask questions, request critiques, share ideas and seek inspiration. Each user has a profile and can create posts. Posts are divided into 4 categories: questions, snaps, links and code. If posting isn’t your thing, you can respond/comment on other peoples posts contributing your knowledge and experience to the community.

The site revolves around a forum architecture where users can post interesting content/questions and other users can comment or contribute to the conversation. I’ve never really participated in forums before but there is something about Forrst that has me hooked. Not sure if it’s the sites focus or just that the site isn’t inundated with tons of users yet, but I find myself checking in several times a day and contributing when I have something useful to add.

Although Forrst is mostly about posts it’s important to note that there’s more to this community than just sharing content. They have partnered with AppSumo to offer special software package deals to members, users can create their own forrst.me profile pages and there are plans for a job/gig board in the near future. With these and other planned features Forrst is quickly becoming the place to be for designers and developers on the web.

How do I join?

I think One of the secrets to the sites success is that not just anyone can join. Each month existing members get a certain number of invitations based on their participation in the community (max 5 per month I think). Members then browse through those people who have applied for membership and invite those who they feel have something to contribute to the community. The interesting thing here is that your participation in the community then has an impact on the member who invited you. This forces members to be somewhat choosey about those who they extend invites too. It’s an interesting approach to a pretty common social networking feature that I think helps contribute to a great community of web workers.

If you would like to become a Forrst member, visit http://forrst.com and fill out the membership form. For those of you that are already members, share what you like/dislike the most about Forrst in the comments below.

What’s it about?

PHP5 Social Networking by Michael Peacock is a complete detail packed reference on how to build your own social network. Weighing in at over 400 pages this book isn’t a quick read but it has a wealth of information for those people looking for answers to common social network construction questions. Everything is covered from user profiles and groups to activity streams and events. You will even construct your own API.

The author starts off deconstructing a handfull of popular social networks down to their most basic features and functions. He then puts together a list of the features they all have in common and that becomes the feature list of the network you will build throughout the book. From that point on the author walks  you step by step through the creation of your own PHP framework and social network for dinosaur owners (yeah, I said dinosaurs). Finally, the book wraps up with some sections on hosting and maintaining your site as well as marketing it to your users.

Pros and Cons

I could have really used this book a year or two ago when I first started building myScoutPath. Everything is here to get you well on your way to a fully functioning social network with all the bells and whistles. The author does a good job at walking the reader through each solution and what they can do to improve them further. The examples are also clear enough where you can take what you learn and implement it with whatever framework or architecture you choose.

If they could improve anything I would say cut down on the code samples a little bit. Complete code libraries are printed throughout the book and I think it makes it unnecessarily big and potentially overwhelming to some. Maybe just provide excerpts from libraries within the book; users can view the complete source code later on if they wish anyway.

I don’t recommend sitting down and reading this book cover to cover unless you’re in for a nap (as with any technical book). Seek out the sections that you’re curious about the most and dig in. There’s a little something for everybody.

Background

For those of you who don’t know, Twilio is a web service API that empowers programmers with the ability to make phone calls and send SMS text messages programmatically. I first came across the service a while back and have been keeping an eye on it ever since because I think it has a lot of potential uses in modern web applications. In the past, having your application make a phone call used to entail a lot of programming and hardware overhead ($$$). Twilio makes it as simple as one single API call (that doesn’t break the bank) and you’re done.

In this post I’m going to be building a sample application to illustrate some of what Twilio is capable of. Have you ever used a website or other service that required you to confirm your phone number by receiving a call and then entering a code given to you over the phone? Well that’s what we’re going to build. The concept is that a user fills out a generic registration form on your site and includes their phone number. Upon submission we will leverage Twilio to call the user and recite a 4 digit confirmation code that they will then have to enter in step 2 of the registration process. Upon validating the entered code from step 2 we will either send the user a SMS text message confirming a successful activation or display an error.

For the purposes of this example I am leveraging the CodeIgniter framework simply for the sake of development speed. The code that actually interacts with the API can easily be transplanted into any application and still work. When it comes to interacting with the API, Twilio has a number of client libraries to choose from. Our weapon of choice is PHP, so I will be using the PHP client library.

To make things a little easier I’m providing two downloads, one is the complete source code with all the code included. The other is just the framework preconfigured with the necessary libraries and helpers. This way, if you want to follow along, we won’t have to waste a lot of time setting up and configuring CodeIgniter.

Step 1 – Get a Twilio Account

Before you can access the Twilio API you first need to create an account to get access information. You typically have to pay to use Twilios service, but they do provide a free trial that comes with $30.00 worth of credit which you can use for the purposes of this example.

Visit https://www.twilio.com/try-twilio and fill out the provided form.

Your account dashboard is a collection of all of your account information in one easy to understand and access place. This is where you will find your Account SID and Auth Token. These are the two values you will need in order to make API requests. The dashboard also shows your account balance along with a rough calculation as to how that dollar amount translates into API requests. Your developer sandbox information is also displayed here, however we won’t be doing anything with the sandbox in this example.

The other thing you will need to do before continuing is to setup an outgoing called ID number within Twilio. For obvious reasons you can’t just go placing calls and sending text messages from any old number. You first need to enter and confirm a caller ID number within your account and then you can use that number when making API requests.

OK, so now that you have your API access information and have setup your caller ID your ready to jump in and get coding.

Step 2 – Setup

If you have not done so already, download a copy of the source code (blank or complete) and unzip the archive onto your desktop. For our registration example you will need to create a database and update CodeIgniters database settings (/application/config/database.php) with the appropriate access information. Once you have created your database, use the following SQL statement to create the one table we will be using.

CREATE TABLE `users` (
`id` int(10) unsigned NOT NULL auto_increment,
`fname` varchar(50) NOT NULL,
`lname` varchar(50) NOT NULL,
`email` varchar(200) NOT NULL,
`phone` varchar(12) NOT NULL,
`confirm_code` varchar(4) default NULL,
PRIMARY KEY  (`id`)
) ENGINE=MyISAM AUTO_INCREMENT=1 DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;

Now that you have created your database and updated the code you can upload everything to your development environment. You will notice that if you bring up the application in a browser you will most likely get an error. That’s because we haven’t created our default controller yet, but that’s the next step.

Step 3 – Create the Controller

Now that we’re up and running with our code and database we can get to coding. First thing to do is create a new controller called register.php in /application/controllers. When a user first visits our application we want to display our registration form so let’s setup our controller to do that by default.

class Register extends Controller
{
private $_account_sid = '';
private $_auth_token  = '';
private $_from_phone  = '';

public function __construct()
{
parent::__construct();

require_once(APPPATH . 'libraries/twilio.php');
}

// ------------------------------------------------------------------------

/**
 * Display app registration form.
 *
 * @access public
 * @return void
 */
public function index()
{
$temp_data = array(
'page_title' => lang('application'),
'content_main' => $this->load->view('register/index', 0, TRUE)
);

$this->load->view('_layouts/default', $temp_data);
}
}

The above code leverages CodeIgniters default controller function index() to automatically display our registration form when a user first visits our application. Now we need to create our registration form view file. Create a new folder in /application/views called register and a new file in that folder called index.php.

<h1><?php echo lang('application'); ?></h1>
<?php echo display_form_error(validation_errors()); ?>

<?php echo form_open('register/confirm'); ?>

<p><label for="fname">First name: <em>*</em></label>
<input type="text" name="fname" id="fname" value="<?php echo set_value('fname'); ?>" /></p>

<p><label for="lname">Last name: <em>*</em></label>
<input type="text" name="lname" id="lname" value="<?php echo set_value('lname'); ?>" /></p>

<p><label for="email">Email address: <em>*</em></label>
<input type="text" name="email" id="email" value="<?php echo set_value('email'); ?>" /></p>

<p><label for="phone">Phone number: <em>*</em></label>
<input type="text" name="phone" id="phone" maxlength="12" value="<?php echo set_value('phone'); ?>" /></p>

<p><input type="submit" value="Register now" /></p>

<?php echo form_close(); ?>

This view file contains just a simple four field registration form the user will complete to begin the registration process. Save and upload your changes and when you visit the application in a browser you should see the following form displayed. But before we go much further be sure to update the class variables at the top of the controller with your Account SID, Auth Token and caller ID number. Please note, the caller ID number should start with a plus sign (+), include the country code and have no hyphens.

Step 4 – Access the API

We now have our controller and registration form. You may notice however that when you submit the registration form nothing happens. The form is looking for a controller function called confirm(). This function will begin our user registration process by validating the form input, generating the users confirmation code and contacting the Twilio API to call our user and recite the code. Let’s go ahead and create this function now in our controller.

public function confirm($call = TRUE)
{
$this->load->library('form_validation');

$this->form_validation->set_error_delimiters('<li>', '</li>');

$rules = array(
array('field' => 'fname', 'label' => 'first name', 'rules' => 'trim|required|htmlentities'),
array('field' => 'lname', 'label' => 'last name', 'rules' => 'trim|required|htmlentities'),
array('field' => 'email', 'label' => 'email address', 'rules' => 'trim|required|valid_email|htmlentities'),
array('field' => 'phone', 'label' => 'phone number', 'rules' => 'trim|required|htmlentities'),
);

$this->form_validation->set_rules($rules);

if($this->form_validation->run())
{
// generate random 4 digit confirmation code
$confirm_code = rand(1000,9999);

// add new user to DB
$user_data = array(
'fname' => $this->input->post('fname'),
'lname' => $this->input->post('lname'),
'email' => $this->input->post('email'),
'phone' => $this->input->post('phone'),
'confirm_code' => $confirm_code
);

$this->db->insert('users', $user_data);
$user_id = $this->db->insert_id();

if($call)
{
// make call request to Twilio
$twilio = new TwilioRestClient($this->_account_sid, $this->_auth_token);
$result = $twilio->request('2010-04-01/Accounts/' . $this->_account_sid . '/Calls', 'POST', array('From' => $this->_from_phone, 'To' => $this->input->post('phone'), 'Url' => site_url('register/handle_call/' . $user_id)));
}

// display confirmation form
$page_data = array(
'user_id' => $this->db->insert_id()
);

$temp_data = array(
'page_title' => lang('application'),
'content_main' => $this->load->view('register/confirm', $page_data, TRUE)
);

$this->load->view('_layouts/default', $temp_data);
}
else
{
// display form errors
$this->index();
}
}

The majority of this code should be pretty self explanatory (for those familiar with CI) but let’s review just to be safe. The first 13 lines are all about validation. We are using CodeIgniters form_validation library to validate our form input and ensure we have valid data. If there are any errors we display the form again with error messages. On line 19 we create a random 4 digit number that we will use as our confirmation code. This is the code we will pass to Twilio to recite to our users and then test for in step 2 of our process. This will be stored in our database along with our other user data. Lines 21-31 handle the database insertion for our user record using CIs active record library. 33-38 are where we contact the Twilio API and make our request to call the user (I’ll review these lines in a moment). The remainder of the function displays step 2 of our registration form which is just a single field asking the user to enter their confirmation code. Before we forget let’s create this new view file called confirm.php in /application/views/registration.

<h1><?php echo lang('application'); ?></h1>

<h2>Confirm Your Identity</h2>

<p>You will receive a phone call shortly providing a 4 digit confirmation code.
Please enter that code below and click <strong>Confirm</strong>.</p>

<?php echo display_form_error(validation_errors()); ?>

<?php echo form_open('register/confirm_code'); ?>

<input type="hidden" name="user_id" value="<?php echo $user_id; ?>" />

<p><label for="confirm_code">Confirmation code: <em>*</em></label>
<input type="text" name="confirm_code" id="confirm_code" maxlength="4" value="" />
<input type="submit" value="Confirm" /></p>

<?php echo form_close(); ?>

As I mentioned above, lines 33-38 are where we actually make our API request to Twilio.

if($call)
{
// make call request to Twilio
$twilio = new TwilioRestClient($this->_account_sid, $this->_auth_token);
$result = $twilio->request('2010-04-01/Accounts/' . $this->_account_sid . '/Calls', 'POST', array('From' => $this->_from_phone, 'To' => $this->input->post('phone'), 'Url' => site_url('register/handle_call/' . $user_id)));
}

The first thing we do here is determine if we need to make the call or not by checking the $call variable passed to the function. I put this in here to avoid making additional API calls if the user enters a wrong confirmation code (this will make sense later on). Next we create a new instance of TwilioRestClient which is the PHP client library and pass it our Account SID and Auth Token for authentication. Using our new TwilioRestClient object, we make a request to the API using the request() function. This function takes 3 arguments: the path to the API method your calling, the type of request your making (POST, GET, etc.) and any data you are passing along to the API (as an array).

Something to make note of here is the path to the API method we are passing. In a rather odd turn of events, each API call must include your Account SID. I find this rather odd and verbose but alas it is required. There are ways to make this easier to use within your code by making a minor modification to their library, but I chose to keep things just the way they provide for the purposes of our example.

So we are calling the /Accounts/Calls API method and passing it a “From” phone number, “To” phone number and “Url” to handle the call. The “From” number is the phone number the call will be made from (your Twilio called ID number). The “To” number is the number Twilio will be calling. It’s worth noting that this number must inclue the country code and contain no hyphens. The code should probably include some sanitization to ensure this, but I kept it out for simplicity. Finally the URL to handle the call is where Twilio will look for instructions on what to do for this call. This is where we have to provide it with instructions using TwiML or Twilio Markup Language.

Step 5 – TwiML

There is an entire section of documentation dedicated to TwiML, so I don’t intend on spending a tremendous amount of time on it. Suffice it to say it is the XML format that Twilio expects when looking for instructions on what to do when placing a phone call. You have several options to choose from but all we care to do is place a call and read a script. Let’s go ahead and create a new function in our controller called handle_call() to generate the necessary TwiML.

public function handle_call($user_id = NULL)
{
if(!is_null($user_id))
{
$user = $this->db->get_where('users', array('id' => $user_id))->row();

// put spaces between code so Twilio will pronounce digits instead of the complete number
$confirm_code = '';
for($i=0; $i<=3; ++$i)
{
$confirm_code .= $user->confirm_code[$i] . ' ';
}

$script = 'Hello your confirmation code is ' . $confirm_code . '.';
}
else
{
$script = 'Im sorry but your account could not be verified.';
}

$twilio = new Response();
$twilio->addSay($script, array('loop' => 2));
$twilio->Respond();
}

The above code basically creates the following XML document.

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
     <Say loop="2">Hello your confirmation code is XXXX.</Say>
</Response>

The first thing we do here is find our user based on ID in the DB. Next we take their confirmation code and put spaces between the numbers. Without doing this Twilio will pronounce the number as a complete number instead of digit by digit which would be a bummer for our users. Finally we put it all together in a script and call the addSay() function adding a loop attribute of 2 to make sure Twilio repeats the message twice. If you were to visit this function in your browser (/registration/handle_call) you would hopefully see the XML I provided above as an example.

Step 6 – Confirmation

We now have the majority of our application in place. The only thing we’re missing is the processing code to handle step 2 of our registration process. Let’s create a new function in our controller called confirm_code() to handle the final bit of validation.

function confirm_code()
{
$this->load->library('form_validation');

$this->form_validation->set_error_delimiters('<li>', '</li>');

$rules = array(
array('field' => 'confirm_code', 'label' => 'confirmation code', 'rules' => 'trim|numeric|max_length[4]|htmlentities'),
);

$this->form_validation->set_rules($rules);

if($this->form_validation->run())
{
$user = $this->db->get_where('users', array('id' => $this->input->post('user_id')))->row();

if($user->confirm_code == $this->input->post('confirm_code'))
{
$this->db->update('users', array('confirm_code' => NULL), array('id' => $user->id));

// make SMS request to Twilio
$twilio = new TwilioRestClient($this->_account_sid, $this->_auth_token);
$result = $twilio->request('2010-04-01/Accounts/' . $this->_account_sid . '/SMS/Messages', 'POST', array('From' => $this->_from_phone, 'To' => $user->phone, 'Body' => 'Hi ' . $user->fname . ', Thanks for activating your account.'));

$content_main = $this->load->view('register/account_activated', 0, TRUE);
}
else
{
$content_main = $this->load->view('register/account_error', 0, TRUE);
}

$temp_data = array(
'page_title' => lang('application'),
'content_main' => $content_main
);

$this->load->view('_layouts/default', $temp_data);
}
else
{
$this->confirm(FALSE);
}
}

The above code processes the confirmation code submission and checks to see if our user entered the correct code or not. If correct, we send the user a SMS text message using Twilio and display a view called account_activated.php. If incorrect, we simply display a view called account_error.php. Let’s create those two views now in /application/views/register.

<h1><?php echo lang('application'); ?></h1>

<p>Your account has been activated.</p>

<h1><?php echo lang('application'); ?></h1>

<p>Your account could not be verified at this time.</p>

The code for sending the text message is very similar to the block we used to make the phone call above.

$twilio = new TwilioRestClient($this->_account_sid, $this->_auth_token);
$result = $twilio->request('2010-04-01/Accounts/' . $this->_account_sid . '/SMS/Messages', 'POST', array('From' => $this->_from_phone, 'To' => $user->phone, 'Body' => 'Hi ' . $user->fname . ', Thanks for activating your account.'));

This time we are requesting the /SMS/Messages API method to send a text message and passing along “From”, “To” and “Body” as parameters. Just like above “From” is the phone number we are sending from (our Twilio caller ID number), “To” is the number we are sending to and “Body” is the actual content of the text message. It’s worth mentioning that text messages don’t require any TwiML instructions, only phone calls.

And there you have it. If you save and upload your changes you should now have a functioning example. Enter your phone number in the phone number field of the registration form (being sure to include the country code and no hyphens) and hit submit. You should shortly receive a phone call reciting your confirmation code. Enter that code in the confirmation code form and submit. You should then see the success message and receive a congratulatory text message.

Debugging

When I was first building this app I was not having much luck with placing phone calls. Twilio would call me but say there was a system error and then hang up (very frustrating). Come to find out that I had my site password protected and it couldn’t get to the handle_call() function for the TwiML instructions. The point of this story is I wouldn’t have been able to figure out what the problem was without the Twilio Debugger available through your Twilio account.

Conclusion

This is obviously not a complete and well polished application but it does illustrate some of what Twilio is capable of. Some possible enhancements to this code could include adding a country code drop down menu to the registration form so the user doesn’t have to enter it as part of their phone number, better phone number validation to ensure processing and maybe e-mail integration since we are collecting the users e-mail address. Feel free to experiment on your own and let me know how you make out by leaving a comment.

I know this was a long post but thanks for sticking with me. To learn more about what Twilios capable of, be sure to visit their documentation and implementation gallery.

Now before we get started, you might have noticed a bit of sarcasm in the opening of this post about whether this type of functionality is really a good thing. Personally I place this feature in the same category as pop-up windows and those really annoying flash ads that start talking to you after loading (I hate those things). However, I wanted to do a post on this service because it’s really a pretty slick web app and it’s made by the same people that brought us SlideDeck which is totally cool! So in an attempt to give them the benefit of the doubt, and showcase a very well put together interface, I decided to take a swing at writing an impartial review of the service. Here goes nothing.

Initial Setup

To get started you will need an account. Hello Bar is currently in a private beta, so signing up on the homepage will only get you so far. I have a hand full of invites to share if anyone is interested (just leave a comment).

After logging in for the first time you come to a dashboard of sorts that will eventually display all of your bars for management. The interface leaves little to the imagination as to what you need to do to get started with your first bar. Click the “Create New” button and you are served with the hello bar editor.

The bulk of this service revolves around this bar editor screen. This is where you actually construct your hello bar and it’s loaded with options. You can either create a static bar with text you enter manually or populate the bar dynamically from an RSS feed (you can even configure it so you can update your bar via Twitter). Once you’ve decided on the type of bar you’re creating you can get to customizing every aspect like link text and colors. There really isn’t much that you can’t customize easily through the interface.

Once you’re satisfied with your hello bar (by checking the preview) you are presented with a little bit of JavaScript to copy and paste into your websites body tag. After that you should be up and running with your brand new hello bar.

Wait, is there more?

Up until now you might be wondering why you would use such a service and not just go hunting for a jQuery plugin or something. Well the true value in Hello Bar comes after you copy and paste the JavaScript. Once you have created your bars you can manage them all collectively from your account, turning them on and off remotely as needed. I can see this as a very handy feature for those people who have several dispersed web properties to manage.

And if that’s not enough for you there are also statistics. Hello Bar tracks impressions, clicks and the click through rate for each bar in your account. You can then filter that data by day, week or month.

While it is true that you could track the same data leveraging a jQuery plugin (using Google Analytics) that takes time. I was up and running with my hello bar in LESS than 5 minutes. Setting up Google Analytics alone will take more time than that.

Final Verdict

When I first came across Hello Bar my thought was “Really?? Someone made an entire web app just for these annoying little drop down bar things?” However, after taking a look at all the features and statistics tracking I have to say I’m impressed. Seems like a useful feature set paired with a kick ass interface, definitely a winning combination. Now if it only wasn’t for those annoying drop down bar things that remind me of pop-up ads.

All jokes aside, I will not personally be using this service, but I do recommend it to anyone looking for this type of functionality. Very solid tool!