From 1c4ab9638ca9015d4d1db9e7e222e0c291c34d8f Mon Sep 17 00:00:00 2001 From: Juga Paazmaya Date: Wed, 28 Nov 2018 10:11:51 +0200 Subject: [PATCH 1/2] Adjust heading levels and update with recent changes --- README.markdown | 95 ++++++++++++++++++++++--------------------------- 1 file changed, 42 insertions(+), 53 deletions(-) diff --git a/README.markdown b/README.markdown index 773ac513..db63dea7 100644 --- a/README.markdown +++ b/README.markdown @@ -1,86 +1,73 @@ -# HTML_CodeSniffer README +# HTML_CodeSniffer ## What is HTML_CodeSniffer? HTML_CodeSniffer is a JavaScript application that checks a HTML document or source code, and detects violations of a defined presentation or accessibility -standard. +standard, such as Section508 or WCAG2.0. -### Standards included +## Standards included -By default, HTML\_CodeSniffer comes with standards that cover the three conformance +By default, HTML_CodeSniffer comes with standards that cover the three conformance levels of the W3C [Web Content Accessibility Guidelines (WCAG) 2.0](http://www.w3.org/TR/WCAG20), and the U.S. [Section 508](http://section508.gov/index.cfm?fuseAction=stdsdoc) legislation. It also provides tools to write your own standards, which can be useful in situations where you wish to enforce consistency across a web site. -### Using HTML_CodeSniffer +## Using HTML_CodeSniffer -HTML\_CodeSniffer can be called in multiple ways: +HTML_CodeSniffer can be called in multiple ways: * Called directly in JavaScript source, HTML_CodeSniffer will provide a list of known and potential violations to the calling script. * It also comes with a pop-up auditor interface, accessible via a bookmarklet, letting you browse through messages emitted from one of the defined standards. Where possible, the auditor also points you to the HTML element causing the problem. * It can also be run on the command line with the assistance of a headless browser app. -* Using npm: -``` -$ npm i -g npm -$ npm i --save html_codesniffer -``` - -### Licence +* Using as a Node.js module, installed with npm: `npm i --save html_codesniffer` -HTML_CodeSniffer is released under a BSD-style licence. For more information, -please see the file "licence.txt". ## Using the source code ### Building the auditor -The HTML\_CodeSniffer auditor can be built using [node.js](https://nodejs.org/) and the Grunt -tasker (http://gruntjs.com/). It has been tested with the latest version of node.js -(at time of writing: version 6.0) and Grunt, but should also work with recent -earlier versions. - -* Install node.js with your package manager of choice. -* You may need to update the Node.js package manager (npm) itself: - npm update -g npm -* Install the Grunt CLI helper if you haven't already done so: - npm install -g grunt-cli -* Get node.js to install the dependencies Grunt needs: - npm install -* Run Grunt to build the auditor: - grunt build - -You should see two new directories: node_modules (containing the node.js -dependencies), and build (containing your auditor). You can then move -(or symlink as appropriate) your build directory to a web-accessible +The HTML_CodeSniffer auditor can be built using [Node.js](https://nodejs.org/) and [Grunt +task runner](http://gruntjs.com/). It has been tested with the recent version of Node.js +(starting from version 6.0) and Grunt. + +* Install Node.js with your package manager of choice, for example `sudo apt-get install nodejs` +* You may need to update the Node.js package manager (npm) itself: `npm install -g npm` +* Install the Grunt CLI helper if you haven't already done so: `npm install -g grunt-cli` +* Get Node.js to install the dependencies Grunt needs: `npm install` +* Run Grunt to build the auditor: `grunt build` + +You should see two new directories: `node_modules` (containing the Node.js +dependencies), and `build` (containing your auditor). You can then move +(or symlink as appropriate) your `build` directory to a web-accessible location. Then grab or copy the JavaScript from the auditor bookmarklet from the [HTML_CodeSniffer site](https://squizlabs.github.io/HTML_CodeSniffer), replace the directory at the start (//squizlabs.github.io/HTML_CodeSniffer/build) with your local URL, and save as a new bookmarklet. -#### Debug build +### Debug build -If you are developing using HTML\_CodeSniffer and require the code not minified for -debugging purposes, follow the above steps, but run grunt build-debug +If you are developing using HTML_CodeSniffer and require the code not minified for +debugging purposes, follow the above steps, but run `grunt build-debug` (instead of just build). This will combine the files as normal, but not minify them. -### Command-Line processing +## Command-Line processing **Note:** These examples assume a built version of HTMLCS exported to `./build/HTMLCS.js` -#### PhantomJS +### PhantomJS You will need [PhantomJS](http://www.phantomjs.org/) installed if you wish to use the contributed command-line script. PhantomJS provides a headless Webkit-based browser to run the scripts in, so it should provide results that are similar to recent (or slightly less than recent) versions of Safari. -See the Contrib/PhantomJS/HTMLCS_Run.js file for more information. +See the `Contrib/PhantomJS/HTMLCS_Run.js` file for more information. -#### Headless Google Chrome via Puppeteer +### Headless Google Chrome via Puppeteer [Puppeteer](https://developers.google.com/web/tools/puppeteer/get-started) offers an easy way to interact with the page via Google Chrome. @@ -113,7 +100,7 @@ const url = 'https://www.squiz.net'; page.on('console', msg => { console.log(msg.text()) }); - + await page.goto(url); await page.addScriptTag({ @@ -128,13 +115,14 @@ const url = 'https://www.squiz.net'; })(); ``` -#### Node & JSDom +### Node.js & JSDom -HTML_CodeSniffer requires a dom to run, however, it is possible to run it entirely -server side without a headless browser using Node on arbitrary fragments of HTML using +HTML_CodeSniffer requires a DOM to run, however, it is possible to run it entirely +server side without a headless browser using Node.js on arbitrary fragments of HTML using an environment wrapper like [JSDom](https://github.com/jsdom/jsdom). -An example node script: +An example Node.js script: + ```javascript var jsdom = require('jsdom'); var { JSDOM } = jsdom; @@ -157,7 +145,7 @@ dom.window.eval(HTMLCS); dom.window.HTMLCS_RUNNER.run('WCAG2AA'); ``` -### Translations +## Translations HTML_CodeSniffer supports _very_ basic string translations. The auditor will use the current language of the document it is being run in (e.g. ``). A language code can be supplied if you need to tell HTML_CodeSniffer which language you want to use. @@ -168,11 +156,11 @@ HTMLCSAuditor.run('WCAG2AA', null, { }); ``` -**Note:** HTML_CodeSniffer only has english (default) and polish language. +**Note:** HTML_CodeSniffer only has English (default), French, and Polish languages. -If other language support is required a custom version can be built by adding more translations in `Translations/.js` and using the grunt build process described above. +If other language support is required a custom version can be built by adding more translations in `Translations/*.js` and using the grunt build process described above. -### Contributing and reporting issues +## Contributing and reporting issues To report any issues with using HTML_CodeSniffer, please use the [HTML_CodeSniffer Issue Tracker](http://github.com/squizlabs/HTML_CodeSniffer/issues). @@ -188,10 +176,9 @@ contribute, you do not need to do both. More information on HTML_CodeSniffer can be found on its GitHub site, [http://squizlabs.github.io/HTML_CodeSniffer/](http://squizlabs.github.io/HTML_CodeSniffer/). This site provides: -- Information on the tests performed (and messages emitted) by HTML_CodeSniffer's standards, organised by conformance level and Success Criterion; -- A source test area that allows you to try out HTML_CodeSniffer with your own HTML source code; and -- A link to the HTML_CodeSniffer bookmarklet, letting you check other pages using the pop-up auditor interface. - +* Information on the tests performed (and messages emitted) by HTML_CodeSniffer's standards, organised by conformance level and Success Criterion; +* A source test area that allows you to try out HTML_CodeSniffer with your own HTML source code; and +* A link to the HTML_CodeSniffer bookmarklet, letting you check other pages using the pop-up auditor interface. ## Translation Contributors @@ -203,3 +190,5 @@ Special thanks to: ## License Licensed under [the BSD 3-Clause "New" or "Revised" License](https://opensource.org/licenses/BSD-3-Clause). + +License text also available in [the `license.txt` file](./license.txt). From 7575ebafbc07a3eb7b954e93bc60a1d1cfd96654 Mon Sep 17 00:00:00 2001 From: Juga Paazmaya Date: Wed, 28 Nov 2018 10:12:18 +0200 Subject: [PATCH 2/2] Define minimum Node.js version --- index.js | 4 ++-- package.json | 4 ++++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/index.js b/index.js index a780da32..66db7e5b 100644 --- a/index.js +++ b/index.js @@ -4,5 +4,5 @@ var scriptPath = __dirname+'/build/HTMLCS.js'; if (fs.existsSync(scriptPath) === true) { module.exports = require(scriptPath); } else { - throw new Error('HTMLCS must be built using `grunt build` before it can be required in Nodejs.'); -} \ No newline at end of file + throw new Error('HTMLCS must be built using `grunt build` before it can be required in Node.js.'); +} diff --git a/package.json b/package.json index cdec06e5..ca9d69c3 100644 --- a/package.json +++ b/package.json @@ -9,8 +9,12 @@ ], "scripts": { "prepack": "grunt build", + "build": "grunt build", "test": "echo \"Error: no test specified\" && exit 1" }, + "engines": { + "node": ">=6" + }, "files": [ "Auditor", "build",