But – in five minutes, I’ll try to simplify the process of working with custom fonts as much as I possibly can. Services like Font Squirrel help to make the task a cinch!

Final CSS

@font-face {
font-family: 'blok-regular';
src: url('type/Blokletters-Potlood.eot');
src: local('Blokletters Potlood Potlood'),
 local('Blokletters-Potlood'),
 url('type/Blokletters-Potlood.ttf') format('truetype');
}

@font-face {
font-family: 'blok-italic';
src: url('type/Blokletters-Balpen.eot');
src: local('Blokletters Balpen Balpen'),
 local('Blokletters-Balpen'),
 url('type/Blokletters-Balpen.ttf') format('truetype');
}

@font-face {
font-family: 'blok-heavy';
src: url('type/Blokletters-Viltstift.eot');
src: local('Blokletters Viltstift Viltstift'),
 local('Blokletters-Viltstift'),
 url('type/Blokletters-Viltstift.ttf') format('truetype');
}

h1 { font-family: blok-heavy, helvetica, arial; }

Notice how we’re referencing both an .eot and .ttf font? This is because, of course, Internet Explorer only uses its own format, that has yet to truly catch on. As such, we must first import that .eot file, and then move on to the different formats for Firefox, Safari, etc. It’s essential that you load the .eot version first.

Next, we search for the font on the user’s computer by using the “local” attribute. If it’s unfound, only then do we pass a url that will load the font.

Why Doesn’t IE Try to Load the TTF Fonts?

This was definitely a concern. If Explorer can’t work with the truetype format, we don’t want to waste time trying to download the font. Luckily, because of all those local attributes, and the commas, IE won’t understand any of it. As such, it will simply skip the line all together, thus, only utilizing the .eot version.

• Follow us on Twitter, or subscribe to the Nettuts+ RSS Feed for the best web development tutorials on the web.

You can use Adman65/nettuts for a successful login. Be sure to use bad credentials so you can see how everything works.

What We’re Making

Getting Started

We’re going to start by creating a dummy application that has a public and private page. The root url is the public page. There’s a login link on the public page. If the user logs in successfully, they’re redirected to the private page. If not, they’re redirected back to the login form. The private page shows the user name. We’ll use this as the starting point for ajaxifying the site.

The first step is using the rails command to generate a new application, then install and setup up authlogic.

$ cd into-a-directory
$ rails unobtrusive-login

Add authlogic.

# /config/environment.rb
config.gem 'authlogic'

Now install the gems.

$ sudo gem install gemcutter
$ sudo gem tumble
$ sudo rake gems:install

Next create a user model and add the required authlogic columns to the migration.

$ ./script/generate model User
exists  app/models/
exists  test/unit/
exists  test/fixtures/
create  app/models/user.rb
create  test/unit/user_test.rb
create  test/fixtures/users.yml
create  db/migrate
create  db/migrate/20100102082657_create_users.rb

Now, add the columns to the new migration.

class CreateUsers < ActiveRecord::Migration
  def self.up
    create_table :users do |t|
      t.string    :login,               :null => false
      t.string    :crypted_password,    :null => false
      t.string    :password_salt,       :null => false
      t.string    :persistence_token,   :null => false
      t.timestamps
    end
  end

  def self.down
    drop_table :users
  end
end

Migrate the database.

$ rake db:migrate

Include authlogic in the user model.

# /app/models/user.rb
class User < ActiveRecord::Base
  acts_as_authentic
end

Now we can create a user. Since this is a demo app, web based functionality for signing up isn’t required. So open up the console and create a user:

$ ./script/console
>> me = User.create(:login => 'Adman65', :password => 'nettuts', :password_confirmation => 'nettuts')

Now we have a user in the system, but we have no way to login or logout. We need to create the models, controllers, and views for this. Authlogic has its own class for tracking logins. We can use the generator for that:

# create the user session
$ ./script/generate UserSession

Next we need to generate the controller that will login/logout users. You can create sessions just like any other resource in Rails.

# create the session controller
$ ./script/generate controller UserSessions

Now set its contents to:

# /app/controllers/user_sessions_controller.rb
class UserSessionsController < ApplicationController
  def new
    @user_session = UserSession.new
  end

  def create
    @user_session = UserSession.new(params[:user_session])
    if @user_session.save
      flash[:notice] = "Login successful!"
      redirect_back_or_default user_path
    else
      render :action => :new
    end
  end
end

It looks exactly the same as a controller that was generated via scaffolding. Now create the users controller which has public and private content. Generate a users controller. Inside the controller we’ll use a before filter to limit access to the private areas. The index action is public and show is private.

# create the users controller
$ ./script/generate controller users

Update its contents:

# /app/controllers/users_controller.rb
class UsersController < ApplicationController
  before_filter :login_required,  nly => :show

  def index
  end

  def show
    @user = current_user
  end

  private
  def login_required
    unless current_user
      flash[:error] = 'You must be logged in to view this page.'
      redirect_to new_user_session_path
    end
  end
end

You should notice that current_user is an undefined method at this point. Define these methods in ApplicationController. Open up application_controller.rb and update its contents:

# application controller
class ApplicationController < ActionController::Base
  helper :all # include all helpers, all the time
  protect_from_forgery # See ActionController::RequestForgeryProtection for details

  # From authlogic
  filter_parameter_logging :password, :password_confirmation
  helper_method :current_user_session, :current_user

  private
  def current_user_session
    @current_user_session ||= UserSession.find
  end

  def current_user
    @current_user ||= current_user_session && current_user_session.user
  end
end

At this point the models and controllers are complete, but views aren’t. We need to create views for a login form and the public and private content. We’ll use the nifty-generators gem to create a basic layout.

$ sudo gem install nifty-generators
$ ./script/generate nifty_layout

Time to create the login form. We’re going to use a partial for this because in the future we’ll use the partial to render just the login form in the modal box. Here’s the code to create the login form. It’s exactly the same as if you were creating a blog post or any other model.

# create the login views
# /app/views/user_sessions/_form.html.erb
<% form_for(@user_session, :url => user_session_path) do |form| %>
  <%= form.error_messages %>

  <p>
    <%= form.label :login %>
    <%= form.text_field :login %>
  </p>

  <p>
    <%= form.label :password %>
    <%= form.password_field :password %>
  </p>

  <%= form.submit 'Login' %>
<% end %>

Render the partial in the new view:

# /app/views/user_sessions/new.html.erb
<% title 'Login Please' %>
<%= render :partial => 'form' %>

Create some basic pages for the public and private content. The index action shows public content and show displays private content.

# create the dummy public page
# /app/views/users/index.html.erb
<% title 'Unobtrusive Login' %>

<p>Public Facing Content</p>

<%= link_to 'Login', new_user_session_path %>

And for the private page:

# create the dummy private page
# /app/views/users/show.html.erb
<% title 'Welcome' %>
<h2>Hello <%=h @user.login %></h2>

<%= link_to 'Logout', user_session_path, :method => :delete %>

Delete the file /public/index.html and start the server. You can now log in and logout of the application.

$ ./script/server

Here are some screenshots of the demo application. The first one is the public page.

Now the login form

And the private page

And finally, access denied when you try to visit http://localhost:3000/user

The AJAX Login Process

Before continuing, we need to understand how the server and browser are going to work together to complete this process. We know that we’ll need to use some JavaScript for the modal box and the server to validate logins. Let’s be clear on how this is going to work. The user clicks the login link, then a modal box appears with the login form. The user fills in the form and is either redirected to the private page, or the modal box is refreshed with a new login form. The next question is how do you refresh the modal box or tell the browser what to do after the user submits the form? Rails has respond_to blocks. With respond_to, you can tell the controller to render different content if the user requested XML, HTML, JavaScript, YAML etc. So when the user submits the form, the server can return some JavaScript to execute in the browser. We’ll use this render a new form or a redirect. Before diving any deeper, let’s go over the process in order.

1. User goes to the public page
2. User clicks the login link
3. Modal box appears
4. User fills in the form
5. Form is submitted to the server
6. Server returns JavaScript for execution
7. Browser executes the JavaScript which either redirects or updates the modal box.

That’s the high level. Here’s the low level implementation.

1. User visits the public page
2. The public page has some JavaScript that runs when the DOM is ready that attaches JavaScript to the login link. That javscript does an XMLHTTPRequest (XHR from now on) to the server for some JavaScript. The JavaScript sets the modal box’s content to the form HTML. The JavaScript also does something very important. It binds the form’s submit action to an XHR with POST data to the form’s action. This allows the user to keep filling the login form in inside the modal box.
3. Modal box now has the form and required JavaScript
4. User clicks ‘Login’
5. The submit() function is called which does a POST XHR to the form’s action with its data.
6. Server either generates the JavaScript for the form or the redirect
7. Browser receives the JavaScript and executes it. The browser will either update the modal box, or redirect the user through window.location.

Taking a Peak at the AJAX Ready Controller

Let’s take a look at the new structure for the UserSessions controller.

