CSS::DOM - Document Object Model for Cascading Style Sheets
Version 0.06
This is an alpha version. The API is still subject to change. Many features have not been implemented yet (but patches would be welcome :-).
The interface for feeding CSS code to CSS::DOM changed incompatibly in version 0.03.
use CSS::DOM;
my $sheet = CSS::DOM::parse( $css_source );
use CSS::DOM::Style;
my $style = CSS::DOM::Style::parse(
'background: red; font-size: large'
);
my $other_sheet = new CSS::DOM; # empty
$other_sheet->insertRule(
'a{ text-decoration: none }',
$other_sheet->cssRules->length,
);
# etc.
# access DOM properties
$other_sheet->cssRules->[0]->selectorText('p'); # change it
$style->fontSize; # returns 'large'
$style->fontSize('small'); # change it
This module provides the CSS-specific interfaces described in the W3C DOM recommendation.
The CSS::DOM class itself implements the StyleSheet and CSSStyleSheet DOM interfaces.
This method parses the $string and returns a style sheet object. If you just have a CSS style declaration, e.g., from an HTML style attribute, see "parse" in CSS::DOM::Style.
Creates a new, empty style sheet object. Use this only if you plan to build the style sheet piece by piece, instead of parsing a block of CSS code.
You can pass named arguments to both of those. parse accepts all of them; new understands only the first:
This has to be a code ref that returns the contents of the style sheet at the URL passed as the sole argument. E.g.,
# Disclaimer: This does not work with relative URLs.
use LWP::Simple;
use CSS::DOM;
$css = '@import "file.css"; /* other stuff ... ';
$ss = CSS::DOM::parse $css, url_fetcher => sub { get shift };
$ss->cssRules->[0]->styleSheet; # returns a style sheet object
# corresponding to file.css
The subroutine can choose to return undef or an empty list, in which case the @import rule's styleSheet method will return null (empty list or undef), as it would if no url_fetcher were specified.
It can also return named items after the CSS code, like this:
return $css_code, decode => 1, encoding_hint => 'iso-8859-1';
These correspond to the next two items:
If this is specified and set to a true value, then CSS::DOM will treat the CSS code as a string of bytes, and try to decode it based on @charset rules and byte order marks.
By default it assumes that it is already in Unicode (i.e., decoded).
Use this to provide a hint as to what the encoding might be.
If this is specified, and decode is not, then decode => 1 is assumed.
See the options above. This section explains how and when you should use those options.
According to the CSS spec, any encoding specified in the 'charset' field on an HTTP Content-Type header, or the equivalent in other protocols, takes precedence. In such a case, since CSS::DOM doesn't deal with HTTP, you have to decode it yourself.
Otherwise, you should use decode => 1 to instruct CSS::DOM to use byte order marks or @charset rules.
If neither of those is present, then encoding data in the referencing document (e.g., <link charset="..."> or an HTML document's own encoding), if available/applicable, should be used. In this case, you should use the encoding_hint option, so that CSS::DOM has something to fall back to.
If you use decode => 1 with no encoding hint, and no BOM or @charset is to be found, UTF-8 is assumed.
The two constructors above, and also "CSS::DOM::Style::parse|CSS::DOM::Style/parse, set $@ to the empty string upon success. If they encounter a syntax error, they set $@ to the error and return an object that represents whatever was parsed up to that point."
Other methods that parse CSS code might die on encountering syntax errors, and should usually be wrapped in an eval.
The parser follows the 'future-compatible' syntax described in the CSS 2.1 specification, and also the spec's rules for handling parsing errors. Anything not handled by those two is a syntax error.
In other words, a syntax error is one of the following:
a { text-decoration: none )
*[name=~'foo'} {}
#thing { clip: rect( ]
a { text-decoration : none <!-- /* Oops! */ }
<!-- /*ok*/ @media --> /* bad! */ print { }
@ keyword or semicolon where it doesn't belong; e.g.,
@media @print { .... }
@import "file.css" @print;
td, @page { ... }
#tabbar td; #tab1 { }
Returns the string 'text/css'.
Allows one to specify whether the style sheet is used. (This attribute is not actually used yet by CSS::DOM.) You can set it by passing an argument.
Returns the node that 'owns' this style sheet.
If the style sheet belongs to an '@import' rule, this returns the style sheet containing that rule. Otherwise it returns an empty list.
Returns the style sheet's URI, if applicable.
Returns the value of the owner node's title attribute.
Returns the MediaList associated with the style sheet (or a plain list in list context). This defaults to an empty list. You can pass a comma-delimited string to the MediaList's mediaText method to initialise it.
(The medium information is not actually used [yet] by CSS::DOM, but you can put it there.)
If this style sheet was created by an @import rule, this returns the rule; otherwise it returns an empty list (or undef in scalar context).
In scalar context, this returns a CSS::DOM::RuleList object (simply a blessed array reference) of CSS::DOM::Rule objects. In list context it returns a list.
Parses the rule contained in the $css_code, inserting it the style sheet's list of rules at the given $index.
Deletes the rule at the given $index.
You can call this either as an object or class method.
This is actually supposed to be a method of the 'DOMImplementation' object. (See, for instance, HTML::DOM::Interface's method of the same name, which delegates to this one.) This returns a boolean indicating whether a particular DOM module is implemented. Right now it returns true only for the 'CSS2' and 'StyleSheets' features (version '2.0').
This allows you to set the value of ownerNode. Passing an argument to ownerNode does nothing, because it is supposed to be read-only. But you have to be able to set it somehow, so that's why this method is here.
The style sheet will hold a weak reference to the object passed to this method.
Like set_ownerNode, but for href.
See "CONSTRUCTORS", above.
Warning: This is still highly experimental and crawling with bugs.
This computes the style for a given HTML element. It does not yet calculate actual measurements (e.g., converting percentages to pixels), but simply applies the cascading rules and selectors. Shorthand properties are not yet supported, which renders this function quite useless. Pseudo-classes are not supported either (but pseudo-elements are).
The CSS 2.1 specification does not specify the handling of user-agent important rules. Since user agent sheets passed to compute_style are themselves CSS::DOM objects, they can support them, of course. So compute_style ignores the priority of such declarations when comparing them with style sheets in another category, but honours them in relation to other user-agent declarations.
The %options are as follows. They are all optional except for element.
The user agent style sheet
The user style sheet
Array ref of style sheets that the HTML document defines or links to.
The element
The pseudo-element (e.g., 'first-line'). This can be specified with no colons (the way Opera requires it) or with one or two colons (the way Firefox requires it).
(To be implemented)
Here are the inheritance hierarchy of CSS::DOM's various classes and the DOM interfaces those classes implement. For brevity's sake, a simple '::' at the beginning of a class name in the left column is used for 'CSS::DOM::'. Items in brackets do not exist yet. (See also CSS::DOM::Interface for a machine-readable list of standard methods.)
Class Inheritance Hierarchy Interfaces
--------------------------- ----------
CSS
CSS::DOM StyleSheet, CSSStyleSheet
::Array
::MediaList MediaList
::StyleSheetList StyleSheetList
::RuleList CSSRuleList
::Rule CSSRule, CSSUnknownRule
::Rule::Style CSSStyleRule
::Rule::Media CSSMediaRule
::Rule::FontFace CSSFontFaceRule
::Rule::Page CSSPageRule
::Rule::Import CSSImportRule
::Rule::Charset CSSCharsetRule
::Style CSSStyleDeclaration, CSS2Properties
::Value CSSValue
::Value::Primitive CSSPrimitiveValue
[::Value::List CSSValueList]
[::RGBColor RGBColor]
[::Rect Rect]
[::Counter Counter]
CSS::DOM does not implement the following interfaces (see HTML::DOM for these):
LinkStyle DocumentStyle ViewCSS DocumentCSS DOMImplementationCSS ElementCSSInlineStyle
item and length methods.perl 5.8.2 or higher
Exporter 5.57 or later
Encode 2.10 or higher
CSS 'shorthand' properties (such as 'font') are not supported yet. Right now they are treated as their own properties, unrelated to those they are short for.
To report bugs, please e-mail the author.
Copyright (C) 2007-9 Father Chrysostomos <sprout [at] cpan [dot] org>
This program is free software; you may redistribute it and/or modify it under the same terms as perl.
All the classes listed above under "CLASSES AND DOM INTERFACES".
CSS::SAC, CSS.pm and HTML::DOM
The DOM Level 2 Style specification at http://www.w3.org/TR/DOM-Level-2-Style
The CSS 2.1 specification at http://www.w3.org/TR/CSS21/
