After the Deadline

1. Why After the Deadline

Welcome to Raffi’s practical guide to adding After the Deadline to your application. After the Deadline is a technology that checks spelling, style, and grammar. Through it you can bring word processor quality writing tools to the users of your application. And it’s open source. How much better can it get?

2. Server Software

After the Deadline uses a client-server architecture. Your program embeds code that talks to an After the Deadline server. When the user clicks the spellcheck button their document is sent to a server, processed, and the errors are sent back. This code in your application then proceeds to highlight these errors and present them to the user.

To add After the Deadline to your application you will need to run an After the Deadline server. You can download the code for the server from:

http://open.afterthedeadline.com/download/download-source-code/

You only need the source code package and don’t worry–precompiled binaries are distributed in the package.

To run After the Deadline you’ll need Java 1.6.0 and 4GB of memory. You can put it on a virtual machine so long as it has enough memory. After the Deadline will happily use as many CPU cores as you can give it. If you’re not processing a lot of requests you’ll only need a single core. We run our After the Deadline server on an eight core machine but we have a lot of users, your needs may vary.

The memory requirements are steep but this is because After the Deadline loads its language models into memory. After the Deadline uses these models to make smart spelling corrections, decide if a word is misused, and to avoid bogus grammar and style errors.

Installation of After the Deadline is pretty easy. Extract the archive where ever you like and execute ./run.sh to start the server. We’ve run the After the Deadline server on Linux and MacOS X

After the Deadline will listen on port 1049 of your localhost. For security reasons it only accepts connections from 127.0.0.1. We use nginx to proxy connections from port 80 to 127.0.0.1:1049. You can do this or if you’re feeling adventurous you can edit run.sh and change -Dbind.interface=127.0.0.1 to reflect the external IP address of your server.

Regardless of which choice you make, you’ll want to take note of the IP address and port number of your After the Deadline server. We will use this information later.

3. Talking to the Server

As a security measure, JavaScript uses a same origin policy for AJAX calls. JavaScript executed on a webpage can only send requests to the server the script was downloaded from. It’s quite understandable that you’ll want to run After the Deadline on hardware that is separate from your web server. This poses a problem as this policy prevents any front-end integration from talking to your After the Deadline server.

The solution to this problem is to create a proxy script on your webserver that receives AJAX calls and sends them to your After the Deadline server. In our TinyMCE and jQuery packages we include this proxy.php file that you can modify to your needs.

$API_KEY = "";

if ( $_SERVER['REQUEST_METHOD'] === 'POST' )
{
 $postText = trim(file_get_contents('php://input'));
}

if (strcmp($API_KEY, "") != 0)
{
 $postText .= '&key=' . $API_KEY;
}

$url = $_GET['url'];

/* this function directly from akismet.php by Matt Mullenweg.  *props* */
function AtD_http_post($request, $host, $path, $port = 80)
{
 $http_request  = "POST $path HTTP/1.0\r\n";
 $http_request .= "Host: $host\r\n";
 $http_request .= "Content-Type: application/x-www-form-urlencoded\r\n";
 $http_request .= "Content-Length: " . strlen($request) . "\r\n";
 $http_request .= "User-Agent: AtD/0.1\r\n";
 $http_request .= "\r\n";
 $http_request .= $request;

 $response = '';
 if( false != ( $fs = @fsockopen($host, $port, $errno, $errstr, 10) ) )
 {
   fwrite($fs, $http_request);

   while ( !feof($fs) )
   {
     $response .= fgets($fs);
   }
   fclose($fs);
   $response = explode("\r\n\r\n", $response, 2);
 }
 return $response;
}

$data = AtD_http_post($postText, "service.afterthedeadline.com", $url);

header("Content-Type: text/xml");
echo $data[1];
?>

To adapt this script, change service.afterthedeadline.com in line 42 to the address of your server. I don’t recommend hardcoding an API key as the After the Deadline server caches information about your writing and uses the key to lock this data structure. If every request uses the same key, you will unnecessarily bottleneck those requests.

If your After the Deadline server receives requests on a port other than port 80, you may append this port to the AtD_http_post function after $url:

$data = AtD_http_post($postText, "192.168.1.101", $url, 1049);

If you don’t use PHP on your server then you will need to create your own AJAX proxy script. This is a common problem and several solutions are available for most languages.

Now that you have a proxy script, note this URL as we will use it when we integrate After the Deadline with your application’s front-end.

4. Front-End Integration