class UserSessionsController < ApplicationController
  layout :choose_layout

  def new
    @user_session = UserSession.new
  end

  def create
    @user_session = UserSession.new(params[:user_session])

    if @user_session.save
      respond_to do |wants|
        wants.html { redirect_to user_path(@user_session.user) }
        wants.js { render :action => :redirect } # JavaScript to do the redirect
      end
    else
      respond_to do |wants|
        wants.html { render :new }
        wants.js # defaults to create.js.erb
      end
    end
  end

  private
  def choose_layout
    (request.xhr?) ? nil : 'application'
  end
end

As you can see the structure is different. Inside the if save, else conditional, respond_to is used to render the correct content. want.xx where xx is a content type. By default Prototype and jQuery request text/JavaScript. This corresponds to wants.js. We’re about ready to get started on the AJAX part. We won’t use any plugins except ones for modal boxes. We’ll use Facebox for jQuery and ModalBox for Prototype.

Prototype

Rails has built in support for Prototype. The Rail’s JavaScript helpers are Ruby functions that generate JavaScript that use Prototype. This technique is known as RJS (Ruby JavaScript). One example is remote_form_for which works like the standard for_for adds some JS bound to onsubmit that submits to the form to its action using its method with its data. I won’t use RJS in this article since I want to demonstrate vanilla JS. I think by using pure JS and eliminating the JS helpers the article will be more approachable by less experienced developers. That being said, you could easily accomplish these steps using RJS/Prototype helpers if you choose.

Adding Prototype to the application is very easy. When you use the rails command, it creates the Prototype and scriptaculous files in /public/JavaScripts. Including them is easy. Open up /app/views/layouts/application.erb and add this line inside the head tag:

<%= JavaScript_include_tag :defaults %>

JavaScript_include_tag creates script tags for default files in /public/JavaScripts, most importantly prototype.js, effects.js, and application.js. effects.js is scriptaculous. application.js is a file you can use to keep application specific JS. Now we need a modal box plugin. We’re going to use this. Its a very nice modal box plugin inspired by OSX. The source is hosted on GitHub, so you’ll have to clone and move the files in your project directory. For example:

$ cd code
$ git clone git://github.com/okonet/modalbox.git
$ cd modalbox
# move the files in the correct directories.
# move modalbox.css into /public/stylesheets
# move modalbox.js into /public/JavaScripts
# move spinner.gif into /public/images

Now include the stylesheets and JavaScript in your application.

  <%= stylesheet_link_tag ‘application’ %>
  <%= stylesheet_link_tag ‘modalbox’ %>
  <%= JavaScript_include_tag :defaults %>
  <%= JavaScript_include_tag ‘modalbox’%>

Now let’s get our login link to open a modalbox. In order to do this we need to add some JavaScript that runs when the DOM is ready that attaches the modalbox to our link. When the user clicks the login link, the browser will do a GET to /user_sessions/new which contains the login form. The login link uses the #login-link selector. Update the login link to use the new id in /app/views/users/index.html.erb. Modify the link_to function like this:

<%= link_to 'Login', new_user_session_path, :id => 'login-link' %>

That gives us a#login-link. Now for the JavaScript to attach a modalbox. Add this JS in /public/JavaScripts/application.js

document.observe('dom:loaded', function() {
    $('login-link').observe('click', function(event) {
        event.stop();
        Modalbox.show(this.href,
            {title: 'Login',
            width: 500}
        );
    });
})

There’s some simple JS for when the user clicks the link a modal box opens up with the link’s href. Refer to the modalbox documentation if you’d like more customization. Here’s a screenshot:

Notice that inside the modal box looks very similar to our standard page. Rails is using our application layout for all HTML responses. Since our XHR’s want HTML fragments, it make sense to render without layouts. Refer back to the example controller. I introduced a method for determining the layout. Add that to UserSessionsController to disable layout for XHR’s.

class UserSessionsController < ApplicationController
  layout :choose_layout

  def new
    @user_session = UserSession.new
  end

  def create
    @user_session = UserSession.new(params[:user_session])
    if @user_session.save
      flash[:notice] = "Login successful!"
      redirect_to user_path
    else
      render :action => :new
    end
  end

  def destroy
    current_user_session.destroy
    flash[:notice] = "Logout successful!"
    redirect_to root_path
  end

  private
  def choose_layout
    (request.xhr?) ? nil : 'application'
  end
end

Refresh the page and click the link you should get something like this:

Fill in the form and see what happens. If you fill in the from with bad info, you’re redirected outside the modal box. If you login correctly you’re redirected normally. According the requirements the user should be able to fill out the form over and over again inside the modal box until they login correctly. How can we accomplish this? As described before we need to use AJAX to submit data to the server, then use JavaScript to update the modal box with the form or do a redirection. We know that the modalbox does a GET for HTML. After displaying the initial modalbox, we need to write JS that makes the form submits itself AJAX style. This allows the form to submit itself inside the modal box. Simply adding this code after the modal box is called won’t work because the XHR might not have finished. We need to use Modalbox’s afterLoad callback. Here’s the new code:

document.observe('dom:loaded', function() {
    $('login-link').observe('click', function(event) {
        event.stop();
        Modalbox.show(this.href,
            {title: 'Login',
            width: 500,
            afterLoad: function() {
                $('new_user_session').observe('submit', function(event) {
                    event.stop();
                    this.request();
                })
            }}
        );
    });
})

Form#request is a convenience method for serializing and submitting the form via an Ajax.Request to the URL of the form’s action attribute—which is exactly what we want. Now you can fill in the form inside the modal without it closing. The client side is now complete. What about the server side? The client is submitting a POST wanting JS back. The server needs to decide to either return JavaScript to update the form or render a redirect. In the UserSessionsController we’ll use respond_to to handle the JS request and a conditional to return the correct JS. Let’s begin by handling the failed login case. The server needs to return JS that updates the form, and tells the new form to submit over ajax. We’ll place this template in /app/views/users_sessions/create.js.erb. Here’s the structure for the new create action:

def create
  @user_session = UserSession.new(params[:user_session])
  if @user_session.save
    flash[:notice] = "Login successful!"
    redirect_to user_path
  else
    respond_to do |wants|
      wants.html { render :new }
      wants.js # create.js.erb
    end
  end
end

Now let’s fill in create.js.erb:

$('MB_content').update("<%= escape_JavaScript(render :partial => 'form') %>");
Modalbox.resizeToContent();
$('new_user_session').observe('submit', function(event) {
    event.stop();
    this.request();
});

First we update the content to include the new form. Then we resize the modal box. Next we ajaxify the form just as before. Voilla, you can fill in the form as many times as you want.

Next we need to handle the redirection case. Create a new file in /app/views/users_sessions/redirect.js.erb:

  window.location=”<%= user_path %>”;

Now, update the create action to handle the redirection process:

def create
  @user_session = UserSession.new(params[:user_session])
  if @user_session.save
    respond_to do |wants|
      wants.html do
        flash[:notice] = "Login successful!"
        redirect_to user_path
      end

      wants.js { render :redirect }
    end
  else
    respond_to do |wants|
      wants.html { render :new }
      wants.js # create.js.erb
    end
  end
end

And that’s it! Now try login with correct credentials and you’re redirected to the private page. For further learning, try to add a spinner and notification telling the user the form is submitting or they’re being redirect. The application still works if the user has JavaScript disabled too.

jQuery

Since I’ve already covered the Prototype process, so I won’t go into the same detail as before. Instead, I will move quickly describing the alternate JavaScript to add to the application. The jQuery vesion will have the exact same structure as the Prototype version. All we need to change is what’s in application.js, create.js.erb, and the JavaScript/css includes.

First thing we need to do is download jQuery and Facebox. Move jQuery into /public/JavaScripts as jquery.js. For facebox move the images into /public/images/, stylesheets into /public/stylesheets, and finally the JS into /public/JavaScripts. Now update /app/views/layouts/application.html.erb to reflect the changes:

<head>
  <title><%= h(yield(:title) || "Untitled") %></title>
  <%= stylesheet_link_tag 'facebox' %>
  <%= stylesheet_link_tag 'application' %>
  <%= JavaScript_include_tag 'jquery' %>
  <%= JavaScript_include_tag 'facebox' %>
  <%= JavaScript_include_tag 'application' %>
</head>

Facebox comes with a default stylesheet which assumes you have your images in /facebox. You’ll need to update these selectors in facebox.css like so:

#facebox .b {
  background:url(/images/b.png);
}

#facebox .tl {
  background:url(/images/tl.png);
}

#facebox .tr {
  background:url(/images/tr.png);
}

#facebox .bl {
  background:url(/images/bl.png);
}

#facebox .br {
  background:url(/images/br.png);
}

Now we attach facebox to the login link. Open up /public/JavaScripts/application.js and use this:

$(document).ready(function() {
    $('#login-link').facebox({
        loadingImage : '/images/loading.gif',
    closeImage   : '/images/closelabel.gif',
    });
});

I override the default settings for the images to reflect the new image path. Start the sever and head over to the index page. You should see a nice facebox with the login form:

