gaphu.js The javascript editor (Get A Parser Hooked Up)

Download and unzip the javascript bundle or get the most recent from github.

Force strict mode for the page by using an appropriate DOCTYPE, for example:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

Include the necessary files in your html header:

<script src="jquery-1.4.3.min.js" type="text/javascript"></script>
<script src="parser-0.0.9.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="parser-0.0.9.css">

The editor can be instantiated by attaching it to any standard textarea.

This is the code for the custom textarea example above.

<textarea id="custom" cols="60" rows="5"></textarea>

<script type="text/javascript">
  new ExpressionEditor("custom",
                       {parser: "test-parse.php",
                        autocomplete: "test-autocomplete.php",
                        highlightResults     : false,
                        autocompleteOnChange : true});
</script>

There are several options for tweaking the behaviour of the editor:

parser	default: null	a url or function that parses the expression (see below)
autocomplete	default: null	a url or function that performs autocomplete (see below)
queryParam	default: expression	the name of the query parameter passed in the remote request
format	default: xml	the type of the server responses - either json or xml
highlightResults	default: true	mark the matching part of the autocomplete results in bold
autocompleteOnChange	default: false	perform an autocomplete on every change to the text
errorHandler	default: that.defaultErrorHandler	a handler function f(e) where e is a ParseError

To set up a parser or autocompleter, you either need to provide a javascript function or a remote service that can be called at the specified url.

There are two local test functions that can be used when getting setup:

TestParser A parser that verifies space separated words as being "one" - "ten"
TestAutocomplete An autocompleter that suggests numbers matching any incomplete word

There are two matching remote test services:

test-parse.php
test-autocomplete.php

These simple examples use php implementations of the parse success, error and autocomplete result classes that are also available in the bundle in gaphu.js.php. These classes handle serialisation.

Javascript parser

Set parser to a javascript function.

The function should take a single parameter (the contents of the editor) and return either a ParseSuccess object if successful:

new ParseSuccess(expression, errMessage);

or a ParseError object if the parse failed:

new ParseError(expression, errMessage, position, token);

Remote parser

Set parser to the url of your service.

ExpressionEditor will make AJAX calls to the url you provide in the setup, appending the query

?[queryParam]=[contents of the editor]

Your service should return xml in the format described below.

On success:

<?xml version="1.0" encoding="UTF-8"?>
<success>
    <expression>one two three</expression>
    <message>An option success message - Hurray!</message>
</success>

On error:

<?xml version="1.0" encoding="UTF-8"?>
<error pos="8" eof="true" found="t">
    <expression>one two t</expression>
    <message>Found "t". Expected one of one,two,three,four,...</message>
</error>

Or for json the following for success and error respectively:

{"expression": "one two three",
 "message": "An option success message - Hurray!"
}

{"expression": "one two t",
 "pos": "8",
 "token": "t",
 "message": "Found \"t\". Expected one of one,two,three,four,..."
}

Javascript autocomplete

Set autocomplete to a javascript function.

The function should take a single parameter (the contents of the editor) and return an AutocompleteResult object:

new AutocompleteResult(expression, position, token, matchingTerms);

Remote autocomplete

Set autocomplete to the url of your service
(due to limitations in XMLHttpRequest this must be on the same domain as the page was served from).

ExpressionEditor will make AJAX calls to the url you provide in the setup, appending the query

?[queryParam]=[contents of the editor up to the cursor]

Your service should return xml in the format described below:

<?xml version="1.0" encoding="UTF-8"?>
<results pos="8" found="t">
    <expression>one two t</expression>
    <expected type="Number">
        <token>two</token>
        <token>three</token>
        <token>ten</token>
    </expected>
</results>

or json in the format described below:

{"expression": "one two t",
 "pos": "8",
 "token": "t",
 "expectedByType": {
     "Number" : ["two", "three", "ten"]
 }
}

Debugging support is only basic. There are two consoles available.

A debug console can be added by creating a div with id debug and setting DEBUG_RESULTS and/or DEBUG_KEYS to true.

Server responses can be traced by creating a div with id xml.

gaphu.js

Installation

Setting up a parser

Javascript parser

Remote parser

Setting up an autocompleter

Javascript autocomplete

Remote autocomplete

Debugging