Now that you have a server and a means to communicate with it, the last step is to integrate After the Deadline into the front-end of your web application. Several options are available at http://www.afterthedeadline.com/development.slp. Here I will focus on the After the Deadline extension for jQuery. jQuery is a JavaScript library that removes the pain of working with multiple browsers.

Download the After the Deadline package for jQuery and extract it on your webserver. You can get it from: http://www.afterthedeadline.com/download.slp?platform=jQuery

Adding After the Deadline to an application involves:

1. loading the right resources
2. creating your form
3. telling the After the Deadline jQuery package where to find your proxy script
4. creating functions to check the right form element and restore the form before submitting.

Our example application is a car review website. Ok, it’s not much of an application but it illustrates these steps. It contains a TEXTAREA where the user is expected to write their review. It also has a Check Spelling link that the user can click to check their writing.

Here is a screenshot of this application in action:

Here is the code to the application:

<html>
 <head>
 <title>Write a review of your car</title>

 <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3/jquery.min.js"></script>
 <script src="scripts/jquery.atd.js"></script>
 <script src="scripts/csshttprequest.js"></script>
 <link rel="stylesheet" type="text/css" media="screen" href="css/atd.css" />
 <script src="scripts/jquery.atd.textarea.js"></script>

 <script>
 function check()
 {
    AtD.checkTextArea('review', 'checkLink', 'Edit Text');
 }

 function submit()
 {
    AtD.restoreTextArea('review');
    jQuery('#reviewForm').submit();
 }

 AtD.rpc = 'server/proxy.php?url=';
 AtD.api_key = ( new Date() ).getMinutes();
 </script>

 </head>
 <body>

 <h1>Review your car!</h1>

 <p>Please write a review of your car so others may learn.</p>

 <form id="reviewForm">
   <textarea id="review" name="review" class="input" style="width: 400px; height: 100px; border: 1px solid black"></textarea>
   <p><a href="javascript:submit()">Submit Review</a> | <a href="javascript:check()" id="checkLink">Check Spelling</a></p>
 </form>
 </body>
</html>

Lines 7-9 load the After the Deadline resources. You can change the look of the After the Deadline markup by modifying css/atd.css. Line 5 loads jQuery. You want to make sure you do this first.

Lines 34-37 contain the car review form. Line 35 has the TEXTAREA. Note that the value of its id is review. I have also embedded some style information into the TEXTAREA element. When you click the check spelling button, the After the Deadline jQuery extension will do its best to mimic the look of the original TEXTAREA. You can put this information inline or assign a class to the TEXTAREA. If you want the spellchecker mode to pick up the style information, make sure it works with a DIV as well as a TEXTAREA.

Lines 23 and 24 tell the After the Deadline jQuery extension where to find your proxy script. You’ll notice I set the key to a random value.  I did this because you’re using your own server. Despite this, the After the Deadline jQuery extension expects an API key when talking to a proxy script.

In line 36 you’ll notice that Submit Link is set to call the JavaScript submit function. This function is defined on lines 17-21. In line 19 I call a function to restore your TEXTAREA before submitting the form. This is important as After the Deadline replaces the TEXTAREA with a DIV during proofreading. This function does nothing if the TEXTAREA doesn’t need to be restored.

Line 36 also has a Check Spelling link that calls a JavaScript check function. This function is defined on lines 12-15. On line 14 I call an After the Deadline jQuery extension function to check the TEXTAREA. The first parameter is the id of the TEXTAREA. The second parameter is the id of the check spelling link. Within this link you can use any HTML you like. The third parameter is what the link should say when After the Deadline is checking the TEXTAREA. This is a good place to tell the user that their text is not editable.

You can try this example at http://www.polishmywriting.com/atd_jquery/carreview.html.

5. Can I use After the Deadline with my application?

The After the Deadline server software is released under the GNU General Public License (GPL). You’re welcome to use and redistribute this server software even for commercial purposes. If you choose to redistribute the After the Deadline server with your changes then you must make the source code with your changes available under the GNU General Public License. This only applies to the After the Deadline server software. Since this software is a stand-alone server, the requirements of the GPL shouldn’t burden you too much.

The client side libraries like the jQuery extension are available under the GNU Lesser General Public License. This license grants you the same freedoms as the GPL while including an exception that states only changes to the library need to be redistributed with source code. You’re able to use these libraries in your closed source application.

6. The Next Step

Now you know how to add After the Deadline to your application. It’s a simple matter of installing the server, creating a proxy, and integrating with your front-end.

If you have questions, you’re encouraged to ask them on the atd-developers mailing list.