Next thing we have to do is set the form to submit itself via AJAX. Just like before, we’ll have to use callbacks to execute code after the modal box is ready. We’ll use jQuery’s post method for the XHR request. Facebox has an after reveal hook we can use. application.js:

$(document).ready(function() {
    $('#login-link').facebox({
        loadingImage : '/images/loading.gif',
        closeImage   : '/images/closelabel.gif',
    });

    $(document).bind('reveal.facebox', function() {
        $('#new_user_session').submit(function() {
            $.post(this.action, $(this).serialize(), null, "script");
            return false;
        });
    });
});

Updating create.js.erb should be easy enough. We have to update the facebox’s contents and re-ajaxify the form. Here’s the code:

$('#facebox .content').html("<%= escape_JavaScript(render :partial => 'form') %>");
$('#new_user_session').submit(function() {
    $.post(this.action, $(this).serialize(), null, "script");
    return false;
});

And that’s it! Here’s the final product:

Downloading the Code

You can get the code here. There are branches for each library so you can check out the Prototype or jQuery versions. Any questions, comments, concerns? Thanks again for reading!

• Follow us on Twitter, or subscribe to the Nettuts+ RSS Feed for the best web development tutorials on the web.

1. Understand What it All Means

First up, you need to understand what AJAX is, what it stands for and how it has revolutionized parts of the internet. You’ll need to know what its advantages are before you can make an informed decision

Here is a list of must read articles to get you up to speed.

• WikiPedia
• MDC on AJAX
• DevX

2. Check for Appropriate Usage Scenarios

AJAX can sound all fine and dandy but there are only so many places you can implement it without it sounding like another bullet point. Do proper research and testing to make sure you are implementing AJAX for the right reasons. Because it sounds nice is not a valid reason.

Proper usage scenarios would be if you have lots of data in the back end and want to update the UI as and when the user needs access to that data or when you want to emulate a proper desktop application and handle everything asynchronously. An extremely bad scenario is when you have each page of a static web site load through AJAX for no reason other than you can. Use your discretion here.

3. Learn to Implement it With Raw Code

Before you delve into writing your code, understand the raw code to do it first. Libraries are great at reducing the time it takes to create browser agnostic code but when it breaks it’d be best if you know how to do it without libraries helping you.

I highly recommend Jeffrey’s tutorials on making AJAX requests with raw JavaScript here and here.

4. Use a Library

Once you’ve mastered the raw JS which handles the AJAX implementations, it’s best you shift over to a JavaScript library which provides robust support for AJAX. Any of the major libraries like jQuery, Prototype or MooTools should do.

Libraries not only provide an exhaustive feature set you can make use of but also makes sure your code is compatible with all browsers without you having to do anything extra.

Here are a few of our favorites which encompass proper AJAX functionality:

• jQuery
• Dojo
• MooTools
• Prototype
• Yahoo Ui Library
• Google Web Toolkit

5. Master the Library

Once you’ve gotten the hang of making AJAX requests with your library of choice, it’s time to take it to the next level and master it. It may sound a little redundant but there is a big difference between the two.

With each library getting bigger, packing more features with each release, the developers hide a huge amount of functionality from the beginner developer. For example, did you know that there are multiple methods in jQuery to make AJAX calls? Or that a number of event triggered methods are only available with the core AJAX call? A lot of people don’t know that and thus are unable to leverage the untapped potential of the library.

Here are a few choice resources for your perusal:

• jQuery 1.4 Reference Guide
• jQuery Enlightenment
• Learning jQuery’d Advanced section
• A comparison between jQuery and MooTools

6. Provide Feedback

On of the main reasons people were against AJAX in the past was they couldn’t really tell when the application updates the data it contains. This is also an integral part of the general user experience made even more pertinent with AJAX.

So even for the tiniest thing, remember to provide feedback to the user letting them know their action has been registered. The user has clicked on a button? Let them know!

7. Utilize Proper Events and Callback Functions

Whether you are using raw JS or a library to implement this functionality, you’ll have access to the state of the request i.e. whether the request was successful; met with an error and finally whether it has been completed.

Make proper use of these events and their respective callbacks to manipulate the UI for a better user experience. For example, if the request was unsuccessful, you’d want to update the user interface to reflect that their changes weren’t successful while if it was successful, you’d want to tell them so. Don’t keep the user waiting!

With jQuery, you’d make use of the success and error callbacks. You also get other callbacks such as complete and beforeSend to be invoked for apporopriate use.

$.ajax({
        //Other code
           success: function(msg)
        {
            // Update the UI here to reflect that the request was successful.
            doSomethingClever();
        },
        error: function(msg)
        {
            // Update the UI here to reflect that the request was unsuccessful
            doSomethingMoreClever();
        },
        complete: function(msg)
        {
            // Update the UI here to reflect completion
            doSomethingEvenMoreClever();
        }
});

- Show quoted text -

8. Choose the Right Format for the Job

Just because XML occurs in the abbreviation doesn’t mean you are limited to XML for the payload. You are free to choose whatever format strikes your liking. JSON? Sure. XML? Naturally. HTML? Of course. Raw strings? Definitely.

So, essentially, whatever floats your boat. You aren’t limited to any format. You get to choose whichever format makes the work at hand easier for you and makes the most sense for that specific instance.

9. Read Extensively

AJAX, while old in relative terms, is still very much in flux. Exciting new solutions are created everyday while scarily thorough books covering the subject are often released. Be it web developments blogs (like this one!) or books, keep reading to keep yourself informed of the latest developments.

Here are my most visited and/or read blogs and books:

• CSS Tricks
• Snook.ca
• James Padolsey’s Blog
• Remy Sharp’s Blog

10. Experiment Continuously

Reading book after book and article after article is awesome but to get a grip on the subject, you’ll need to fold up your sleeves and write some code yourselves. Trust me, you’ll learn a lot more a lot quicker reading a bit and then writing some code about it than just reading continuously without writing any code to better understand what you’ve learnt.

11. Utilize Firebug

Firebug is arguable the most important tool in every web developer’s repertoire. Along with impressive JavaScript debugging and other potent features, it also let’s you see each AJAX request as it is made along with a myriad other details about the request including from where it originates, what its payload is and so much more. You can download it right here.

Here are a few more recommended resources:

• 10 Reasons Why You Should Be Using Firebug
• Firebug Explained
• How to Use Firebug with CSS
• Easy CSS with Firebug

12. Keep the Users With Old Browsers in Mind

Unless your web application is like Google Maps it’s always a good idea to provide users with a fallback so they can still use your application. Case in point would be the numerous web applications which route all their user interactions through AJAX if they have the capability while falling back to a normal HTML version otherwise.

13. Bookmarkability

The tendency to bookmark is a pervasive habit of the average web user and it’s imperative your application respects that. With AJAX, the address bar of the browser is not updated which means when a user wants to bookmark a page with content loaded dynamically with AJAX, he/she is going to bookmark the initial page and not the updated page. This presents a huge problem.

Fortunately, there are a few techniques to fix this problem. Here is a selected list of articles intended to help you with that:

• Content with Style
• jQuery History Plugin
• Really Simple History

14. Use Proper Animations

This is another of those user experience issues which may mar an otherwise spectacular application. Often with an AJAX application, the user may fail to even notice a change has occurred with an element of the user interface or the data it contains. In light of this issue, it’s essential that the developer uses non-garish, tasteful animations to draw the user’s attention to the fact that the user interface has been updated to reflect the user’s actions.

You can read about how to use jQuery to create tasteful, cross browser animations here.

15. Respect the Back Button

The back button is another action that has become part of a normal web user’s habits. Make sure your application adheres to this respected paradigm to avoid angering users. Trust me, they will, if suddenly their back button doesn’t work as intended.

Here is a list of article which should help you with the matter.

• Content with Style
• jQuery History Plugin
• Really Simple History

16. Change the DOM Intelligently

Imagine this: your request has succeeded and has returned a chunk of data with which you hope to update your user interface. If this chunk of data has few individual chunks, you can proceed as usual. If instead it has, say, 15 contiguous elements to be updated, it is better to just create the elements, modify their data in memory and replace those in the DOM in one big swoop rather than accessing each element and updating the DOM each time separately.

Modifying the DOM separately leads to worse performance as the number of edits to be made increases.

So, for a chunk of HTML like so:

<div id="container">
<span id="elem1"></span>
<span id="elem2"></span>
</div>

instead of doing this:

$("#elem1").html("Value 1");
$("#elem2").html("Value 2");

Do this:

var updatedText = "<span id=\"elem1\">Value1</span>
<span id=\"elem2\">Value2</span>";
$("#container").html(updatedText);

It might look a lot of work for just two elements but once you extrapolate it to more, the performance alone will be worth it. It’ll be faster since you’ll be updating the DOM just once irrespective of how many elements you have within the updated HTML. With the usual method though, the number of edits required to the DOM scales linearly to the number of elements which in turn degrades performance.

17. Comment Your Code

This is a no-brainer but comment your code properly. Chances are, your code is going to be looked at by a few hundred people , at least, looking to learn from you and commenting is definitely going to earn your extra rep points and paragon cookies.

