Grammalecte  Check-in [dd167e6841]

# API for the web

If Grammalecte is installed by the user on his browser (like Firefox or Chrome), you can call
several functions for a better integration of grammar checking for your website. This is mostly usefull
if your use a non-standard textarea.


### Detecting if Grammalecte API is here

Every call to the Grammalecte API will be done via an object called `oGrammalecteAPI`.

    if (typeof(oGrammalecteAPI) === "object") {
        ...
    }


### Disabling the Grammalecte button (the spinning pearl)

By default, Grammalecte inserts a button (a spinning pearl) on each textarea node and editable node (unless the user disabled it).
You can tell Grammalete not to create these buttons on your text areas with the property: `data-grammalecte_button="false"`.


### Open the Grammalecte panel for a node

If you have disabled the spinning buttons, you may launch the Grammalecte panel with your custom button

    oGrammalecteAPI.openPanelForNode("node_id")
    oGrammalecteAPI.openPanelForNode(node)

The node can be a textarea, an editable node or an iframe.
If the node is an iframe, the content won’t be modified by Grammalecte.


### Open the Grammalecte panel for any text

    oGrammalecteAPI.openPanelForText("your text")

This method won’t send back any result or modified text.


### Open Grammalecte panel

    oGrammalecteAPI.openPanel(param)

Depending of what `param` is, this method will call `openPanelForNode()` or `openPanelForText()`.


### Prevent Grammalecte to modify the node content

If you don’t want Grammalecte to modify directly the node content, add the property: `data-grammalecte_result_via_event="true"`.

