After the Deadline is an open source software service that checks spelling, style, and grammar. This package contains an AtD API and examples for using After the Deadline in your web application.
The AtD API is available by including scripts/jquery.atd.js in your webpage. There are two methods for talking to the AtD service: cross-domain AJAX and normal calls. The following functions work with either:
AtD.addI18n({strings}) is a means to install a new set of strings into this extension for localization.
AtD.getLang('key', 'default value') looks up the key in the plugin strings table. If the key is no present the default value is returned. Use this method to query the strings table for localized strings.
AtD.ignore_types is an array of strings specifying which types of errors to ignore. By default all errors are ignored except misspelled words, misused words, and grammar errors. All the style checking options are disabled. The following types are available: Bias Language, Cliches, Complex Expression, Diacritical Marks, Double Negatives, Hidden Verbs, Jargon Language, Passive voice, Phrases to Avoid, and Redundant Expression.
AtD.remove('id') is a function to remove all the AtD markup from the DIV with the specific id.
AtD.setIgnoreStrings('a,b,c') is a function to set which strings AtD should ignore. Separate phrases with a comma.
AtD.showTypes('Complex Expression') is a function to update AtD.ignore_types by removing the specified types. Separate multiple types with a comma.
The AtD.check() function expects to call a proxy script located on the same server as the page you've embedded AtD into.
AtD.api_key is a string containing a unique key identifying this AtD user. You get to make this value up. Ideally, use a string to identify your application followed by a string that is unique to this user or installation of AtD. There is a performance benefit to using the same key for subsequent requests.
AtD.check('id', callbacks) checks the spelling, style, and grammar in the specified DIV id using the server-side proxy communication method. The callbacks object is a
hash containing success and error functions that are called when appropriate. The API for these functions is the same as checkCrossAJAX(). The callbacks
object may also contain editSelection, explain, ignore, and ready functions. There is no set limit on the length of the text using this method.
The callback functions used with AtD.check() include:
The editSelection function, which is called with a JavaScript object containing an HTML element with the error. When set, AtD will show an Edit Selection ... menu item. The user should be prompted for an alternate suggestion after clicking this menu item. This exists to get around the inconvenience of not being able to edit text while correcting it. demo2.html uses this feature.
The explain function, which is called with a string containing a URL. When set, AtD will show an Explain ... menu item for errors that have an explanation.
The error function, which is called with a string containing an error message. This function is called when an error occurred that prevented the checking of the document.
The ignore function, which is called with a string containing a word or phrase to ignore. When set, AtD will show an Ignore Always menu item to permanently ignore an error. It's up to you to store the phrase or word when the ignore function is called.
The ready function, which is called with an integer containing the number of errors found. This function is called when the request to the AtD service is complete.
The success function, which is called with an integer containing the number of errors found. This function is called after the document has been checked and all errors have been ignored or corrected.
AtD.rpc is a string containing the URL for the AtD proxy script. This value is used by the check() function. Point this to server/proxy.php
included in this package. If you use proxy.php you should set AtD.rpc to 'proxy.php?url='. Use of the server-side proxy will decrease the wait time
for responses and there is no character limit.
The cross-domain AJAX API lets you communicate with an AtD server on a separate domain. If you use this method with our CSS proxy server you don't need an API key. BUT you're at
a disadvantage if you do this. Our CSS proxy is on a single server and the AtD app server only allows one concurrent request/key. Your best option is to set AtD.rpc_css
and set your (made up) key in server/proxycss.php.
AtD.checkCrossAJAX('id', callbacks) checks the spelling, style, and grammar in the specified DIV id using the remote CSS includes method. In my opinion this is a total hack (but it does work!). The callbacks object is a hash as described above. See demo and demo2 for practical examples of how this works. Internet Explorer users are limited to 2,000 characters using this method and other browsers are limited to ~7,500 characters.
AtD.rpc_css is a string containing the URL for an AtD proxy script that encodes AtD requests as a CSS file compatible with the CSSHttpRequest call developed by nb.io. This value is already set to a proxy you can use for personal projects and testing. If you choose to run an AtD server, you can set this value to something else. The server/proxycss.php file shows how to communicate with AtD with remote CSS includes.
AtD.rpc_css_lang is the desired proofreading language (one of: de, en, es, fr, or pt). We use a separate server for each language (e.g., [lang].service.afterthedeadline.com). Specifying this value tells proxycss.php which server to send the request to. The normal AtD API does not have this value as I assume you control the proxy mechanism and can specify which server your AtD requests go to.
The TextArea API is available by loading scripts/jquery.atd.textarea.js. This API allows you to check a textarea when a link is clicked.
AtD.checkTextArea('id', 'linkId', 'link HTML after clicking') checks the spelling, style, and grammar in the specified TEXTAREA id by posting to the server-side proxy. The linkId is the id of the link that activates this method. When clicked the HTML will be changed to link HTML after clicking. This will signal to the user that the textarea is in proofreading mode. Clicking the link again will restore the original textarea and link HTML.
AtD.checkTextAreaCrossAJAX('id', 'linkId', 'link HTML after clicking') checks the spelling, style, and grammar in the specified TEXTAREA id using the remote CSS includes communication method. The options are the same as described above.
AtD._checkTextArea('id', function(), 'linkId', 'link HTML after clicking') checks the spelling, style, and grammar in the specified TEXTAREA id by calling the function() passed in the second parameter. This function will receive the AtD DIV id and a JavaScript object callbacks as described in the AtD.check() API. You can call this version of _checkTextArea to intercept the callbacks and modify them or add new behaviors. Do this if you need full control.
AtD.restoreTextArea('id') will strip the After the Deadline errors and restore the TEXTAREA. You can safely call this function if no spell check is in progress. It will do nothing at that point. I recommend calling this function before submitting a form with an AtD textarea attached.
The API above gives you full control over what AtD does. If you'd like to get going quicker and you have a basic form, then the jQuery style API is what you want. To attach AtD to a textarea:
$(textarea).addProofreader({ edit_text_content: 'Edit Text', proofread_content: 'Proofread' );
This call will also hook the parent form's submit event to restore the textarea for you.
You can customize the HTML used for the proofread and edit text links. If you want to communicate using a proxy, set AtD.rpc and AtD.api_key to the appropriate values and the proofreader will use that communication method instead.
You may customize the suggestions menu and the error styles in css/atd.css.
The best way to learn to use the AtD API is to look at the examples and adapt them to your needs. The two examples included are:
To localize the strings in this extension, create an object with the localized strings. Here is an example:
var my_plugin_strings = {
menu_title_spelling: "Spelling",
menu_title_repeated_word: "Repeated Word",
menu_title_no_suggestions: "No suggestions",
menu_option_explain: "Explain...",
menu_option_ignore_once: "Ignore suggestion",
menu_option_ignore_all: "Ignore all",
menu_option_ignore_always: "Ignore always",
menu_option_edit_selection: "Edit Selection...",
message_no_errors_found: "No writing errors were found.",
message_server_error_short: "There was a problem communicating with the After the Deadline service.",
dialog_replace_selection: "Replace selection with:"
};
Then make AtD use these strings:
AtD.addI18n(my_plugin_strings);
These string labels are compatible with the AtD/TinyMCE extension.
We have an AtD service instance open to the outside world. This API is configured to use it by default. We will continue to operate it so long as the load on it is not too great. The After the Deadline Server is open source under the GPLv2 license. Consider running your own server if you have a commercial need.
As a final note, make sure your webpage is encoded in UTF-8 format. AJAX requests use the encoding of the parent website and AtD expects UTF-8. This is important as AtD has better support for accented characters and languages beyond English.
See the Change Log.
Unless otherwise noted, the resources here are dual licensed under LGPL and MIT license.
The files scripts/csshttprequest.js and server/cssencode.php are © 2008-2009 nb.io and are licensed under the BSD license.
Join the atd-developers list for support.