You don’t necessarily need to comment every tiny bit of your code; commenting just the important bits is sufficient.

This is too much!

$.ajax({
    // Switch off caching
    cache: false,

        //Set the type of request
       type: "GET",

        // Set the timeout
    timeout: 5000,

        // Specify the proper handler
       url: "handler.php",
       success: function(msg)
        {
           // Update the UI here to reflect that the request was successful.
           doSomethingClever();
        },
        error: function(msg)
        {
           // Update the UI here to reflect that the request was unsuccessful
           doSomethingMoreClever();
        }
});

A much better way to add comments since a lot of it is self explanatory.

// Make an AJAX call to handler.php and update the UI
$.ajax({
    cache: false,
       type: "GET",
    timeout: 5000,
       url: "handler.php",
       success: function(msg)
        {
           doSomethingClever();
        },
        error: function(msg)
        {
              doSomethingMoreClever();
        }
});

18. Make an Informed Decision About the Request Type

This is strictly a general web application tip than specifically an AJAX tip but do take special note of the type of request you are making: GET or POST. The XMLHttpRequest object is capable of making both type of requests but it is up to you to decide what kind to make.

As their names signify, a GET request is used to procure data from a source while a POST request is used to submit data to be processed. With an AJAX GET request, as with a normal GET request, you’ll have to pass on the query data as part of the URL itself manually as opposed to a POST request where the data is sent automatically. Also note that GET requests are cached automatically while a POST request isn’t.

19. Use a Proper IDE

When it comes to JavaScript, please don’t be an elitist and limit yourself to plain old notepad. Your productivity will spike sharply with the use of a proper IDE, specially one with support for your JavaScript library of choice.

For the PC loyalists

• InType
• E-Text Editor
• Notepad++
• Aptana
• Dreamweaver CS4

For my fruit flavored brethren

• Coda
• Espresso
• href="http://macromates.com/">TextMate
• href="http://www.aptana.com">Aptana
• href="http://www.adobe.com/products/dreamweaver/">DreamWeaver CS4

20. Participate in the Community

Getting to be a part of awesome web development communities, like this, will not only expose you to a wider range of ideas but will also lead you to the path of writing better code. By writing and commenting on articles similar to these, you’ll not only teach people less knowledgeable than you on the subject but you’ll also be able to learn more from the more experienced people who comment on your code.

As Jeff says, you only truly understand something when you’ve taught it to someone else.

21. Tweak Your Response Times

By response time I mean only one thing: the time before a user triggers an AJAX request. Consider this, you are typing in an input box which uses AJAX to retrieve search suggestions from the server. Response time would be the time duration between the key press and the AJAX call being made. Too fast and you’d have to do multiple requests for each letter of the search phrase. Too slow and you’ll have the user twiddling his thumbs wondering as to how he broke the application.

This isn’t limited to just the scenario noted above. This applies to each and every non-definite (click) user action. Test rigorously with your users to find the optimum latency.

22. Use Status Indicators

This is an extension of a point noted above but just as important. Users coming from the desktop application or a general web application paradigm will be flummoxed when they use an AJAX enabled web application. While notifying the user when a change has been made is good, you’ll also need to make sure to let them know that a request has been initiated in the first place.

This is where status indicators come in. These are the little rotating or bouncing GIFs you see in applications. In function these are similar to the hour glass cursor used in desktop operating systems.

Here is a wonderful little tool which lets you create an indicator of your choice.

23. Appreciate JSON-P’s Awesomeness

Often, as part of the cross site mashup you’re creating, you’d need to access data from other sites through AJAX requests. This flies directly in the face of the cross domain restriction most browsers enforce. In this case, instead of going with exotic solutions like masking and proxying, you could just use JSON-P.

JSON-P, JSON with Padding, essentially lets us circumvent this restriction and lets us obtain data from third party domains. Here is a list of articles to get you started:

• WikiPedia Link
• Remy Sharp’s Blog
• James Padolsey’s Blog

24. Ask Questions Freely

Don’t be shy to ask questions. Every one of us started as a complete newbie and began by asking questions. There are plenty of placed to clarify your doubts including the comments section of Nettuts+. Never, ever be afraid of asking questions. Just try to be a little polite! It always helps.

That’s all folks

And we’re done. Twenty four points to keep in mind when implementing AJAX within your site or web application. Hopefully, this has been useful to you and you found it interesting. I’ll be closely watching the comments section so chime in there if you have any counter arguments or different perspectives on the matter.

Questions? Nice things to say? Criticisms? Hit the comments section and leave me a comment. Happy coding!

Write a Plus Tutorial

Did you know that you can earn up to $600 for writing a PLUS tutorial and/or screencast for us? We’re looking for in depth and well-written tutorials on HTML, CSS, PHP, and JavaScript. If you’re of the ability, please contact Jeffrey at nettuts@tutsplus.com.

Please note that actual compensation will be dependent upon the quality of the final tutorial and screencast.

• Follow us on Twitter, or subscribe to the Nettuts+ RSS Feed for the best web development tutorials on the web.

Reversing a String

This little snippet takes advantage of the Array object’s “reverse” method, and applies its functionality to a given string. In effect, something like “hello” will be turned into “olleh,” and can be accessed by using “myString.reverse()”.

String.prototype.reverse = function() {
	return Array.prototype.reverse.apply(this.split('')).join('');
};

var myString = 'hello';
console.log(myString.reverse());

Bonus Question

Now that we have a basic of understanding of augmenting objects, can you figure out a way to write a custom “contains” method for the String object? For example, the jQuery library allows us to write things like:

$("div:contains('John')").css('fontWeight', 'bold');

The snippet above will search through all of the divs on the page, and then filter that wrapped set down to only those that contain the string “John.” How could we extend the String object, with raw JavaScript, to allow for this? Leave your solution in the comments, and we’ll discuss!

• Follow us on Twitter, or subscribe to the Nettuts+ RSS Feed for the best web development tutorials on the web.

Free Copies of jQuery UI 1.7

The author of this article, Dan Wellman, recently released jQuery UI 1.7, from Packt Publishing. It’s a fantastic read, and I’m pleased to announce that we have a handful of copies to randomly give out. Simply leave a comment about the article, and you’ll automatically be entered into the drawing. Check back on Monday to find out if you’re a winner!

Bug Zapping

This release of the library brings several bug fixes for some key components including the Datepicker and Dialog widgets and the Droppable, Resizable and Selectable interaction helpers. None of the bugs were show-stoppers, but nevertheless, clearing out the bugs is a critical part of the ongoing progression of the library. One important point to note is that the beforeclose event of the Dialog widget has been deprecated and replaced with beforeClose so that it follows the same naming convention as the events of other components.

As well as bugs in the code, several styling and accessibility issues have also been addressed; notably the title text of Dialog widgets can no longer disappear behind the close icon, and the keyboard navigability of the new button widget has been improved. For a complete list of all bug fixes included with version 1.8 see the changelog at http://jqueryui.com/docs/Changelog/1.8rc1

Positioning

jQuery UI now has a unique positioning system that that can be used whenever a widget needs to be positioned relative to another element, such as with a drop-down menu or a floating tooltip. The Position utility allows us to easily specify, using a series of simple strings, which part of the positioned element should be fixed to which part of the specified target element. So for example, the “top left” point of one element can be fixed to the “bottom right” of another specified element.

The utility also features a robust collision detection system which prevents viewers of the page being exposed to unsightly toolbars if the element being positioned gets too close to the edge of the viewport, or cannot otherwise occupy its positioned place.

The API for this utility is compact, with just 7 configurable options at this stage. This gives us all the control we need however and allows us to specify up to 81 possible combinations of positioning; options we can configure include the following:

at:

Refers to the position on the target element the element being positioned will be fixed to; the method accepts a single string comprised of the value for the horizontal axis (either right, center, or left) followed by the value for the vertical axis (either top, center, or bottom). There is no separating character between the 2 values.

bgiframe:

If the bgiframe plugin is available on the page, this option will apply an iframe shim to the positioned element, which can help to prevent select elements showing above the positioned content in IE6.

collision:

This option determines how collisions are handled; it accepts one of the following strings: flip, fit or none. The default is flip, which causes the element being positioned to invert the position relative to the target element, e.g. “right center” will become “left center”.

my:

Refers to the element being positioned; accepts same values as at.

of:

Accepts a jQuery selector specifying the target element.

offset:

Specify a number of pixels to offset the element being positioned on the target element.

using:

A callback function can be used with this option allowing you to animate the positioning of the element.

Autocomplete

One of my favourite widgets has returned as an official UI component! Autocomplete was a beta widget in an early 1.6 version of the library and is now back after a complete refactor. It is attached to text inputs on the page and supplies a list of possible choices when a visitor begins typing in the text field.

The widget can take its data (the matching items in the suggestion menu) from a variety of sources including a standard JavaScript array, JSON via an AJAX request or a flexible callback function that can implement any data source and return a customized response to display in the suggestion menu.

