You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

132 lines
5.3 KiB

  1. # [NWSAPI](http://dperini.github.io/nwsapi/)
  2. Fast CSS Selectors API Engine
  3. ![](https://img.shields.io/npm/v/nwsapi.svg?colorB=orange&style=flat) ![](https://img.shields.io/github/tag/dperini/nwsapi.svg?style=flat) ![](https://img.shields.io/npm/dw/nwsapi.svg?style=flat) ![](https://img.shields.io/github/issues/dperini/nwsapi.svg?style=flat)
  4. NWSAPI is the development progress of [NWMATCHER](https://github.com/dperini/nwmatcher) aiming at [Selectors Level 4](https://www.w3.org/TR/selectors-4/) conformance. It has been completely reworked to be easily extended and maintained. It is a right-to-left selector parser and compiler written in pure Javascript with no external dependencies. It was initially thought as a cross browser library to improve event delegation and web page scraping in various frameworks but it has become a popular replacement of the native CSS selection and matching functionality in newer browsers and headless environments.
  5. It uses [regular expressions](https://en.wikipedia.org/wiki/Regular_expression) to parse CSS selector strings and [metaprogramming](https://en.wikipedia.org/wiki/Metaprogramming) to transforms these selector strings into Javascript function resolvers. This process is executed only once for each selector string allowing memoization of the function resolvers and achieving unmatched performances.
  6. ## Installation
  7. To include NWSAPI in a standard web page:
  8. ```html
  9. <script type="text/javascript" src="nwsapi.js"></script>
  10. ```
  11. To include NWSAPI in a standard web page and automatically replace the native QSA:
  12. ```html
  13. <script type="text/javascript" src="nwsapi.js" onload="NW.Dom.install()"></script>
  14. ```
  15. To use NWSAPI with Node.js:
  16. ```
  17. $ npm install nwsapi
  18. ```
  19. NWSAPI currently supports browsers (as a global, `NW.Dom`) and headless environments (as a CommonJS module).
  20. ## Supported Selectors
  21. Here is a list of all the CSS2/CSS3/CSS4 [Supported selectors](https://github.com/dperini/nwsapi/wiki/CSS-supported-selectors).
  22. ## Features and Compliance
  23. You can read more about NWSAPI [features and compliance](https://github.com/dperini/nwsapi/wiki/Features-and-compliance) on the wiki.
  24. ## API
  25. ### DOM Selection
  26. #### `ancestor( selector, context, callback )`
  27. Returns a reference to the nearest ancestor element matching `selector`, starting at `context`. Returns `null` if no element is found. If `callback` is provided, it is invoked for the matched element.
  28. #### `first( selector, context, callback )`
  29. Returns a reference to the first element matching `selector`, starting at `context`. Returns `null` if no element matches. If `callback` is provided, it is invoked for the matched element.
  30. #### `match( selector, element, callback )`
  31. Returns `true` if `element` matches `selector`, starting at `context`; returns `false` otherwise. If `callback` is provided, it is invoked for the matched element.
  32. #### `select( selector, context, callback )`
  33. Returns an array of all the elements matching `selector`, starting at `context`; returns empty `Array` otherwise. If `callback` is provided, it is invoked for each matching element.
  34. ### DOM Helpers
  35. #### `byId( id, from )`
  36. Returns a reference to the first element with ID `id`, optionally filtered to descendants of the element `from`.
  37. #### `byTag( tag, from )`
  38. Returns an array of elements having the specified tag name `tag`, optionally filtered to descendants of the element `from`.
  39. #### `byClass( class, from )`
  40. Returns an array of elements having the specified class name `class`, optionally filtered to descendants of the element `from`.
  41. ### Engine Configuration
  42. #### `configure( options )`
  43. The following is the list of currently available configuration options, their default values and descriptions, they are boolean flags that can be set to `true` or `false`:
  44. * `IDS_DUPES`: true - true to allow using multiple elements having the same id, false to disallow
  45. * `LIVECACHE`: true - true for caching both results and resolvers, false for caching only resolvers
  46. * `MIXEDCASE`: true - true to match tag names case insensitive, false to match using case sensitive
  47. * `LOGERRORS`: true - true to print errors and warnings to the console, false to mute both of them
  48. ### Examples on extending the basic functionalities
  49. #### `configure( { <configuration-flag>: [ true | false ] } )`
  50. Disable logging errors/warnings to console, disallow duplicate ids. Example:
  51. ```js
  52. NW.Dom.configure( { LOGERRORS: false, IDS_DUPES: false } );
  53. ```
  54. NOTE: NW.Dom.configure() without parameters return the current configuration.
  55. #### `registerCombinator( symbol, resolver )`
  56. Registers a new symbol and its matching resolver in the combinators table. Example:
  57. ```js
  58. NW.Dom.registerCombinator( '^', 'e.parentElement' );
  59. ```
  60. #### `registerOperator( symbol, resolver )`
  61. Registers a new symbol and its matching resolver in the attribute operators table. Example:
  62. ```js
  63. NW.Dom.registerOperator( '!=', { p1: '^', p2: '$', p3: 'false' } );
  64. ```
  65. #### `registerSelector( name, rexp, func )`
  66. Registers a new selector, the matching RE and the resolver function, in the selectors table. Example:
  67. ```js
  68. NW.Dom.registerSelector('Controls', /^\:(control)(.*)/i,
  69. (function(global) {
  70. return function(match, source, mode, callback) {
  71. var status = true;
  72. source = 'if(/^(button|input|select|textarea)/i.test(e.nodeName)){' + source + '}';
  73. return { 'source': source, 'status': status };
  74. };
  75. })(this));
  76. ```