@@ -9,7 +9,7 @@ The CssSelector Component
99Installation
1010------------
1111
12- You can install the component in many different ways:
12+ You can install the component in several different ways:
1313
1414* Use the official Git repository (https://github.com/symfony/CssSelector);
1515* Install it via PEAR ( `pear.symfony.com/CssSelector `);
@@ -18,9 +18,71 @@ You can install the component in many different ways:
1818Usage
1919-----
2020
21- The component only goal is to convert CSS selectors to their XPath
21+ Why use CSS selectors?
22+ ~~~~~~~~~~~~~~~~~~~~~~
23+
24+ When you're parsing an HTML or an XML document, by far the most powerful
25+ method is XPath.
26+
27+ XPath expressions are incredibly flexible, so there is almost always an
28+ XPath expression that will find the element you need, but they quickly
29+ become very complicated, and the learning curve is steep. Even common
30+ operations (such as finding an element with a particular class) can require
31+ long and unwieldy expressions.
32+
33+ Many developers -- particularly web developers -- are more comfortable
34+ using CSS selectors to find elements. As well as working in stylesheets,
35+ CSS selectors are used in Javascript with the ``querySelectorAll `` function
36+ and in popular Javascript libraries such as jQuery, Prototype and MooTools.
37+
38+ CSS selectors are less powerful than XPath, but far easier to write, read
39+ and understand. Since they are less powerful, almost all CSS selectors can
40+ be converted to an XPath equivalent. This XPath expression can then be used
41+ with other functions and classes that use XPath to find elements in a
42+ document.
43+
44+ The ``CssSelector `` component
45+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
46+
47+ The component's only goal is to convert CSS selectors to their XPath
2248equivalents::
2349
2450 use Symfony\Component\CssSelector\CssSelector;
2551
2652 print CssSelector::toXPath('div.item > h4 > a');
53+
54+ This gives output of ``descendant-or-self::div[contains(concat(' ',
55+ normalize-space(@class), ' '), ' item ')]/h4/a ``. You can use this
56+ expression with :phpclass: `DOMXPath ` or :phpclass: `SimpleXML ` to find
57+ elements in a document..
58+
59+ .. tip ::
60+
61+ The :method: `Symfony\\ Component\\ DomCrawler::filter` ` method uses the
62+ ``CssSelector `` component to find elements based on a
63+ CSS selector string.
64+
65+ Limitations of the CssSelector component
66+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
67+
68+ Not all CSS selectors can be converted to XPath equivalents.
69+
70+ There are several CSS selectors that only make sense in the context of a
71+ web-browser.
72+
73+ * link-state selectors: ``:link ``, ``:visited ``, ``:target ``
74+ * selectors based on user action: ``:hover ``, ``:focus ``, ``:active ``
75+ * UI-state selectors: ``:enabled ``, ``:disabled ``, ``:indeterminate ``
76+ (however, ``:checked `` and ``:unchecked `` are available)
77+
78+ Pseudo-elements (``:before ``, ``:after ``, ``:first-line ``,
79+ ``:first-letter ``) are not supported because they select portions of text
80+ rather than elements.
81+
82+ Several pseudo-classes are not yet supported:
83+
84+ * ``:lang(language) ``
85+ * ``root ``
86+ * ``*:first-of-type ``, ``*:last-of-type ``, ``*:nth-of-type ``,
87+ ``*:nth-last-of-type ``, ``*:only-of-type ``. (These work with an element
88+ name (e.g. ``li:first-of-type ``) but not with ``* ``.
0 commit comments