Autocomplete is a highly configurable widget and features a full API of options, methods and events to make use of. It’s completely themable via SteamRoller and fully keyboard navigable. All in all this component brings a lot of functionality to your pages. At some future point caching may also be a configurable behaviour.

Let’s take a look at its API; it contains the following three configuration options:

delay:

We can specify the number of milliseconds the widget should wait before displaying the suggestion menu when the visitor begins typing in the input.

minLength:

This option takes an integer that refers to how many characters should be typed into the input before the suggestion menu is displayed.

source:

We configure the data source using this option; possible values include an array of strings representing the items to show in the suggestion menu, or an array of objects where each object contains two properties – the first is the label shown in the suggestion menu, the second is the value that will be added to the input if an item in the suggestion menu is selected. We can also supply a single string representing a remote resource that can return the data asynchronously, or a callback function that can request the data and return it to the widget in the required format.

The following two methods are exposed by Autocomplete:

close:

Used to close the suggestion menu.

search:

Perform a search of the available data and display the suggestions if the term is matched. Can take a predefined value as the term which is passed into the method as an argument, or the value of the input field it is associated with.

We can also hook callback functions into the following custom events:

change:

Fired after an item in the suggestion menu is selected and the menu is closed.

close:

Fired whenever the suggestion menu is closed, whether or not an item was selected. Precedes the change event.

focus:

Fired directly before focus is given to an item in the suggestion menu.

open:

Fired once the data has been returned, directly before the suggestion menu is displayed.

search:

Fired directly before the data source is searched. The search can be cancelled by returning false from a callback function bound to this event.

select:

This event is triggered when an item from the menu before the menu closes.

As a special bonus, the source file for the Autocomplete widget also contains the beta Menu widget, which is still currently in development and is due for release in a later version of the library. So far it looks like a robust and attractive addition to the library, and allows us to transform an unordered list into an attractive drop-down or fly-out menu. Many features are supported including sub-menus, icons, dividers and even a drill-down menu with breadcrumb.

Button

The button widget allows us to implement attractive and functional buttons that can be configured to behave like a particular type of button; for example, we can crate standard push buttons, radio-style buttons where only a single button in a set may be selected, or check-style buttons where any number in a particular set may be selected. Several types of button that incorporate a simple drop-down menu can also be created.

It’s a very flexible widget and can be built using a variety of underlying elements including <button>, <input> and <a>. The buttons are fully accessible and ARIA compliant, adding or removing the appropriate roles and states when necessary. The API is relatively simple at this point, but covers all essentials with three configurable options and a single method to invoke; the configuration options are as follows:

icons:

This option allows us to specify primary and secondary icons to display on the button. It expects an object with the keys primary and secondary, and CSS class names as the values.

label:

With this option we can set the text that is displayed on the button; a string value is expected, but if this is not supplied the value of the underlying HTML element from which the button is created can be used.

text:

The text option accepts a Boolean indicating whether or not to show a text label on the button, which could be the case if a simple icon is all that is needed. The default value is true.

The event that we can bind to in order to execute a callback function and react to interaction is the click event; the native click event of the browser is used unless with the radio or checkbox-style buttons, in which case the event is fired by the widget, not the underlying element.

Mouse Utility

The final new utility to be found in jQuery UI 1.8 is the Mouse utility, which is used by other library components in order to better distribute related implementations of the same behaviour by different widgets. This is great for developers because it means that if mouse interaction is a required behaviour of a custom UI widget, the logic in this utility can be used without having to rewrite it manually. Like the Menu component however, this utility should be considered beta and subject to considerable revision in future releases.

The API is very compact; there are just three configurable options; there are a series of private methods that are used internally by the plugin, but nothing we would need to manually invoke. The configurable options are as follows:

cancel:

This option accepts a string value containing selectors and allows us to configure elements that interaction should be cancelled on. The default value is ‘:input, option’ so for example, in a drag and drop implementation, these elements would not be draggable.

distance:

This option accepts an integer representing the number of pixels the mouse should move before the interaction is registered. The default is 1.

delay:

This option also accepts an integer, but this time refers to the number of milliseconds that should elapse before the interaction is registered. The default of this option is 0.

Summary

jQuery UI 1.8 is shaping up to be a fine release of the library; with a combination of both bug-fixes and new components it’s looking like an important milestone in the library’s roadmap. We first looked at the library’s new positioning system which gives us easy access to a huge number of different was of positioning one element relative to another element. We then looked at the two new components Autocomplete and Button and saw the different configuration options, methods and events exposed by each of their APIs.

• Follow us on Twitter, or subscribe to the Nettuts+ RSS Feed for the best web development tutorials on the web.

Tutorial Details

• Program: CodeIgniter, CodeIgniter REST server and CodeIgniter REST client
• Difficulty: Medium
• Estimated Completion Time: 30 minutes

Introduction

If you have been following the CodeIgniter From Scratch series you will know by now that it is relatively quick and easy to put together simple web applications, such as blogs, CMS systems, brochure sites, etc. One thing you may not have thought about is using CodeIgniter to create an interactive API. After trying several existing REST implementations, I found they not only lacked simplicity but were missing most of the features you would expect from a RESTful implementation; so I built my own. This tutorial will show you how to use this code to set up your REST API, and gives example of how to interact with it from your web application.

Assumptions

1. You have a web server set up, locally or online and known how to manage files on it.
2. You have read a few of the CodeIgniter from Scratch tutorials.
3. You know how to set up CodeIgniter.
4. You know a little about RESTful services.

This tutorial is broken down into two parts. We will start by learning how to create a RESTful service, then further down, we will learn how to interact with it in a few different ways.

Part 1 – Creating a RESTful API

Step 1: Setting up the Demo

Firstly you need to download the codeigniter-restserver code from GitHub and extract it and move the code to your server.

When you open the folder, you will see an entire CodeIgniter install, which is there to power the demo. This allows people to have a play with the REST demo before integrating with your existing application.

Open up “application/config/config.php” and set the base_url to get links working. This base_url will be different for everyone and depends entirely on where you uploaded your files.

Step 2: The URLs

With the files extracted and the base_url set, we are ready to load up our RESTful CodeIgniter installation, and have a look at the demo supplied with it. Browse the base URL, which by default is:

http://localhost/restserver

Here you will find a few example links to the example_api controller, which can be found at “application/controllers/example_api.php”. Let’s dissect the URL’s of these examples to see what is going on. The first URL is a very simple one.

This URL looks very much like any other CodeIgniter URL with a controller and a method, but you will notice in this diagram that the method is named a “Resource”. REST is all about Resources and they are essentially a noun within your application, which are interacted with (i.e added, deleted, edited, queried) based on HTTP headers and URL query strings or HTTP arguments.

The default format for output is XML which is what we see in this basic example. The other links are slightly larger and demonstrate how to pass parameters and show how the output format can be modified in the URL:

Normally in CodeIgniter, you just pass in parameter values, but a REST controller accepts any number of parameters in any order. For this to work, we need to pass in the name of the parameter followed by the value in pairs.

At the end of the URL is the “format” parameter. This is a reserved parameter that will modify the output format of the requested data like so:

By giving both the API developer and the client application the choice of data formats to use, the API is opened up to a much wider audience and can be used with more programming languages and systems. These three are not the only formats supported, out of the box your REST API can use:

• xml – almost any programming language can read XML
• json – useful for JavaScript and increasingly PHP apps.
• csv – open with spreadsheet programs
• html – a simple HTML table
• php – Representation of PHP code that can be eval()’ed
• serialize – Serialized data that can be unserialized in PHP

While adding the format to the URL is not technically the most RESTful way to change formats, it allows for easy browser testing and lets developers without cURL perform simple GET requests on the API. The more RESTful way is to send a Content-type HTTP header to the REST controller using cURL, but that will be explained later.

Step 3: The Code

Now if you open up application/controllers/example_api.php you will immediatley spot a few differences from normal CodeIgniter controllers.

REST_Controller

In the MVC pattern, a controller is the central point of the logic. It is called when a user makes a request and then based on the logic in the controller it fetches data and outputs views. CodeIgniter contains its own logic for how a Controller should work, but as we are doing something different we need our own REST_Controller library to contain its own REST related logic. So instead of simply using:

<?php
class Example_api extends Controller {

}

…you will need to use:

<?php
require(APPPATH'.libraries/REST_Controller.php');

class Example_api extends REST_Controller {

}

Working with Resources

Now your empty controller is set up, next are the methods or “resources”. This is prossibly the most confusing part of the tutorial if you are used to how CodeIgniter works. Basically, you take the Resource and the HTTP verb and combine them to make a method name. So the two examples we looked at before had a Resource of user and users. Because both of these were loaded in the browser, we know it was using a GET request and so the two methods below are used:

<?php
require(APPPATH'.libraries/REST_Controller.php');

class Example_api extends REST_Controller {

    function user_get()
    {
		// respond with information about a user
    }

    function users_get()
    {
		// respond with information about several users
    }
}

