html-script-hook
v1.0.0
Published
For each local HTML script tag, calls a function with the code inside the tag and replaces the code with the return value
Maintainers
apowers313Readme
html-script-hook
About
Calls a callback function with the code for each <script> tag found in a HTML file. Whatever the callback returns becomes the new code in the <script> section. To leave the code exactly the same, simply callback with the same argument that was passed in.
Originally this was created to help Istanbul instrument JavaScript in a HTML file so that it can be recognized for code coverage. But it can also support other tools that would want to have access to or modify the <script> tag. For example: documentation generators, code analysis tools, style analysis, linters, obfuscation, etc.
Install
npm install html-script-hookUsage
Start with a HTML file:
<!-- test.html -->
<!DOCTYPE html>
<html>
<title>Just a test file</title>
<script>
console.log ("This is a test");
</script>
</html>
<body>
This is a test.
</body>Run the parser on test.html:
var fs = require("fs");
var testParser = require("html-script-hook");
var html = fs.readFileSync("test.html", {
encoding: "utf8"
});
// callback receives code from <script> section and replaces it with return value
function gotScript(code) {
// prints: "\nconsole.log (\"this is a test.\\n\");\n"
// which is the line from between the script tags in the HTML
console.log (code);
// replace the current code with a single comment
return "// no more console log";
}
// the `ret` variable will contain the new HTML
var ret = testParser(testhtml, {
// tell the parser to call the gotScript() function for each <script> section
scriptCallback: gotScript
});End up with a modified <script> section:
<!-- test.html -->
<!DOCTYPE html>
<html>
<title>Just a test file</title>
<script>// no more console log</script>
</html>
<body>
This is a test.
</body>Usage With Istanbul
As a bit more of a real world example, here's how to instrument a HTML file for Istanbul code coverage:
var istanbul = require('istanbul');
var scriptHook = require('html-script-hook');
var fs = require("fs");
// create a new Istanbul instrumenter
var instrumenter = new istanbul.Instrumenter();
// read in a HTML file
var html = fs.readFileSync(htmlFilePath, 'utf8');
// parse the HTML file and replace it with a HTML file where the code has been instrumented
// (using the gotScript() callback)
html = scriptHook (html, {scriptCallback: gotScript});
// catch the code in the script section
function gotScript(code, loc) {
// replace the existing code with instrumented code
return instrumenter.instrumentSync(code, htmlFilePath);
}For the complete example, see the example code from web-component-tester-istanbul, which instruments the files on the server as the files are being requested by the browser.
Options
The parser that is returned by require('html-script-hook') takes the following arguments:
parser (html, options)html[required] : the string containing the HTML fileoptions[optional] : an object with the configuration options for the parser. Those options include the following properties:scriptCallback (code, details)[function, default=undefined] : if defined, this function will be called with the code from inside each<script>section. It takes the form ofscriptCallback (code, details)and the return value fromscriptCallbackreplaces the code for the<script>section. AssumingpadLineNois not set, simply return thecodeargument to leave the code unchanged. Thedetailsargument is experimental, and contains an object describing the location of the code, an object describing start location of the<script>tag, an object describing start location of the</script>tag, and aunexpectedEofflag that indicates that thescriptCallbackwas called even though a final</script>tag wasn't found.padLineNo[boolean, default=true] : whether the JavaScript passed to the script callback should start with a number of newlines ("\n") so that it matches the line numbers of the code in the HTML file. Useful for making sure that tools that pick up line numbers use the same line numbers.htmlCallback (html)[function, default=undefined] : if defined, this function will be called with a single argument that is the final HTML with any modified JavaScript. It is the exact same as the return value fromparserand rather silly, since theparseris synchronous.
The parser returns the HTML that was modified by scriptCallback.
Tests
npm test