cheerio-advanced-selectors
v2.0.1
Published
Add advanced selector support to cheerio
Downloads
7,241
Maintainers
Readme
cheerio-advanced-selectors
Add support for the following selectors to cheerio:
:first
:last
:eq(index)
More selectors can easily be added: Just open an issue and I'll look into it :)
This module is inspired by cheerio-eq with the added support for many different selectors.
Supports cheerio version 0.18.0 and above.
Installation
npm install cheerio-advanced-selectors
Usage
Use the .wrap()
function to make cheerio-advanced-selectors take care
of everything for you:
var cheerio = require('cheerio')
var cheerioAdv = require('cheerio-advanced-selectors')
cheerio = cheerioAdv.wrap(cheerio)
var $ = cheerio.load('<div>foo</div><div>bar</div>')
$('div:first').text() // => 'foo'
Advanced usage
Alternatively use the .find()
function to only use
cheerio-advanced-selectors for a specific selector:
var cheerio = require('cheerio')
var cheerioAdv = require('cheerio-advanced-selectors')
var $ = cheerio.load('<div><span>foo</span></div><div><span>bar</span></div>')
cheerioAdv.find($, 'div:eq(1)').text() // => 'bar'
If you need to run the same selector on a lot of different HTML
documents, you can speed things up by pre-compiling the selector using
the .compile()
function:
var cheerio = require('cheerio')
var cheerioAdv = require('cheerio-advanced-selectors')
var myH1 = cheerioAdv.compile('div:first span:eq(1) h1')
var html1 = cheerio.load('<div><span><h1>foo1</h1></span><span><h1>bar1</h1></span></div>')
var html2 = cheerio.load('<div><span><h1>foo2</h1></span><span><h1>bar2</h1></span></div>')
myH1(html1).text() // => 'bar1'
myH1(html2).text() // => 'bar2'
What's the problem?
Cheerio sacrifices advanced CSS selector support for speed. This means
for instance that the :eq()
selector isn't supported. The work-around
is normally to use the .eq()
function instead:
// this will not work:
$('div:eq(1)');
// use this instead:
$('div').eq(1);
This is a good alternative if you write the CSS selectors from scrach,
but what if you are working with selectors that already contain :eq()
?
Don't fear, cheerio-advanced-selectors is here :)
Solution
The solution to the problem is to automatically parse the selector
string at run-time. So if you give cheerio-advanced-selectors a selector
like div:eq(1)
it will return the following cheerio cursor:
$('div').eq(1)
.
It also works for complex selectors, so that div:eq(1) h2:first span
will be converted and interpreted as
$('div').eq(1).find('h2').first().find('span')
.
Supported advanced selectors
This module currently only support a minimal subset of the possible advanced selectors:
:first
:last
:eq(index)
But don't fear :) It's easy to add support for other selectors. Just open an issue or make a pull request.
API
.wrap(cheerio)
Wraps the main cheerio module to overload the standard load
function
so it knows how to handle the advanced selectors.
Returns the cheerio
module.
.find(cheerio, selector [, context [, root]])
Run the selector
on the given cheerio object optionally within the
given context
and optionally on the given root
.
The cheerio
object is usually called $
.
.compile(selector)
Compiles the selector
and returns a function which take 3 arguments:
fn(cheerio [, context [, root]])
:
cheerio
- a reference to the cheerio object (usually called$
)context
- the context in which to run the selector (optional)root
- the HTML root on which to run the selector (optional)
License
MIT