CSS::DOM(3) User Contributed Perl Documentation CSS::DOM(3)NAMECSS::DOM - Document Object Model for Cascading Style Sheets
VERSION
Version 0.14
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.
SYNOPSIS
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
DESCRIPTION
This set of modules provides the CSS-specific interfaces described in
the W3C DOM recommendation.
The CSS::DOM class itself implements the StyleSheet and CSSStyleSheet
DOM interfaces.
This set of modules has two modes:
1. It can validate property values, ignoring those that are invalid
(just like a real web browser), and support shorthand properties.
This means you can set font to '13px/15px My Font' and have the
font-size, line-height, and font-family properties (among others)
set automatically. Also, "color: green; color: kakariki" will
assign 'green' to the color property, 'kakariki' not being a
recognised color value.
2. It can blithely accept all property assignments as being valid. In
the case of "color: green; color kakariki", 'kakariki' will be
assigned, since it overrides the previous assignment.
These two modes are controlled by the "property_parser" option to the
constructors.
CONSTRUCTORS
CSS::DOM::parse( $string )
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.
new CSS::DOM
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 two, "property_parser" and
"url_fetcher".
property_parser
Set this to a PropertyParser object to specify which properties are
supported and how they are parsed.
If this option is not specified or is set to "undef", all property
values are treated as valid.
See CSS::DOM::PropertyParser for more details.
url_fetcher
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:
decode
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).
encoding_hint
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.
STYLE SHEET ENCODING
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.
SYNTAX ERRORS
The two constructors above, and also "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:
· An unexpected closing bracket, as in these examples
a { text-decoration: none )
*[name=~'foo'} {}
#thing { clip: rect( ]
· An HTML comment delimiter within a rule; e.g.,
a { text-decoration : none <!-- /* Oops! */ }
<!-- /*ok*/ @media --> /* bad! */ print { }
· An extra "@" keyword or semicolon where it doesn't belong; e.g.,
@media @print { .... }
@import "file.css" @print;
td, @page { ... }
#tabbar td; #tab1 { }
OBJECT METHODS
Attributes
type
Returns the string 'text/css'.
disabled
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.
ownerNode
Returns the node that 'owns' this style sheet.
parentStyleSheet
If the style sheet belongs to an '@import' rule, this returns the
style sheet containing that rule. Otherwise it returns an empty
list.
href
Returns the style sheet's URI, if applicable.
title
Returns the value of the owner node's title attribute.
media
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.)
ownerRule
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).
cssRules
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.
Methods
insertRule ( $css_code, $index )
Parses the rule contained in the $css_code, inserting it in the
style sheet's list of rules at the given $index.
deleteRule ( $index )
Deletes the rule at the given $index.
hasFeature ( $feature, $version )
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').
Non-DOM Methods
set_ownerNode
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.
set_href
Like "set_ownerNode", but for "href".
property_parser
url_fetcher
These two both return what was passed to the constructor. The
second one, "url_fetcher" also allows an assignment, but this is
not propagated to sub-rules and is intended mainly for internal
use.
FUNCTIONS
CSS::DOM::parse
See "CONSTRUCTORS", above.
CSS::DOM::compute_style( %options )
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.
Pseudo-classes are not yet supported (but pseudo-elements are).
The precedence rules for normal vs important declarations in the
CSS 2 specification are used. (CSS 2.1 is unclear.) The precedence
is as follows, from lowest to highest:
user agent normal declarations
user normal declarations
author normal "
user agent !important declarations
author !important "
user " "
The %options are as follows. They are all optional except for
"element".
ua_sheet
The user agent style sheet
user_sheet
The user style sheet
author_sheets
Array ref of style sheets that the HTML document defines or
links to.
element
The element
pseudo
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).
medium
height
width
ppi (To be implemented)
The
CLASSES AND DOM INTERFACES
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::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, RGBColor, Rect
::Value::List CSSValueList
[::Counter Counter]
CSS::DOM does not implement the following interfaces (see HTML::DOM for
these):
LinkStyle
DocumentStyle
ViewCSS
DocumentCSS
DOMImplementationCSS
ElementCSSInlineStyle
IMPLEMENTATION NOTES
· Attributes of objects are accessed via methods of the same name.
When the method is invoked, the current value is returned. If an
argument is supplied, the attribute is set (unless it is read-only)
and its old value returned.
· Where the DOM spec. says to use null, undef or an empty list is
used.
· Instead of UTF-16 strings, CSS::DOM uses Perl's Unicode strings.
· Each method that the specification says returns an array-like
object (e.g., a RuleList) will return such an object in scalar
context, or a simple list in list context. You can use the object
as an array ref in addition to calling its "item" and "length"
methods.
PREREQUISITES
perl 5.8.2 or higher
Exporter 5.57 or later
Encode 2.10 or higher
Clone 0.09 or higher
BUGS
The parser has not been updated to conform to the April 2009 revision
of the CSS 2.1 candidate recommendation. Specifically, unexpected
closing brackets are not ignored, but cause syntax errors; and @media
rules containing unrecognised statements are themselves currently
treated as unrecognised (the unrecognised inner statements should be
ignored, rendering the outer @media rule itself valid).
If you create a custom property parser that defines 'list-style-type'
to include multiple tokens, then counters will become "CSS_CUSTOM"
CSSValue objects instead of "CSS_COUNTER" CSSPrimitiveValue objects.
If you change a property parser's property definitions such that a
primitive value becomes a list, or vice versa, and then try to modify
the "cssText" property of an existing value object belonging to that
property, things will go awry.
Whitespace and comments are sometimes preserved in serialised CSS and
sometimes not. Expect inconsistency.
To report bugs, please e-mail the author.
ACKNOWLEDGEMENTS
Thanks to Ville SkyttA~X and Nicholas Bamber for their contributions.
AUTHOR & COPYRIGHT
Copyright (C) 2007-10 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. The full text of the license can be found
in the LICENSE file included with this module.
SEE ALSO
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 <http://www.w3.org/TR/DOM-
Level-2-Style>
The CSS 2.1 specification at <http://www.w3.org/TR/CSS21/>
perl v5.14.1 2011-06-20 CSS::DOM(3)
