feat: add option to pass a function for rendering error handling (#79)

README.md

@@ -35,13 +35,14 @@ The defaults for `pageConfig` are
     singleDollars: false, // allow single-dollar delimiter for inline TeX
     fragment: false, // return body.innerHTML instead of full document
     cssInline: true,  // determines whether inline css should be added
-    jsdom: {... }, // jsdom-related options (NOT used when passing jsdom object to mjpage())
+    jsdom: {...}, // jsdom-related options
     displayMessages: false, // determines whether Message.Set() calls are logged
     displayErrors: false, // determines whether error messages are shown on the console
     undefinedCharError: false, // determines whether unknown characters are saved in the error array
     extensions: '', // a convenience option to add MathJax extensions
     fontURL: 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/fonts/HTML-CSS', // for webfont urls in the CSS for HTML output
-    MathJax: {} // options MathJax configuration, see https://docs.mathjax.org
+    MathJax: {}, // options MathJax configuration, see https://docs.mathjax.org
+    errorHandler: (id, wrapperNode, sourceFormula, sourceFormat, errors) => {...} // function to handle rendering error
 }
 ```
 and where `mjnodeConfig` represents mathjax-node configuration options, the defaults are.
@@ -125,6 +126,17 @@ All formula conversion events pass `ParsedFormula` instance to the event handler
 If `input` is a HTML string, `mjpage` function callback receives result after the DOM serialization.  
 If `input` is a `jsdom` object, `mjpage` function callback receives `jsdom` object itself.
 
+#### Error handling
+When a rendering error occurs, `config.errorHandler` will be called. These arguments are passed:
+
+* `id`: index of formula on the page.
+* `wrapperNode`: The jsdom HTMLElement object where the rendered math should be put.
+* `sourceFormula`: The input math code.
+* `sourceFormat`: The format of input math code -- e.g. `inline-TeX` or `TeX`.
+* `errors`: A array of strings of MathJax-Node returned errors.
+
+Modify the `wrapperNode` object to show some error message to user. The default error handling function is printing the error with `console.log`.
+
 #### Example
 ```javascript
 mjpage(input, {

lib/main.js

@@ -58,7 +58,10 @@ MjPageJob.prototype.run = function() {
         undefinedCharError: false, // determines whether unknown characters are saved in the error array
         extensions: '', // a convenience option to add MathJax extensions
         fontURL: 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/fonts/HTML-CSS', // for webfont urls in the CSS for HTML output
-        MathJax: {} // options MathJax configuration, see https://docs.mathjax.org
+        MathJax: {}, // options MathJax configuration, see https://docs.mathjax.org
+        errorHandler: (id, wrapperNode, sourceFormula, sourceFormat, errors) => {
+            console.error(`Formula ${sourceFormula} contains the following errors:\n`, errors);
+        }
     };
     const mjstate = {};
     // defaults for mathjax-node's typeset method
@@ -188,7 +191,8 @@ MjPageJob.prototype.run = function() {
         _started = true;
     }
     while (script = scripts[index]) {
-        const conf = typesetConfig;
+        // Deep copy the typeset config to make sure error handler gets the correct source formula and format.
+        const conf = Object.assign({}, typesetConfig);
         const format = conf.format = script.getAttribute('type').slice(5);
         if (format === 'MathML-block') conf.format = 'MathML';
         conf.math = script.text;
@@ -236,7 +240,7 @@ MjPageJob.prototype.run = function() {
             if(!options) console.error("typeset function did not return options object needed for state keeping");
             let parsedFormula = options ? options.state.parsedFormula : result;
             if (result.errors) {
-                console.error(`Formula ${parsedFormula.sourceFormula} contains the following errors:\n`, result.errors);
+                config.errorHandler(index, wrapper, conf.math, conf.format, result.errors);
                 checkFinished();
                 return;
             }

test/error-handling.js

@@ -0,0 +1,22 @@
+const tape = require('tape');
+const mjpage = require('../lib/main.js').mjpage;
+
+tape('Error handling should work', function(t) {
+    t.plan(2);
+
+    const input = `error: $$\\Menci$$, non-error: $$\\sum\\limits_{i=0}^na_i$$`,
+          errorMessage = 'HERE BE ERROR MESSAGE';
+    mjpage(input, {
+        output: 'svg',
+        errorHandler: (id, wrapperNode, sourceFormula, sourceFormat, errors) => {
+            t.ok(
+              sourceFormula === '\\Menci' && errors[0] === 'TeX parse error: Undefined control sequence \\Menci', 
+              'Error handler called with correct error information.'
+            );
+
+            wrapperNode.innerHTML = errorMessage;
+        }
+    }, {}, function(output) {
+        t.ok(output.indexOf(errorMessage) !== -1, 'Error message successfully inserted to wrapper node.');
+    });
+});