Javascript Events and API for ASPNetSpell


ASPNetSpell has a full JavaScript API allowing the advanced developer to capture events and modify behaviour of spell-checkers at client runtime.

This demo shows the Javscript API capturing the onDialogOpen and onChangeWord (as-you-type) events.

ASPNetSpell has a full JavaScript API allowing the advanced developer to capture events and modify behaviour of spell-checkers at client runtime.

Simple .Net Event Model - OnSpellCheckComplete

If you just want to submit a form upon spell-check dialog completion - see the ASP.Net SpellButton Event - OnSpellCheckComplete


JavaScript Event Model

Each SpellButton and SpellTextArea at the server side are paired with a clientside instance of LiveSpellOject - a Javascript class documented below.

  • You can acess this API using the JavaScript identifier JavaScriptId for each object
    • E.g.<%= SpellButton1.JavaScriptId%>
  • This code must be placed AFTER the last <form> tag on the page
  • The script tag should have the 'defer' attribute set for IE compatibility.
SourceCode:
<form id="form1" runat="server">
           <ASPNetSpell:SpellTextBox ID="SpellTextBox1" runat="server">
            ...
            </ASPNetSpell:SpellTextBox>

           <ASPNetSpell:SpellButton ID="SpellButton1" runat="server" />
</form>

<script type='text/javascript' defer='defer' > 
// This script must come after the end of the < /form > tag 	 
// Notice the defer='defer' attribute for IE compatibility

 	var mySpellButton= <%=SpellButton1.JavaScriptId%>;
	mySpellButton.onDialogOpen = function(){ alert("onDialogOpen Dialog Event fired by SpellButton1")}

	var mySpellTextBox= <%=SpellTextBox1.JavaScriptId%>;
	mySpellTextBox.onChangeWord = function(){ alert("onChangeWord As-You-Type Event fired by SpellTextBox1")}
</script>

Events can apply to both as-you-type and in dialog spellchecking as needed:

  • onDialogOpen
  • onDialogComplete
  • onDialogCancel
  • onDialogClose
  • onChangeLanguage
  • onIgnore
  • onIgnoreAll
  • onChangeWord
  • onChangeAll
  • onLearnWord
  • onLearnAutoCorrect
  • onUpdateFields

Full JavasScpit Object Reference

Class LiveSpellObject

Defined in /ASPNetSpellInclude/include.js



SourceCode:
<script src="/ASPNetSpellInclude/include.js' type='text/javascript'></script>
<script type='text/javascript'>
// E.g. 
var mySpell = new LiveSpellInstance();
mySpell.Fields = "ALL"
mySpell.ServerModel="aspx"
mySpell.DrawSpellImageButton()
mySpell.ActivateAsYouType()
</script>


Core Properties
CaseSensitive Bool True Consider case mistakes when spellchecking?
CheckGrammar Bool True Check for structural grammar errors such as repeated words, and sentence casing.
CSSTheme String "classic" Theme for the spell-checker UI context menu and spelling dialog window. Maps to a folder name within /ASPNetSpellInclude/themes/
Fields String "ALL" Sets the html elements to be spell-checked by this instance.
  • Multiple fields may be set using:
    • a "comma,separated,list" or
    • array("an","array","of","ids").
  • Each field must have an InnerHTML or Value property.
FormToSubmit String "" A form id to submit upon successful spellchecking using the dialog.
IgnoreAllCaps Bool True Ignore ALL CAPITALIZED words
IgnoreNumeric Bool true gnore strings with numbers in them which are often product codes or serial numbers.
  • E.g. HSH-S872-282P
Language String "English (International)" Dictionary language to be used for spellchecking.
  • This maps to a ".dic" dictionary in your /ASPNetSpellInclude/dictionaries directory
  • Multiple languages can be set simultaneously using a comma separated list
    • E.g. "English (International), Svenska"
UserInterfaceLanguage String "en" Translation ANSI language code for the spellchecker dialogue and context menu.
  • This maps to a ".js" language file in your /ASPNetSpellInclude/translaions directory
ServerModel String "php" Server hypertext processing language. Needs to be set to "aspx" or "asp.net" for .net applications
Advanced Setup Properties
CustomOpener function null Set a custom function which will override the regular spell-checker window opening method.
  • Also see function url()