With this property, Grammalecte will send an event to the node each times the text is modified within the panel.
The text can be retrieved with:

    node.addEventListener("GrammalecteResult", function (event) {
        if (event.detail.sType  &&  event.detail.sType == "text") {
            let sText = event.detail.sText;
            ...
        }
    }


### Parse a node and get errors

    oGrammalecteAPI.parseNode("node_id")
    oGrammalecteAPI.parseNode(node)

The node can be a textarea, an editable node or an iframe. The node must have an identifier.
Results will be sent with a succession of events at the node.

    node.addEventListener("GrammalecteResult", function (event) {
        if (event.detail.sType  &&  event.detail.sType == "errors") {
            let oResult = event.detail.oResult; // null when the text parsing is finished
            ...
        }
    }

For the last event, `oResult` will be `null`.


### Get spelling suggestions

`oGrammalecteAPI.getSpellingSuggestions(word, destination, error_identifier)`

Parameters:

- word (string)

- destination: node_id (string)

- error_identifier: a custom identifier (string)

Suggestions will be sent within an event at the node identified by `destination`.

    node.addEventListener("GrammalecteResult", function (event) {
        if (event.detail.sType  &&  event.detail.sType == "spellsugg") {
            let oResult = event.detail.oResult;
            let oInfo = event.detail.oInfo; // object containing the destination and the error_identifier
            ...
        }
    }


### Version of the Grammalecte Web API

    oGrammalecteAPI.sVersion

    xTabPort.postMessage({sActionDone: sCommand, result: result, dInfo: null, bEnd: false, bError: false});
}

function sendCommandToCurrentTab (sCommand) {
    if (bChrome) {
        browser.tabs.query({ currentWindow: true, active: true }, (lTabs) => {
            for (let xTab of lTabs) {
                //console.log(xTab);
                browser.tabs.sendMessage(xTab.id, {sActionRequest: sCommand});
            }
        });
        return;
    }
    browser.tabs.query({ currentWindow: true, active: true }).then((lTabs) => {
        for (let xTab of lTabs) {
            //console.log(xTab);
            browser.tabs.sendMessage(xTab.id, {sActionRequest: sCommand});
        }
    }, showError);
}

function sendCommandToAllTabs (sCommand) {
    for (let [iTab, xTabPort] of dConnx.entries()) {

// JavaScript

"use strict";


const oGrammalecteAPI = {
    // functions callable from within pages
    // to be sent to the content-cript via an event “GrammalecteCall”

    sVersion: "1.0",

    openPanel: function (arg1) {
        //  Parameter: a text, a node, or the identifier of a node.
        let xNode = null;
        if (typeof(arg1) === 'string') {
            if (document.getElementById(arg1)) {
                xNode = document.getElementById(arg1);
            } else {
                this.openPanelForText(arg1);
            }
        }
        else if (arg1 instanceof HTMLElement) {
            xNode = arg1;
        }
        if (xNode) {
            if (xNode.tagName == "INPUT"  ||  xNode.tagName == "TEXTAREA"  ||  xNode.tagName == "IFRAME"  ||  xNode.isContentEditable) {
                this.openPanelForNode(xNode);
            } else {
                this.openPanelForText(xNode.innerText);
            }
        }
    },

    openPanelForNode: function (vNode) {
        //  Parameter: a HTML node or the identifier of a HTML node
        if (vNode instanceof HTMLElement) {
            let xEvent = new CustomEvent("GrammalecteCall", { detail: {sCommand: "openPanelForNode", xNode: vNode} });
            document.dispatchEvent(xEvent);
        }
        else if (typeof(vNode) === "string" && document.getElementById(vNode)) {
            let xEvent = new CustomEvent("GrammalecteCall", { detail: {sCommand: "openPanelForNode", xNode: document.getElementById(vNode)} });
            document.dispatchEvent(xEvent);
        }
        else {
            console.log("[Grammalecte API] Error: parameter is not a HTML node.");
        }
    },

    openPanelForText: function (sText) {
        //  Parameter: text to analyze
        if (typeof(sText) === "string") {
            let xEvent = new CustomEvent("GrammalecteCall", { detail: {sCommand: "openPanelForText", sText: sText} });
            document.dispatchEvent(xEvent);
        } else {
            console.log("[Grammalecte API] Error: parameter is not a text.");
        }
    },

    parseNode: function (vNode) {
        /*  Parameter: a HTML node (with a identifier) or the identifier of a HTML node.
            The result will be sent as an event “GrammalecteResult” to the node.
        */
        if (vNode instanceof HTMLElement  &&  vNode.id) {
            let xEvent = new CustomEvent("GrammalecteCall", { detail: {sCommand: "parseNode", xNode: vNode} });
            document.dispatchEvent(xEvent);
        }
        else if (typeof(vNode) === "string" && document.getElementById(vNode)) {
            let xEvent = new CustomEvent("GrammalecteCall", { detail: {sCommand: "parseNode", xNode: document.getElementById(vNode)} });
            document.dispatchEvent(xEvent);
        }
        else {
            console.log("[Grammalecte API] Error: parameter is not a HTML node or doesn’t have an identifier.");
        }
    },

    getSpellSuggestions: function (sWord, sDestination, sErrorId) {
        /* parameters:
            - sWord (string)
            - sDestination: HTML identifier (string) -> the result will be sent as an event “GrammalecteResult” to destination node
            - sErrorId: identifier for the error (string)
        */
        if (typeof(sWord) === "string"  &&  typeof(sDestination) === "string"  &&  typeof(sErrorId) === "string") {
            let xEvent = new CustomEvent("GrammalecteCall", { detail: {sCommand: "getSpellSuggestions", sWord: sWord, sDestination: sDestination, sErrorId: sErrorId} });
            document.dispatchEvent(xEvent);
        } else {
            console.log("[Grammalecte API] Error: one or several parameters aren’t string.");
        }
    }
}

                            oGrammalecte.oGCPanel.addParagraphResult(result);
                        } else {
                            oGrammalecte.oGCPanel.stopWaitIcon();
                            oGrammalecte.oGCPanel.endTimer();
                        }
                    }
                    else if (dInfo.sDestination  &&  document.getElementById(dInfo.sDestination)) {
                        const xEvent = new CustomEvent("GrammalecteResult", { detail: JSON.stringify({ sType: "errors", oResult: result, oInfo: dInfo }) });
                        document.getElementById(dInfo.sDestination).dispatchEvent(xEvent);
                    }
                    break;
                case "parseAndSpellcheck1":
                    if (dInfo.sDestination == "__GrammalectePanel__") {
                        oGrammalecte.oGCPanel.refreshParagraph(dInfo.sParagraphId, result);
                    }

                    }
                    break;
                case "getSpellSuggestions":
                    if (dInfo.sDestination == "__GrammalectePanel__") {
                        oGrammalecte.oGCPanel.oTooltip.setSpellSuggestionsFor(result.sWord, result.aSugg, result.iSuggBlock, dInfo.sErrorId);
                    }
                    else if (dInfo.sDestination  &&  document.getElementById(dInfo.sDestination)) {
                        const xEvent = new CustomEvent("GrammalecteResult", { detail: JSON.stringify({ sType: "spellsugg", oResult: result, oInfo: dInfo }) });
                        document.getElementById(dInfo.sDestination).dispatchEvent(xEvent);
                    }
                    break;
                case "getVerb":
                    if (dInfo.bStart) {
                        oGrammalecte.oGCPanel.conjugateWith(result.oVerb, result.oConjTable);
                    } else {

                    else {
                        oGrammalecteBackgroundPort.parseAndSpellcheck(oCommand.xNode.innerText, oCommand.xNode.id);
                    }
                }
                break;
            case "getSpellSuggestions":
                if (oCommand.sWord) {
                    oGrammalecteBackgroundPort.getSpellSuggestions(oCommand.sWord, oCommand.sDestination, oCommand.sErrorId);
                }
                break;
            default:
                console.log("[Grammalecte] Event: Unknown command", oCommand.sCommand);
        }
    }
    catch (e) {

            this.xNode.removeChild(this.xNode.firstChild);
        }
    }

    write () {
        if (this.xNode !== null) {
            if (this.bResultInEvent) {
                const xEvent = new CustomEvent("GrammalecteResult", { detail: JSON.stringify({ sType: "text", sText: this.getText() }) });
                this.xNode.dispatchEvent(xEvent);
                //console.log("Text sent via an event :", xEvent.detail);
            }
            else if (this.bTextArea) {
                this.xNode.value = this.getText();
            }
            else if (this.bIframe) {