Mojo::DOM::CSS

Section: User Contributed Perl Documentation (3)
Updated: 2018-11-22
Page Index

NAME

Mojo::DOM::CSS - CSS selector engine

SYNOPSIS

  use Mojo::DOM::CSS;

  # Select elements from DOM tree
  my $css = Mojo::DOM::CSS->new(tree => $tree);
  my $elements = $css->select('h1, h2, h3');

DESCRIPTION

Mojo::DOM::CSS is the CSS selector engine used by Mojo::DOM, based on the HTML Living Standard <https://html.spec.whatwg.org> and Selectors Level 3 <http://www.w3.org/TR/css3-selectors/>.

SELECTORS

All CSS selectors that make sense for a standalone parser are supported.

*

Any element.

  my $all = $css->select('*');

E

An element of type "E".

  my $title = $css->select('title');

E[foo]

An "E" element with a "foo" attribute.

  my $links = $css->select('a[href]');

E[foo=bar]

An "E" element whose "foo" attribute value is exactly equal to "bar".

  my $case_sensitive = $css->select('input[type="hidden"]');
  my $case_sensitive = $css->select('input[type=hidden]');

E[foo=bar i]

An "E" element whose "foo" attribute value is exactly equal to any (ASCII-range) case-permutation of "bar". Note that this selector is EXPERIMENTAL and might change without warning!

  my $case_insensitive = $css->select('input[type="hidden" i]');
  my $case_insensitive = $css->select('input[type=hidden i]');
  my $case_insensitive = $css->select('input[class~="foo" i]');

This selector is part of Selectors Level 4 <http://dev.w3.org/csswg/selectors-4>, which is still a work in progress.

E[foo~=bar]

An "E" element whose "foo" attribute value is a list of whitespace-separated values, one of which is exactly equal to "bar".

  my $foo = $css->select('input[class~="foo"]');
  my $foo = $css->select('input[class~=foo]');

E[foo^=bar]

An "E" element whose "foo" attribute value begins exactly with the string "bar".

  my $begins_with = $css->select('input[name^="f"]');
  my $begins_with = $css->select('input[name^=f]');

E[foo$=bar]

An "E" element whose "foo" attribute value ends exactly with the string "bar".

  my $ends_with = $css->select('input[name$="o"]');
  my $ends_with = $css->select('input[name$=o]');

E[foo*=bar]

An "E" element whose "foo" attribute value contains the substring "bar".

  my $contains = $css->select('input[name*="fo"]');
  my $contains = $css->select('input[name*=fo]');

E[foo|=en]

An "E" element whose "foo" attribute has a hyphen-separated list of values beginning (from the left) with "en".

  my $english = $css->select('link[hreflang|=en]');

E:root

An "E" element, root of the document.

  my $root = $css->select(':root');

E:nth-child(n)

An "E" element, the "n-th" child of its parent.

  my $third = $css->select('div:nth-child(3)');
  my $odd   = $css->select('div:nth-child(odd)');
  my $even  = $css->select('div:nth-child(even)');
  my $top3  = $css->select('div:nth-child(-n+3)');

E:nth-last-child(n)

An "E" element, the "n-th" child of its parent, counting from the last one.

  my $third    = $css->select('div:nth-last-child(3)');
  my $odd      = $css->select('div:nth-last-child(odd)');
  my $even     = $css->select('div:nth-last-child(even)');
  my $bottom3  = $css->select('div:nth-last-child(-n+3)');

E:nth-of-type(n)

An "E" element, the "n-th" sibling of its type.

  my $third = $css->select('div:nth-of-type(3)');
  my $odd   = $css->select('div:nth-of-type(odd)');
  my $even  = $css->select('div:nth-of-type(even)');
  my $top3  = $css->select('div:nth-of-type(-n+3)');

E:nth-last-of-type(n)

An "E" element, the "n-th" sibling of its type, counting from the last one.

  my $third    = $css->select('div:nth-last-of-type(3)');
  my $odd      = $css->select('div:nth-last-of-type(odd)');
  my $even     = $css->select('div:nth-last-of-type(even)');
  my $bottom3  = $css->select('div:nth-last-of-type(-n+3)');

E:first-child

An "E" element, first child of its parent.

  my $first = $css->select('div p:first-child');