This may seem a little strange, but it gives you the ability to use the same URL and respond to the request depending on the HTTP verb that has been used. If somebody tries to access your API in a way that is not allowed (in this example PUT or DELETE) it will simply respond with a 404. If you aren’t sure about HTTP verbs, let me explain.

GET

Used to fetch information about an existing resource. This is used by browsers when you enter a URL and hit go, or when you click on a link, so it perfect for fetching information on one of your REST resources (like user).

POST

Used to update an existing resource with information. Browsers use this to submit most types of forms on the internet, although some use GET as well by submitting the form action with a query string containing the field data.

PUT

Less commonly used and not supported by most browsers, PUT is used to create a new resource.

DELETE

Also not used by many browsers, this HTTP verb rather obviously is used to delete a resource.

If we put that into code and allow each verb on the resource user it would look like this:

<?php
require(APPPATH'.libraries/REST_Controller.php');

class Example_api extends REST_Controller {

    function user_get()
    {
		// respond with information about a user
    }

    function user_put()
    {
		// create a new user and respond with a status/errors
    }

    function user_post()
    {
		// update an existing user and respond with a status/errors
    }

    function user_delete()
    {
		// delete a user and respond with a status/errors
    }
}

Accessing parameters and returning data

So now the API has been given its structure by setting up the resources and defining a method for each HTTP verb we wish to support; we need parameters so we can use our CodeIgniter models and libraries. This is one of the major benefits of using CodeIgniter for our API, as we can use our existing models and libraries and not have to re-code them.

<?php
require(APPPATH'.libraries/REST_Controller.php');

class Example_api extends REST_Controller {

    function user_get()
    {
		$data = array('returned: '. $this->get('id'));
		$this->response($data);
    }

    function user_post()
    {
		$data = array('returned: '. $this->post('id'));
		$this->response($data);
    }

    function user_put()
    {
		$data = array('returned: '. $this->put('id'));
		$this->response($data;
    }

    function user_delete()
    {
		$data = array('returned: '. $this->delete('id'));
		$this->response($data);
    }
}

This example contains five new pieces of code:

$this->get()

Is used to return GET variables from either a query string like this index.php/example_api/user?id=1 or can be set in the more CodeIgniter’esque way with index.php/example_api/user/id/1.

$this->post()

Is an alias for $this->input->post() which is CodeIgniter’s method to access $_POST variables with XSS protection.

$this->put()

Reads in PUT arguments set in the HTTP headers or via cURL.

$this->delete()

You guessed it, this reads in DELETE arguments, also set in HTTP headers or via cURL.

$this->response()

Sends data to the browser in whichever data format has been requested, or defaults to XML. You can optionally pass a HTTP status code to show it has worked or failed. E.g if the ID provided was not in the database, you could use $this->response(array(‘error’ => ‘User not found.’), 404);

Step 4: Working with your Models

Until now, we have been working with an example API in a clean install. So the next step is to get a REST API running from your existing codebase.

Although the download comes with a full CodeIgniter installation for the demo and to allow API’s to be built from scratch, the only two files of importance are:

1. application/config/rest.php
2. application/libraries/REST_Controller.php

Drop those two files into your CodeIgniter application and create a new API controller.

<?php
require(APPPATH.'/libraries/REST_Controller.php');

class Api extends REST_Controller
{
	function user_get()
    {
        if(!$this->get('id'))
        {
        	$this->response(NULL, 400);
        }

        $user = $this->user_model->get( $this->get('id') );

        if($user)
        {
            $this->response($user, 200); // 200 being the HTTP response code
        }

        else
        {
            $this->response(NULL, 404);
        }
    }

    function user_post()
    {
        $result = $this->user_model->update( $this->post('id'), array(
        	'name' => $this->post('name'),
        	'email' => $this->post('email')
        ));

        if($result === FALSE)
        {
        	$this->response(array('status' => 'failed'));
        }

        else
        {
        	$this->response(array('status' => 'success'));
        }

    }

    function users_get()
    {
        $users = $this->user_model->get_all();

        if($users)
        {
            $this->response($users, 200);
        }

        else
        {
            $this->response(NULL, 404);
        }
    }
}
?>

This shows an example API with some generic model names. In the first method, we are picking up a ?id=XX and passing it to the model. If data is found we send it to the $this->response() function with a status 200. If nothing is found, return no body and a 404 to say nothing was found. You can imagine how this could be expanded to run all sorts of API activities for your web application.

Step 5: Securing the API

Now your API is built it needs securing so only users given access can interact with the API. To set the login type, usernames and passwords open up “application/config/rest.php” inside your codebase.

/*
|--------------------------------------------------------------------------
| REST Login
|--------------------------------------------------------------------------
|
| Is login required and if so, which type of login?
|
|	'' = no login required, 'basic' = relatively secure login, 'digest' = secure login
|
*/
$config['rest_auth'] = 'basic';

None

Anyone can interact with any one of of your API controllers.

Basic

A relatively insecure login method which should only be used on internal/secure networks.

Digest

A much more secure login method which encrypts usernames and password. If you wish to have a protected API which anyone could get at, use digest.

/*
|--------------------------------------------------------------------------
| REST Login usernames
|--------------------------------------------------------------------------
|
| Array of usernames and passwords for login
|
|	array('admin' => '1234')
|
*/
$config['rest_valid_logins'] = array('admin' => '1234');

Setting up the users is simple. Each login is an array item, with a key and a value. The key is the username and the value is the password. Add as many as you like to this array and dish them out to anyone who will be using the API.

Part 2 – Interacting with RESTful Services

Whether it is the API you have just built or a public service such as Twitter, you will want to be able to interact with it somehow. Seeing as RESTful services work with basic HTTP requests it is very easy to do this in a number of different ways.

Different Methods to Interact with REST

Each of these different interaction methods will be shown with the code placed directly in the Controller methods. This is purely so the demos are easier to read and would normally would be placed inside a model or a library for correct MVC separation.

file_get_contents()

Using the very simple PHP function file_get_contents(), you can perform a basic GET request. This is the most basic of all the methods but is worth mentioning for those “quick and dirty” moments.

$user = json_decode(
	file_get_contents('http://example.com/index.php/api/user/id/1/format/json')
);

echo $user->name;

It’s worth noting that, while this method will not work using HTTP Digest authentication, if you are using HTTP Basic authentication you can use the following syntax to get data from your password protected RESTful API:

$user = json_decode(
	file_get_contents('http://admin:1234@example.com/index.php/api/user/id/1/format/json')
);

echo $user->name;

There are a few problems with using this method: the only way to set extra HTTP headers is to set them manually using the PHP function stream_context_create(), which can be very complicated for developers who are new to the internal workings of HTTP requests. Another disadvantage is that you only receive the body of the HTTP response in its raw format, which means you need to handle conversion from very single request.

cURL

cURL is the most flexible way to interact with a REST API as it was designed for exactly this sort of thing. You can set HTTP headers, HTTP parameters and plenty more. Here is an example of how to update a user with our example_api and cURL to make a POST request:

    function native_curl($new_name, $new_email)
    {
	    $username = 'admin';
		$password = '1234';

		// Alternative JSON version
		// $url = 'http://twitter.com/statuses/update.json';
		// Set up and execute the curl process
		$curl_handle = curl_init();
		curl_setopt($curl_handle, CURLOPT_URL, 'http://localhost/restserver/index.php/example_api/user/id/1/format/json');
		curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, 1);
		curl_setopt($curl_handle, CURLOPT_POST, 1);
		curl_setopt($curl_handle, CURLOPT_POSTFIELDS, array(
			'name' => $new_name,
			'email' => $new_email
		));

		// Optional, delete this line if your API is open
		curl_setopt($curl_handle, CURLOPT_USERPWD, $username . ':' . $password);

		$buffer = curl_exec($curl_handle);
		curl_close($curl_handle);

		$result = json_decode($buffer);

		if(isset($result->status) && $result->status == 'success')
		{
			echo 'User has been updated.';
		}

		else
		{
			echo 'Something has gone wrong';
		}
    }

Interacting with your API this way works fine, but there are two problems with this method:

1. It uses an ugly confusing syntax – imagine creating several an application based on that.
2. cURL is not installed on all servers by default.

To solve this ugly syntax, a cURL library has been developed for CodeIgniter which simplifies things immensely.

The exact same request made with the cURL library would look like this:

    function ci_curl($new_name, $new_email)
    {
	    $username = 'admin';
		$password = '1234';

		$this->load->library('curl');

		$this->curl->create('http://localhost/restserver/index.php/example_api/user/id/1/format/json');

		// Optional, delete this line if your API is open
		$this->curl->http_login($username, $password);

		$this->curl->post(array(
			'name' => $new_name,
			'email' => $new_email
		));

		$result = json_decode($this->curl->execute());

		if(isset($result->status) && $result->status == 'success')
		{
			echo 'User has been updated.';
		}

		else
		{
			echo 'Something has gone wrong';
		}
    }

Much nicer to look at right? Well there is an even easier method to work with REST in your CodeIgniter applications that this.

REST client library