CustomOpener function null Set a custom function which can be set to override the regular spell-checker window opening method.
CustomOpenerClose function null Set a custom function called when spellchecking in a CustomOpener scenario is completed.
Delay integer 888 Delay in milliseconds between the user finishing typing and As-You-Type fields having their spelling re-validated.
WindowMode String "modal" Sets the behavior of the spellchecker dialog to either:
  • "modal" - a floating toolbar linked to the opening page
  • "popup" - a popup browser window
Strict Bool true Enforces "Banned Words" and "Enforced Corrections" such that they cannot be ignored.
ShowSummaryScreen Bool true Shows a summary of statistics after a spell checker dialog has successfully finished.
ShowMeanings Bool true Shows the meaning of words and thesaurus using the "Lookup meaning..." link in the spell checker dialog.
  • Also see MeaningProvider
MeaningProvider String "http://www.thefreedictionary.com/{word}" The URL expression that the meaning lookup will go to for definitions and synonyms
UndoLimit Integer 20 Maximum remembered levels of user undo.
HiddenButtons String "" A "comma,separated,list" of buttons to be removed from the spell-checker dialog and context menu - identified by their id
HiddenButtons String "" A "comma,separated,list" of buttons to be removed from the spell-checker dialog and context menu - identified by their id
HiddenButtons String "" A "comma,separated,list" of buttons to be removed from the spell-checker dialog and context menu - identified by their id
Methods
checkInWindow() Spell checks your Fields in a pop-up dialog window. No Arguments Returns: null
checkInSitu() Spell checks your text-area fields in place using red-wiggly-underlining and a context menu. No Arguments Returns: null
activateAsYouType() All textarea fields named in the Fields property will now automatically validate spelling in context when their value changes due to user interaction. No Arguments Returns: null
pauseAsYouType() Pauses the behavior started by the activateAsYouType function No Arguments Returns: null
Rendering Methods
url() Returns the URL used to open the spell-checker dialog window. No Arguments Returns: String
url() Returns the URL used to open the spell-checker dialog window. No Arguments Returns: String
DrawSpellButton([inPlace] [,text] [,Class] [,style] ) document.writes a SpellButton Arguments: see SpellButton function Returns: null - writes an element to the HTML DOM
DrawSpellImageButton ([inPlace] [,image] [,rollover] [,text] [,Class] [,style]) document.writes a SpellImageButton Arguments: see SpellImageButton function Returns: null - writes an element to the HTML DOM
DrawSpellLink([inPlace] [,text] [,Class] [,style] ) document.writes a SpellLink Arguments: see SpellLink function Returns: null - writes an element to the HTML DOM
SpellButton([inPlace] [,text] [,Class] [,style] ) Returns an HTML string for a form button that will open a spellchecker. Arguments:
  • inPlace (boolean) [Default Value:false]. Spell-check will take place in the context of the text area (true) - or in a popup window (false)
  • text (string) [Default Value:"Spell Check"] - the value attribute of the button
  • Class (string) [Default Value:""] CSS class to be applied to the button
  • style (string) [Default Value:""] The CSS style attribute to be applied to the button
Returns: (string) of the button's full html
SpellImageButton ([inPlace][,image,][,rolloverImage][,Class][,style]) Returns an HTML string for an image with rollover effect that will open a spellchecker. Arguments:
  • inPlace (boolean) [Default Value:false]. Spell-check will take place in the context of the text area (true) - or in a popup window (false)
  • text (string) [Default Value:"Spell Check"] - the value attribute of the button
  • image (string) [Default Value:""] - image of the button. If unset uses a standard image.
  • rolloverImage (string) [Default Value:""] - rollover image of the button.
  • Class (string) [Default Value:""] CSS class to be applied to the button
  • style (string) [Default Value:""] The CSS style attribute to be applied to the button
Returns: (string) of the image button's full html
SpellLink([inPlace] [,text] [,Class] [,style] ) Returns an HTML string for a hyperlink that will open a spell-checker. Arguments:
  • inPlace (boolean) [Default Value:false]. Spell-check will take place in the context of the text area (true) - or in a popup window (false)
  • text (string) [Default Value:"Spell Check"] - the value attribute of the link
  • Class (string) [Default Value:""] CSS class to be applied to the link
  • style (string) [Default Value:""] The CSS style attribute to be applied to the link