E:last-child

An "E" element, last child of its parent.

  my $last = $css->select('div p:last-child');

E:first-of-type

An "E" element, first sibling of its type.

  my $first = $css->select('div p:first-of-type');

E:last-of-type

An "E" element, last sibling of its type.

  my $last = $css->select('div p:last-of-type');

E:only-child

An "E" element, only child of its parent.

  my $lonely = $css->select('div p:only-child');

E:only-of-type

An "E" element, only sibling of its type.

  my $lonely = $css->select('div p:only-of-type');

E:empty

An "E" element that has no children (including text nodes).

  my $empty = $css->select(':empty');

E:link

An "E" element being the source anchor of a hyperlink of which the target is not yet visited (":link") or already visited (":visited"). Note that Mojo::DOM::CSS is not stateful, therefore ":link" and ":visited" yield exactly the same results.

  my $links = $css->select(':link');
  my $links = $css->select(':visited');

E:visited

Alias for ``E:link''.

E:checked

A user interface element "E" which is checked (for instance a radio-button or checkbox).

  my $input = $css->select(':checked');

E.warning

An "E" element whose class is ``warning''.

  my $warning = $css->select('div.warning');

E#myid

An "E" element with "ID" equal to ``myid''.

  my $foo = $css->select('div#foo');

E:not(s1, s2)

An "E" element that does not match either compound selector "s1" or compound selector "s2". Note that support for compound selectors is EXPERIMENTAL and might change without warning!

  my $others = $css->select('div p:not(:first-child, :last-child)');

Support for compound selectors was added as part of Selectors Level 4 <http://dev.w3.org/csswg/selectors-4>, which is still a work in progress.

E:matches(s1, s2)

An "E" element that matches compound selector "s1" and/or compound selector "s2". Note that this selector is EXPERIMENTAL and might change without warning!

  my $headers = $css->select(':matches(section, article, aside, nav) h1');

This selector is part of Selectors Level 4 <http://dev.w3.org/csswg/selectors-4>, which is still a work in progress.

A|E

An "E" element that belongs to the namespace alias "A" from CSS Namespaces Module Level 3 <https://www.w3.org/TR/css-namespaces-3/>. Key/value pairs passed to selector methods are used to declare namespace aliases.

  my $elem = $css->select('lq|elem', lq => 'http://example.com/q-markup');

Using an empty alias searches for an element that belongs to no namespace.

  my $div = $c->select('|div');

E F

An "F" element descendant of an "E" element.

  my $headlines = $css->select('div h1');

E > F

An "F" element child of an "E" element.

  my $headlines = $css->select('html > body > div > h1');

E + F

An "F" element immediately preceded by an "E" element.

  my $second = $css->select('h1 + h2');

E ~ F

An "F" element preceded by an "E" element.

  my $second = $css->select('h1 ~ h2');

E, F, G

Elements of type "E", "F" and "G".

  my $headlines = $css->select('h1, h2, h3');

E[foo=bar][bar=baz]

An "E" element whose attributes match all following attribute selectors.

  my $links = $css->select('a[foo^=b][foo$=ar]');

ATTRIBUTES

Mojo::DOM::CSS implements the following attributes.

tree

  my $tree = $css->tree;
  $css     = $css->tree(['root']);

Document Object Model. Note that this structure should only be used very carefully since it is very dynamic.

METHODS

Mojo::DOM::CSS inherits all methods from Mojo::Base and implements the following new ones.

matches

  my $bool = $css->matches('head > title');
  my $bool = $css->matches('svg|line', svg => 'http://www.w3.org/2000/svg');

Check if first node in ``tree'' matches the CSS selector. Trailing key/value pairs can be used to declare xml namespace aliases.

select

  my $results = $css->select('head > title');
  my $results = $css->select('svg|line', svg => 'http://www.w3.org/2000/svg');

Run CSS selector against ``tree''. Trailing key/value pairs can be used to declare xml namespace aliases.

select_one

  my $result = $css->select_one('head > title');
  my $result =
    $css->select_one('svg|line', svg => 'http://www.w3.org/2000/svg');

Run CSS selector against ``tree'' and stop as soon as the first node matched. Trailing key/value pairs can be used to declare xml namespace aliases.