ADDED doc/API_web.md Index: doc/API_web.md ================================================================== --- /dev/null +++ doc/API_web.md @@ -0,0 +1,106 @@ +# 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 Index: gc_lang/fr/webext/background.js ================================================================== --- gc_lang/fr/webext/background.js +++ gc_lang/fr/webext/background.js @@ -449,19 +449,19 @@ function sendCommandToCurrentTab (sCommand) { if (bChrome) { browser.tabs.query({ currentWindow: true, active: true }, (lTabs) => { for (let xTab of lTabs) { - console.log(xTab); + //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); + //console.log(xTab); browser.tabs.sendMessage(xTab.id, {sActionRequest: sCommand}); } }, showError); } Index: gc_lang/fr/webext/content_scripts/api.js ================================================================== --- gc_lang/fr/webext/content_scripts/api.js +++ gc_lang/fr/webext/content_scripts/api.js @@ -3,15 +3,16 @@ "use strict"; const oGrammalecteAPI = { // functions callable from within pages - // to be sent to the content-cript via an event GrammalecteCall + // 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 { @@ -28,41 +29,61 @@ this.openPanelForText(xNode.innerText); } } }, - openPanelForNode: function (xNode) { - if (xNode instanceof HTMLElement) { - let xEvent = new CustomEvent("GrammalecteCall", { detail: {sCommand: "openPanelForNode", xNode: xNode} }); + 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 { + } + 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 (xNode) { - if (xNode instanceof HTMLElement) { - let xEvent = new CustomEvent("GrammalecteCall", { detail: {sCommand: "parseNode", xNode: xNode} }); + 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."); + } + else { + console.log("[Grammalecte API] Error: parameter is not a HTML node or doesn’t have an identifier."); } }, getSpellSuggestions: function (sWord, sDestination, sErrorId) { - if (typeof(sWord) === "string") { + /* 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: parameter is not a text."); + console.log("[Grammalecte API] Error: one or several parameters aren’t string."); } } } Index: gc_lang/fr/webext/content_scripts/init.js ================================================================== --- gc_lang/fr/webext/content_scripts/init.js +++ gc_lang/fr/webext/content_scripts/init.js @@ -389,11 +389,11 @@ oGrammalecte.oGCPanel.stopWaitIcon(); oGrammalecte.oGCPanel.endTimer(); } } else if (dInfo.sDestination && document.getElementById(dInfo.sDestination)) { - const xEvent = new CustomEvent("GrammalecteResult", { detail: JSON.stringify({ result: result, info: dInfo }) }); + 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__") { @@ -414,11 +414,11 @@ 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({ result: result, info: dInfo }) }); + 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) { @@ -536,11 +536,11 @@ } } break; case "getSpellSuggestions": if (oCommand.sWord) { - oGrammalecteBackgroundPort.getSpellSuggestions(sWord, oCommand.sDestination, oCommand.sErrorId); + oGrammalecteBackgroundPort.getSpellSuggestions(oCommand.sWord, oCommand.sDestination, oCommand.sErrorId); } break; default: console.log("[Grammalecte] Event: Unknown command", oCommand.sCommand); } Index: gc_lang/fr/webext/content_scripts/panel_gc.js ================================================================== --- gc_lang/fr/webext/content_scripts/panel_gc.js +++ gc_lang/fr/webext/content_scripts/panel_gc.js @@ -1008,11 +1008,11 @@ } write () { if (this.xNode !== null) { if (this.bResultInEvent) { - const xEvent = new CustomEvent("GrammalecteResult", { detail: JSON.stringify({ text: this.getText() }) }); + 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();