`). Any element you don't want to be warned about can be whitelisted.
- **Validate Element Location**: Make sure that elements don't appear as children of parents they're not allowed to descend from. An example of this is a block element like `` appearing as the child of an inline elements like ``.
- **Validate Attributes**: Like validating elements, this rule will let you know if you're using attributes that don't belong on a particular element or perhaps don't belong on any element. If your project uses custom attributes (like `ng-*` in AngularJS) they can be whitelisted.
- **Duplicate IDs**: Warn if non-unique IDs are found on the same page.
- **Unique Elements**: Warn if elements that should be unique (like `` and `<main>`) appear more than once in the document.
### Best Practices
Some markup may be perfectly valid but use practices that are commonly considered to be poor or outdated. The following rules check for these types of things. (Note that everything in this list is subjective and optional.)
- **Inline Event Handlers**: Warn if inline event handlers, like `onclick="return false"` are found in the document. Inline event handlers are hard to manage, hard to debug, and completely non-reusable.
- **Script Placement**: Warn if script elements appear anywhere other than right before the closing `</body>` tag. Because JavaScript is blocking, adding `<script>` elements anywhere other than the end of the document may delay the loading of the page. If a script must appear somewhere other than the end of the document, it can be whitelisted.
- **Unused Classes**: Sometimes you'll remove a CSS rule from your stylesheet but forget to remove the class from the HTML. The "unused-classes" rule compares all the class selectors in the CSS to the classes in the HTML and reports any that aren't being used.
Classes that are in the HTML as JavaScript hooks can be ignored via a whitelist. By default, any class prefixed with `js-`, `language-`, or `supports-` is whitelisted. More information on the rationale behind this rule can be found [here](http://philipwalton.com/articles/css-architecture/).
- **Unnecessary Elements**: Anytime you have a plain `<div>` or `<span>` element in the HTML with no class, ID or any other attribute, it's probably unnecessary or a mark of poor design.
Elements with no semantic meaning should only be used for presentation. If the element has no attributes but is used for styling, it must be done through a rule like `.some-class > div { }` which is just asking for trouble. Again, more information can be found [here](http://philipwalton.com/articles/css-architecture/).
### Convention
The real power of HTML Inspector lies in its ability to enforce your team's chosen conventions. If you've decided that all groups of links should be contained in a `<nav>` element, or all `<section>` elements must contain a heading, you can write those rules, and an error will be thrown when someone breaks them.
Because convention is usually specific to individual teams, there's only one built-in rule in this category, but hopefully it'll get you thinking about rules your team could use.
- **BEM**: The increasingly popular [BEM](http://bem.info/) (block, element, modifier) methodology is a CSS naming convention that is very helpful for large projects. The problem is that using it correctly in the CSS is only half the battle. If it's not used correctly in the HTML it doesn't work either.
This rule throws an error when an element class name is used but that element isn't a descendant of a block by the same name. It also errors when a modifier is used on a block or element without the unmodified class there too.
*(Note: there are a few different BEM naming conventions out there. HTML Inspector support the [three most common](https://github.com/philipwalton/html-inspector/blob/master/src/rules/convention/bem-conventions.js#L3-L29))*
## Writing Your Own Rules
Rules are the bread and butter of HTML Inspector. They are where you check for problems and report errors.
Here's how you add new rules:
```js
HTMLInspector.rules.add(name, [config], func)
```
- **name**: (String) The `name` parameter is a string used to identify the rule. It must be unique.
- **config** *optional* (Object) The `config` parameter stores configuration data that is used by the rule. Anything that users of your rule might want to customize themselves should be set in the `config` object.
- **func**: (Function) The `func` parameter is an initialization function that is invoked as soon as you call `HTMLInspector.inspect()`. The function is passed three arguments `listener`, `reporter`, and `config`. The `listener` object is used to subscribe to events that are triggered as HTML Inspector is traversing the DOM. When problems are found, they can be reported to the `reporter` object. The `config` object is the same `config` that was passed to `HTMLInspector.rules.add`, though its properties may have been customized by other users between then and now.
### Events
The `listener` object can subscribe to events via the `on` method. Like with many other event binding libraries, `on` takes two parameters: the event name, and a callback function:
```js
listener.on(event, callback)
```
- **event**: (String) The name of the event. See below for a complete list of events.
- **callback**: (Function) A function to be invoked when the event occurs. The function will be passed certain arguments depending on the event type. See the event list below for argument details.
Here is a an example of binding a function to the "class" event:
```js
listener.on("class", function(className, domElement) {
if (className == "foo" and element.nodeName.toLowerCase() == "bar") {
// report the error
}
})
```
Below is a complete list of events along with the arguments that are passed to their respective handlers. For events that occur on a DOM element, that element is passed as the final argument. It is also bound to the `this` context.
- **beforeInspect** : domRoot
- **element** : elementName, domElement
- **id**: idName, domElement
- **class**: className, domElement
- **attribute**: attrName, attrValue, domElement
- **afterInspect** : domRoot
### Reporting Errors
When you find something in the HTML that you to want warn about, you simply call the `warn` method on the `reporter` object.
```js
reporter.warn(rule, message, context)
```
- **rule**: (String) The rule name identifier.
- **message**: (String) The warning to report.
- **context**: (mixed) The context in which the rule was broken. This is usually a DOM element or collection of DOM elements, but doesn't have to be. It can be anything that helps the user track down where the error occurred.
Here's an example from the [validate-elements](https://github.com/philipwalton/html-inspector/blob/master/src/rules/validation/validate-elements.js) rule:
```js
reporter.warn(
"validate-elements",
"The <" + name + "> element is not a valid HTML element.",
element
)
```
### An Example Rule
Imagine your team previously used the custom data attributes `data-foo-*` and `data-bar-*`, but now the convention is to use something else. Here's a rule that would warn users when they're using the old convention:
```js
HTMLInspector.rules.add(
"deprecated-data-prefixes",
{
deprecated: ["foo", "bar"]
},
function(listener, reporter, config) {
// register a handler for the `attribute` event
listener.on('attribute', function(name, value, element) {
var prefix = /data-([a-z]+)/.test(name) && RegExp.$1
// return if there's no data prefix
if (!prefix) return
// loop through each of the deprecated names from the
// config array and compare them to the prefix.
// Warn if they're the same
config.deprecated.forEach(function(item) {
if (item === prefix) {
reporter.warn(
"deprecated-data-prefixes",
"The 'data-" + item + "' prefix is deprecated.",
element
)
}
})
}
)
})
```
## Overriding Rule Configurations
Individual rules may or may not do exactly what you need, which is why most rules come with a configurations object that users can customize. A rule's configuration can be changed to meet your needs via the `extend` method of the `HTMLInspector.rules` object.
```js
HTMLInspector.rules.extend(rule, overrides)
```
- **rule**: (String) The rule name identifier.
- **overrides**: (Object | Function) An object (or function that returns an object) to be merged with the rule's config object. If `overrides` is a function, it will be passed the rule's config object as its first argument.
Here are two examples overriding the "deprecated-data-prefixes" rule defined above. The first example passes an object and the second passes a function:
```js
// using an object
HTMLInspector.rules.extend("deprecated-data-prefixes", {
deprecated: ["fizz", "buzz"]
})
// using a function
HTMLInspector.rules.extend("deprecated-data-prefixes", function(config) {
return {
deprecated: config.deprecated.concat(["bazz"])
}
})
```
Here are a few more examples. The following override the defaults of a few of the built-in rules.
```js
// use the `inuit.css` BEM naming convention
HTMLInspector.rules.extend("bem-conventions", {
methodology: "inuit"
})
// add Twitter generated classes to the whitelist
HTMLInspector.rules.extend("unused-classes", {
whitelist: /^js\-|^tweet\-/
})
```
## Browser Support
HTML Inspector has been tested and known to work in the latest versions of all modern browsers including Chrome, Firefox, Safari, Opera, and Internet Explorer. It will not work in older browsers that do not support ES5 methods, the CSS Object Model, or `console.warn()`. Since HTML Inspector is primarily a development tool, it is not intended to work in browsers that aren't typically used for development and don't support modern Web standards.
If you need to test your site in older versions of IE and don't want to see JavaScript errors, simply wrap all your HTML Inspector code inside a conditional comment, so it is ignored by IE9 and below. Here is an example:
```html
<!--[if gt IE 9]><!-->
<script src="path/to/html-inspector.js"></script>
<script>HTMLInspector.inspect()</script>
<!--<![endif]-->
```
## Running the Tests
If Grunt and all the dependencies are installed, you can run the tests with the following command.
```sh
grunt test
```
HTML Inspector has two test suites, one that runs in pure Node and one that uses [Mocha](http://visionmedia.github.io/mocha/) and [PhantomJS](http://phantomjs.org/) because it needs a browser.
If you want to run the browser tests in a real browser (instead of via PhantomJS) simply fire up a local server and load the `tests/html-inspector-test.html` file. Make sure to run `grunt test` beforehand as it builds the tests.
## Contributing
I'm always open to feedback and suggestions for how to make HTML Inspector better. All feedback from bug reports to API design is quite welcome.
If you're submitting a bug report, please search the issues to make sure there isn't one already filed.
If you're submitting a pull request please read [CONTRIBUTING.md](https://github.com/philipwalton/html-inspector/blob/master/CONTRIBUTING.md) before submitting.
## FAQs
The FAQs section has grown rather large, so it has been moved to its own page. You can find the [full FAQs here](https://github.com/philipwalton/html-inspector/blob/master/FAQs.md).
## Third Party Rules
- [Large Viewstate](https://github.com/palewar/html-inspector/blob/master/src/rules/best-practices/large-viewstate.js) - warn if View State takes up more than 50KB (configurable) in ASP.NET generated HTML
- [Voice Input](https://googledrive.com/host/0B8yu2s4Q9YD8VEZNUHJaV3BkSzA/File.htm) - warn when input fields are inaccessible to voice input