Returns: (string) of the link's full html
Events
onDialogOpen() No Arguments Spellchecker dialog is opened.
onDialogComplete() No Arguments Spellchecker dialog completes spellchecking all words.
onDialogCancel() No Arguments Spellchecker dialog is cancelled before spellchecking all words.
onDialogClose() No Arguments Spellchecker dialog closes for any reason.
onChangeLanguage(Language) Arguments: Language (string) User changes the selected dictionary language in either a dialog window or context menu.
onIgnore(Word) Arguments: Word (string) A word is ignored by the user.
onIgnoreAll(Word) Arguments: Word (string) The users tells the spellchecker to "Ignore All"
onChangeWord(From, To) Arguments: From(string), To (string) The user corrects a word's spelling.
onChangeAll(From, To) Arguments: From(string), To (string) The user corrects a words spelling and applies that change globally across all current fields.
onLearnWord(Word) Arguments: Word (string) A words is added to the dictionary.
onLearnAutoCorrect(From, To) Arguments: From(string), To (string) A words is added to the user's own personal auto-correct.
onUpdateFields(arrayOfFieldIds) Arguments: arrayOfFieldIds(Array) An array of strings of the fields which have been updated. A form field is updated due to spellchecking. The fields affected are listed in the arrayofFieldIds array.


The AJAX API

The Ajax API allows your to make Asynchronous server requests for spellcheciing from the client page without refreshing the browser.


Ajax Methods
AjaxSpellCheck(word, makeSuggestions) Arguments: (string) word, (bool) makeSuggestions Returns: null - results are sent to the onSpellCheck event Makes an AJAX request to spell-check the word. Spelling suggestions are only returned to onSpellCheck if makeSuggestions is true.
AjaxSpellCheckArray(arrayOfWords, makeSuggestions) Arguments: (array) arrayOfWords, (bool) makeSuggestions Returns: null - results are sent to the onSpellCheck event ajaxSpellCheckArray functions much as ajaxSpellCheck excapt an array of words is spellchecked. Spelling suggestions are only returned to onSpellCheck if makeSuggestions is true.
AjaxDidYouMean(inputString) Arguments: (string) inputString Returns null - results are sent to the onDidYouMean event Requests the most likely "Did You Mean..." search query string for inputString.
AJAX Events & Callbacks
onSpellCheck (word, spelling, reason, suggestions) Arguments:
  • (string) word. The word which was spell checked.
  • (bool) Spelling - a boolean spellchecking result.
  • (char) reason is the reason for spelling failure:
    • "E" - Enforced Correction
    • "B" - Word is on your banned words list
    • "C" - A CaSe Mistake
    • "X" - (infrequent) Unlicensed software
    • "S" - Spelling mistake. Not found in any dictionary and none of the above cases apply.
    • "" - Spelling was correct
Callback function for the ajaxSpellCheck method.
  • This even also calls back for the AjaxSpellCheckArray function, in which case all of the event arguments will be (arrays) of the above types.
onDidYouMean (suggestion, original) Arguments:
  • (string) suggestion:
    • If spelling of the original is not valid - a suggestion string will be returned.
    • If spelling is valid - the suggestion will be an empty string.
  • (string) original - the original AjaxDidYouMean inputString
Callback function for the AjaxDidYouMean function.

Installation outside of ASP.Net Applications

The JavaScript API allows developers the choice to use all of ASPNetSpell's functionality using JavaScript as the integration language... anywhere on an IIS server that supports ASP.net.

  1. Ensure that /ASPNetSpellInclude/ is installed in the website root (and test this installation using the examples in /ASPNetSpellInclude/debug-test-scripts/).
  2. Use JavaScript to implement ASPNetSpell.

e.g.

SourceCode:
<script src="/ASPNetSpellInclude/include.js' type='text/javascript'></script>
<script type='text/javascript'>
var mySpell = new LiveSpellInstance();
mySpell.Fields = "ALL"
mySpell.ServerModel="aspx"
mySpell.DrawSpellImageButton()
mySpell.ActivateAsYouType()
</script>