# After the Deadline Core UI Module - README

After the Deadline is an open source software service that checks spelling, style, and grammar. This package contains an adaptable JavaScript object to make it easier to add After the Deadline to other WYSIWYG editors and libraries.

This package includes logic to parse the AtD XML protocol, walk a DOM structure and highlight errors, remove highlighted errors, and locate error metadata and suggestions given a highlighted element. If you intend to use AtD beyond the maintained front-end plugins, this extension will save you time.

### Using the Module

To use this module, you must instantiate it and then add several functions to the module to tell it how to perform certain actions in your environment. To instantiate this module:

`var core = new AtDCore();`

The functions that you must define are:

`core.map(array, callback)` should iterate over the array and call the callback function on each item.

`core.hasClass(element, className)` should return true if the specified has the CSS class className.

`core.contents(element)` should return an array of all childnodes of the element.

`core.replaceWith(old_element, new_element)` should replace the old_element with the new_element in the DOM.

`core.create(html_string)` should create a new DOM element from the HTML string. This function must also wrap this new DOM element in a span with the class mceItemHidden.

`core.removeParent(element)` should remove this element from the DOM. This node's children should be kept (and attached to this node's parent).

`core.remove(element)` should remove this element and its children from the DOM.

`core.getAttrib(element, name)` returns the string value of the attribute named name of the specified element.

`core.findSpans(element)` should return an array of all children of element that are a span tag. The only argument for element will be the parent of the DOM you're highlighting with AtD errors. This is used by the `removeWords` function in the module. The argument you provide to `removeWords` is passed to this function.

You are responsible for adding the contents of the atd.css stylesheet to your application or library. These styles tell your browser how to display the AtD markup to your user.

Once you load the stylesheet and provide implementations of these functions to the module, then you can use the Core UI API.

### Core UI API

core.applySuggestion(element, suggestion_string) modifies the marked up element according to the suggestion string. For most errors this is a direct replacement. For the (omit) suggestion, the element is removed.

core.findSuggestion(element) returns a JavaScript object with suggestions and metadata about the error the specified element is marked up with. The object has the following fields:

Field | Description
--- | ---
suggestions | a sorted array of strings, representing suggestions for the error
description | a string with a 1-3 word description of the error
moreinfo | (may be undefined) a URL to get more information about the error

core.getErrorMessage(xml_object) extracts the error message from the XML object.

core.hasErrorMessage(xml_object) returns true if the XML object (returned by the AtD server, I presume) has an error message.

core.isMarkedNode(element) returns true if the specified element contains AtD markup (meaning it's a writing error).

core.markMyWords(element, errors) walks the specified element and highlights the errors (the errors field from the object returned by processXML()) you provide. The element should be the root of your content's DOM.

core.processXML(xml_object) processes XML returned by the After the Deadline server. This function returns a JavaScript object with the following fields:

Field | Description
--- | ---
count | The number of errors returned by the AtD server. Some of these may not be highlighted, so this number is an upperbound.
errors | An object with the errors in the document, their context, metadata, and suggestions.

core.removeWords(element) walks the specified element and its children removing the AtD markup. You should call this before the contents of your library is returned and before calling `markMyWords` on your content.

core.setIgnoreStrings("a,b,c") expects a comma separated list of strings for AtD ignore. AtD will filter errors matching these strings for you. You should call this before calling `processXML`.

core.showTypes("a,b,c") expects a comma separated list of AtD error types to show. By default only spelling errors, misused words, and grammar mistakes are shown. The types you can specify are: "Bias Language,Cliches,Complex Expression,Diacritical Marks,Double Negatives,Hidden Verbs,Jargon Language,Passive voice,Phrases to Avoid,Redundant Expression". You should call this before calling `markMyWords`.

### Development Tips

Here are some tips I've learned the hard way:

1. Wrap your functions that call this API in a try/catch block and make sure you're notified when an exception occurs. Some libraries *cough*CKEditor*cough* think its a good idea to swallow all uncaught exceptions. By wrapping your code in a try/catch block you'll be able to handle uncaught exceptions by notifying yourself.
2. Use Firebug and console.log() to show you what the methods you defined for the core UI module are receiving and returning. If any of these functions fails to work as expected then the core UI module will break in mysterious ways.

### Examples

There are several examples of this module in action, they include:

- AtD/CKEditor
- AtD/jQuery
- AtD/TinyMCE

### Localization

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",
    };

Then make AtD use these strings:

    core.addI18n(my_plugin_strings);

Optionally, you can redefine the `core.getLang("key", "default")` function to hook into your libraries localization function. This module uses the menu_title_spelling and menu_title_repeated_word keys.

### What's New?

See the Change Log.

### License

Unless otherwise noted, the resources here are licensed under LGPL.

### Contact

Raphael Mudge, Automattic

Join the atd-developers list for support.