A REST client library has been developed that sits on top of this cURL library which handles format conversion, HTTP logins and several other aspects of your REST API.

    function rest_client_example($id)
    {
		$this->load->library('rest', array(
			'server' => 'http://localhost/restserver/index.php/example_api/',
			'http_user' => 'admin',
			'http_pass' => '1234',
			'http_auth' => 'basic' // or 'digest'
		));

        $user = $this->rest->get('user', array('id' => $id), 'json');

        echo $user->name;
    }

Here you can see we are making a GET request, sending id as a parameter and telling the library we want ‘json’ as the content format. This handles the setting of Content-type for you, and converts the data into a PHP object for you. You can change this value to ‘xml’, ‘json’, ’serialize’, ‘php’, ‘csv’ or any custom MIME-type you like, for example:

	$user = $this->rest->get('user', array('id' => $id), 'application/json');

As you have probably guessed as well as $this->rest->get(), the library also supports $this->rest->post(), $this->rest->put(), $this->rest->delete() to match all of your REST_Controller methods.

You will need to var_dump() results coming from the REST client library to make sure you are getting the right data format back. The conversion will somtimes be array and sometimes be an object, depending on how it is converted by PHP. If the returned MIME-type is not supported then it will simply return the format as plain-text.

Talking to Twitter

Using this REST library you can talk other RESTful services such as Twitter and Facebook. Here is a simple example of how you can get details for a specfic user based on their ID, using Twitter’s default format XML.

        $this->load->library('rest', array('server' => 'http://twitter.com/'));

        $user = $this->rest->get('users/show', array('screen_name' => 'philsturgeon'));

        $this->load->library('rest', array(
        	'server' => 'http://twitter.com/',
			'http_user' => 'username',
			'http_pass' => 'password',
			'http_auth' => 'basic'
        ));

        $user = $this->rest->post('statuses/update.json', array('status' => 'Using the REST client to do stuff'));

Looking at this, you will notice that interacting with the Twitter API is a bit different in a few ways.

1. They support URL based format switching in the form of .json instead of /format/json. Some require an extension, some do not; so it’s best to always add them.
2. They mostly only support GET/POST, but are starting to add more DELETE methods
3. They don’t always have just a resource in their URL, for example: users/search is one REST method, but lists is another.

Keep an eye out for these differences as they can catch you out. If you get stuck, simply echo $this->rest->debug() for a whole range of information on your REST request.

Summary

Combining what you now know about RESTful services, the CodeIgniter REST client library and the Twitter API documentation – or any other RESTful API documentation for that matter – you can create some very powerful applications that integrate with any custom or public web service using REST. You can extend your API by creating more REST_Controller’s and even make a modular API by using Matchbox or Modular Separation to create an api.php controller for each module to help keep your API as neatly organized as your application.

Write a Plus Tutorial

Did you know that you can earn up to $600 for writing a PLUS tutorial and/or screencast for us? We’re looking for in depth and well-written tutorials on HTML, CSS, PHP, and JavaScript. If you’re of the ability, please contact Jeffrey at nettuts@tutsplus.com.

Please note that actual compensation will be dependent upon the quality of the final tutorial and screencast.

• Follow us on Twitter, or subscribe to the Nettuts+ RSS Feed for the best web development tutorials on the web.

Step 1. Edit your Functions.php Page

// Enable support for post-thumbnails

add_theme_support('post-thumbnails');

// If we want to ensure that we only call this function if
// the user is working with WP 2.9 or higher,
// let's instead make sure that the function exists first

if ( function_exists('add_theme_support') ) {
	add_theme_support('post-thumbnails');
}

Step 2. Insert the Image Tag into your Loop

Within the “if have_posts()” loop, simply place this piece of code anywhere you like. At that point, WordPress will insert an image tag onto the page accordingly. Please note that you’ll have access to a “wp-post-image” class that you may then work with to format/style the image.

<?php the_post_thumbnail(); ?>

• Follow us on Twitter, or subscribe to the Nettuts+ RSS Feed for the best web development tutorials on the web.

Why You Should Join Plus

For those unfamiliar, the family of TUTS sites runs a premium membership service called “TUTSPLUS”. For $9 per month, you gain access to exclusive premium tutorials, screencasts, and freebies from Nettuts+, Psdtuts+, Aetuts+, Audiotuts+, and Vectortuts+! For the price of a pizza, you’ll learn from some of the best minds in the business. Become a Plus member.

• Subscribe to the Nettuts+ RSS Feed for more daily web development tuts and articles.

Tutorial Details

• Language: JavaScript
• Difficulty: Intermediate
• Estimated Completion Time: 30 minutes
• Required File: QUnit JS

What is QUnit

QUnit is a powerful JavaScript unit testing framework that helps you to debug code. It’s written by members of the jQuery team, and is the official test suite for jQuery. But QUnit is general enough to test any regular JavaScript code, and it’s even able to test server-side JavaScript via some JavaScript engine like Rhino or V8.

If you’re unfamiliar with the idea of “unit testing”, don’t worry. It’s not too difficult to understand:

In computer programming, unit testing is a software verification and validation method in which a programmer tests if individual units of source code are fit for use. A unit is the smallest testable part of an application. In procedural programming a unit may be an individual function or procedure.

This is quoted from Wikipedia. Simply put, you write tests for each functionality of your code, and if all of these tests are passed, you can be sure that the code will be bug-free (mostly, depends on how thorough your tests are).

Why You Should Test Your Code

If you haven’t written any unit tests before, you probably just apply your code to a website directly, click for a while to see if any problem occurs, and try to fix it as you spot one. There are many problems with this method.

First, it’s very tedious. Clicking actually is not an easy job, because you have to make sure everything is clicked and it’s very likely you’ll miss one thing or two. Second, everything you did for testing is not reusable, which means it’s not easy to find regressions. What is a regression? Imagine that you wrote some code and tested it, fixed all the bugs you found, and published it. Then, a user sends some feedback about new bugs, and requests some new features. You go back to the code, fix these new bugs and add these new features. What might happen next is that some of the old bugs come up again, which are called “regressions.” See, now you have to do the clicking again, and chances are you won’t find these old bugs again; even if you do, it’ll take a while before you figure out that the problem is caused by regressions. With unit testing, you write tests to find bugs, and once the code is modified, you filter it through the tests again. If a regression appears, some tests will definitely be failed, and you can easily spot them, knowing which part of the code contains the bug. Since you know what you have just modified, it can easily be fixed.

Another advantage of unit testing is especially for web development: it eases the testing of cross-browser compatibility. Just run your tests on different browsers, and if a problem occurs on one browser, you fix it and run these tests again, making sure it doesn’t introduce regression on other browsers. You can be sure that all of the target browsers are supported, once they all pass the tests.

I’d like to mention one of John Resig’s projects: TestSwarm. It takes JavaScript unit testing to a new level, by making it distributed. It’s a website that contains many tests, anyone can go there, run some of the tests, then return the result back to server. In this way, code can be tested on different browsers and even different platforms really quickly.

How to Write Unit Tests with QUnit

So how do you write unit tests with QUnit exactly? First, you need to set up a testing environment:

<!DOCTYPE html>
<html>
<head>
	<title>QUnit Test Suite</title>
	<link rel="stylesheet" href="http://github.com/jquery/qunit/raw/master/qunit/qunit.css" type="text/css" media="screen">
	<script type="text/javascript" src="http://github.com/jquery/qunit/raw/master/qunit/qunit.js"></script>
	<!-- Your project file goes here -->
	<script type="text/javascript" src="myProject.js"></script>
	<!-- Your tests file goes here -->
	<script type="text/javascript" src="myTests.js"></script>
</head>
<body>
	<h1 id="qunit-header">QUnit Test Suite</h1>
	<h2 id="qunit-banner"></h2>
	<div id="qunit-testrunner-toolbar"></div>
	<h2 id="qunit-userAgent"></h2>
	<ol id="qunit-tests"></ol>
</body>
</html>

As you can see, a hosted version of QUnit framework is used here.

The code that is going to be tested should be put into myProject.js, and your tests should be inserted into myTests.js. To run these tests, simply open this HTML file in a browser. Now it’s time to write some tests.

The building blocks of unit tests are assertions.

An assertion is a statement that predicts the returning result of your code. If the prediction is false, the assertion has failed, and you know that something has gone wrong.

To run assertions, you should put them into a test case:

// Let's test this function
function isEven(val) {
	return val % 2 === 0;
}

test('isEven()', function() {
	ok(isEven(0), 'Zero is an even number');
	ok(isEven(2), 'So is two');
	ok(isEven(-4), 'So is negative four');
	ok(!isEven(1), 'One is not an even number');
	ok(!isEven(-7), 'Neither is negative seven');
})

Here we defined a function, isEven, which detects whether a number is even, and we want to test this function to make sure it doesn’t return wrong answers.

We first call test(), which constructs a test case; the first parameter is a string that will be displayed in the result, and the second parameter is a callback function that contains our assertions. This callback function will get called once QUnit is run.

