Skip to content

[CssSelector] Expand CssSelector documentation #1028

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

[CssSelector] Expand CssSelector documentation #1028

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ea73a53
[CssSelector] Expand CssSelector documentation
lonesomeday Jan 25, 2012
a1b54cd
remove double dot and reword
lonesomeday Jan 25, 2012
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
[CssSelector] Expand CssSelector documentation
  • Loading branch information
@lonesomeday
lonesomeday committed Jan 25, 2012
commit ea73a53ead2b7007308d82d6a6ea928acafeb5be
66 changes: 64 additions & 2 deletions components/css_selector.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ The CssSelector Component
Installation
------------

You can install the component in many different ways:
You can install the component in several different ways:

* Use the official Git repository (https://github.com/symfony/CssSelector);
* Install it via PEAR ( `pear.symfony.com/CssSelector`);
Expand All @@ -18,9 +18,71 @@ You can install the component in many different ways:
Usage
-----

The component only goal is to convert CSS selectors to their XPath
Why use CSS selectors?
~~~~~~~~~~~~~~~~~~~~~~

When you're parsing an HTML or an XML document, by far the most powerful
method is XPath.

XPath expressions are incredibly flexible, so there is almost always an
XPath expression that will find the element you need, but they quickly
become very complicated, and the learning curve is steep. Even common
operations (such as finding an element with a particular class) can require
long and unwieldy expressions.

Many developers -- particularly web developers -- are more comfortable
using CSS selectors to find elements. As well as working in stylesheets,
CSS selectors are used in Javascript with the ``querySelectorAll`` function
and in popular Javascript libraries such as jQuery, Prototype and MooTools.

CSS selectors are less powerful than XPath, but far easier to write, read
and understand. Since they are less powerful, almost all CSS selectors can
be converted to an XPath equivalent. This XPath expression can then be used
with other functions and classes that use XPath to find elements in a
document.

The ``CssSelector`` component
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The component's only goal is to convert CSS selectors to their XPath
equivalents::

use Symfony\Component\CssSelector\CssSelector;

print CssSelector::toXPath('div.item > h4 > a');

This gives output of ``descendant-or-self::div[contains(concat(' ',
normalize-space(@class), ' '), ' item ')]/h4/a``. You can use this
expression with :phpclass:`DOMXPath` or :phpclass:`SimpleXML` to find
elements in a document..
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

duplicated dot


.. tip::

The :method:`Symfony\\Component\\DomCrawler::filter`` method uses the
``CssSelector`` component to find elements based on a
CSS selector string.

Limitations of the CssSelector component
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Not all CSS selectors can be converted to XPath equivalents.

There are several CSS selectors that only make sense in the context of a
web-browser.

* link-state selectors: ``:link``, ``:visited``, ``:target``
* selectors based on user action: ``:hover``, ``:focus``, ``:active``
* UI-state selectors: ``:enabled``, ``:disabled``, ``:indeterminate``
(however, ``:checked`` and ``:unchecked`` are available)

Pseudo-elements (``:before``, ``:after``, ``:first-line``,
``:first-letter``) are not supported because they select portions of text
rather than elements.

Several pseudo-classes are not yet supported:

* ``:lang(language)``
* ``root``
* ``*:first-of-type``, ``*:last-of-type``, ``*:nth-of-type``,
``*:nth-last-of-type``, ``*:only-of-type``. (These work with an element
name (e.g. ``li:first-of-type``) but not with ``*``.