We wrote five assertions, all of which are boolean. A boolean assertion expects its first parameter to be true. The second parameter is also a message that will be displayed in the result.

Here is what you get, once you run the test:

Since all these assertions have successfully passed, we can be pretty sure that isEven() will work as expected.

Let’s see what happens if an assertion has failed.

// Let's test this function
function isEven(val) {
	return val % 2 === 0;
}

test('isEven()', function() {
	ok(isEven(0), 'Zero is an even number');
	ok(isEven(2), 'So is two');
	ok(isEven(-4), 'So is negative four');
	ok(!isEven(1), 'One is not an even number');
	ok(!isEven(-7), 'Neither does negative seven');

	// Fails
	ok(isEven(3), 'Three is an even number');
})

Here is the result:

The assertion has failed because we deliberately wrote it wrong, but in your own project, if the test doesn’t pass, and all assertion are correct, you know a bug has been found.

More Assertions

ok() is not the only assertion that QUnit provides. There are other kinds of assertions that are useful when testing your project:

Comparison Assertion

The comparison assertion, equals(), expects its first parameter (which is the actual value) is equal to its second parameter (which is the expected value). It’s similar to ok(), but outputs both actual and expected values, making debugging much easier. Like ok(), it takes an optional third parameter as a message to be displayed.

So instead of:

test('assertions', function() {
	ok( 1 == 1, 'one equals one');
})

You should write:

test('assertions', function() {
	equals( 1, 1, 'one equals one');
})

Notice the last “1″, which is the comparing value.

And if the values are not equal:

test('assertions', function() {
	equals( 2, 1, 'one equals one');
})

It gives a lot more information, making life a lot easier.

The comparison assertion uses “==” to compare its parameters, so it doesn’t handle array or object comparison:

test('test', function() {
	equals( {}, {}, 'fails, these are different objects');
	equals( {a: 1}, {a: 1} , 'fails');
	equals( [], [], 'fails, there are different arrays');
	equals( [1], [1], 'fails');
})

In order to test this kind of equality, QUnit provides another kind assertion: identical assertion.

Identical Assertion

Identical assertion, same(), expects the same parameters as equals(), but it’s a deep recursive comparison assertion that works not only on primitive types, but also arrays and objects. Assertions, in the previous example, will all pass if you change them to identical assertions:

test('test', function() {
	same( {}, {}, 'passes, objects have the same content');
	same( {a: 1}, {a: 1} , 'passes');
	same( [], [], 'passes, arrays have the same content');
	same( [1], [1], 'passes');
})

Notice that same() uses ‘===’ to do comparison when possible, so it’ll come in handy when comparing special values:

test('test', function() {
	equals( 0, false, 'true');
	same( 0, false, 'false');
	equals( null, undefined, 'true');
	same( null, undefined, 'false');
})

Structure Your Assertions

Putting all assertions in a single test case is a really bad idea, because it’s very hard to maintain, and doesn’t return a clean result. What you should do is to structure them, put them into different test cases, each aiming for a single functionality.

You can even organize test cases into different modules by calling the module function:

module('Module A');
test('a test', function() {});
test('an another test', function() {});

module('Module B');
test('a test', function() {});
test('an another test', function() {});

Asynchronous Test

In previous examples, all assertions are called synchronously, which means they run one after another. In the real world, there are also many asynchronous functions, such as ajax calls or functions called by setTimeout() and setInterval(). How can we test these kinds of functions? QUnit provides a special kind of test case called “asynchronous test,” which is dedicated to asynchronous testing:

Let’s first try to write it in a regular way:

test('asynchronous test', function() {
	setTimeout(function() {
		ok(true);
	}, 100)
})

See? It’s as if we didn’t write any assertion. This is because the assertion ran asynchronously, by the time it got called, the test case had already finished.

Here is the correct version:

test('asynchronous test', function() {
	// Pause the test first
	stop();

	setTimeout(function() {
		ok(true);

		// After the assertion has been called,
		// continue the test
		start();
	}, 100)
})

Here, we use stop() to pause the test case, and after the assertion has been called, we use start() to continue.

Calling stop() immediately after calling test() is quite common; so QUnit provides a shortcut: asyncTest(). You can rewrite the previous example like this:

asyncTest('asynchronous test', function() {
	// The test is automatically paused

	setTimeout(function() {
		ok(true);

		// After the assertion has been called,
		// continue the test
		start();
	}, 100)
})

There is one thing to watch out for: setTimeout() will always call its callback function, but what if it’s a custom function (e.g, an ajax call). How can you be sure the callback function will be called? And if the callback is not called, start() won’t be called, and the whole unit testing will hang:

So here is what you do:

// A custom function
function ajax(successCallback) {
	$.ajax({
		url: 'server.php',
		success: successCallback
	});
}

test('asynchronous test', function() {
	// Pause the test, and fail it if start() isn't called after one second
	stop(1000);

	ajax(function() {
		// ...asynchronous assertions

		start();
	})
})

You pass a timeout to stop(), which tells QUnit, “if start() isn’t called after that timeout, you should fail this test.” You can be sure that the whole testing won’t hang and you’ll be notified if something goes wrong.

How about multiple asynchronous functions? Where do you put the start()? You put it in setTimeout():

// A custom function
function ajax(successCallback) {
	$.ajax({
		url: 'server.php',
		success: successCallback
	});
}

test('asynchronous test', function() {
	// Pause the test
	stop();

	ajax(function() {
		// ...asynchronous assertions
	})

	ajax(function() {
		// ...asynchronous assertions
	})

	setTimeout(function() {
		start();
	}, 2000);
})

The timeout should be reasonably long enough to allow both callbacks to be called before the test continues. But what if one of the callback isn’t called? How can you know that? This is where expect() comes in:

// A custom function
function ajax(successCallback) {
	$.ajax({
		url: 'server.php',
		success: successCallback
	});
}

test('asynchronous test', function() {
	// Pause the test
	stop();

	// Tell QUnit that you expect three assertions to run
	expect(3);

	ajax(function() {
		ok(true);
	})

	ajax(function() {
		ok(true);
		ok(true);
	})

	setTimeout(function() {
		start();
	}, 2000);
})

You pass in a number to expect() to tell QUnit that you expect X many assertions to run, if one of the assertion isn’t called, the number won’t match, and you’ll be notified that something went wrong.

There is also a shortcut for expect(): you just pass the number as the second parameter to test() or asyncTest():

// A custom function
function ajax(successCallback) {
	$.ajax({
		url: 'server.php',
		success: successCallback
	});
}

// Tell QUnit that you expect three assertion to run
test('asynchronous test', 3, function() {
	// Pause the test
	stop();

	ajax(function() {
		ok(true);
	})

	ajax(function() {
		ok(true);
		ok(true);
	})

	setTimeout(function() {
		start();
	}, 2000);
})

Conclusion

That’s all you need to know to get started witih QUnit. Unit testing is a great method to test your code before publishing it. If you haven’t written any unit tests before, it’s time to get started! Thanks for reading!

• Follow us on Twitter, or subscribe to the Nettuts+ RSS Feed for the best web development tutorials on the web.

“HipHop for PHP isn’t technically a compiler itself. Rather it is a source code transformer. HipHop programmatically transforms your PHP source code into highly optimized C++ and then uses g++ to compile it. HipHop executes the source code in a semantically equivalent manner and sacrifices some rarely used features — such as eval() — in exchange for improved performance. HipHop includes a code transformer, a reimplementation of PHP’s runtime system, and a rewrite of many common PHP Extensions to take advantage of these performance optimizations.”

The Announcement

“Scaling Facebook is particularly challenging because almost every page view is a logged-in user with a customized experience. When you view your home page we need to look up all of your friends, query their most relevant updates (from a custom service we’ve built called Multifeed), filter the results based on your privacy settings, then fill out the stories with comments, photos, likes, and all the rich data that people love about Facebook. All of this in just under a second. HipHop allows us to write the logic that does the final page assembly in PHP and iterate it quickly while relying on custom back-end services in C++, Erlang, Java, or Python to service the News Feed, search, Chat, and other core parts of the site.”

The Problems Facebook Faced with PHP

• Can’t reuse PHP logic in other systems
• Extensions are harder to write for PHP developers
• High CPU usage; can’t be as efficient as something like C++
• Fully impractical to completely rewrite Facebook with a new language

How They Improved It

• It’s a source code transformer
• Transforms PHP into optimized C++, then compiled with G++
• Has been in development for over two years.
• If you’ve used Facebook within the last six months, you’ve experience Hip Hop
• Facebook team have recorded a 50% decrease in CPU usage.
• They’ll have dedicated evangelists to help train/familiarize the community with Hip Hop
• If you’re on a shared host, using Apache, you’ll most likely want to continue using standard PHP

Where Can We Start Playing with It?

Hip Hop is available now, and is hosted on Github. You can download it here.


• Follow us on Twitter, or subscribe to the Nettuts+ RSS Feed for the best web development tutorials on the web.
]]> http://net.tutsplus.com/articles/news/facebook-hopes-to-revolutionize-php-with-hip-hop/feed/ 54