1CSS::DOM(3)           User Contributed Perl Documentation          CSS::DOM(3)
2
3
4

NAME

6       CSS::DOM - Document Object Model for Cascading Style Sheets
7

VERSION

9       Version 0.17
10
11       This is an alpha version. The API is still subject to change. Many
12       features have not been implemented yet (but patches would be welcome
13       :-).
14
15       The interface for feeding CSS code to CSS::DOM changed incompatibly in
16       version 0.03.
17

SYNOPSIS

19         use CSS::DOM;
20
21         my $sheet = CSS::DOM::parse( $css_source );
22
23         use CSS::DOM::Style;
24         my $style = CSS::DOM::Style::parse(
25             'background: red; font-size: large'
26         );
27
28         my $other_sheet = new CSS::DOM; # empty
29         $other_sheet->insertRule(
30            'a{ text-decoration: none }',
31             $other_sheet->cssRules->length,
32         );
33         # etc.
34
35         # access DOM properties
36         $other_sheet->cssRules->[0]->selectorText('p'); # change it
37         $style->fontSize;          # returns 'large'
38         $style->fontSize('small'); # change it
39

DESCRIPTION

41       This set of modules provides the CSS-specific interfaces described in
42       the W3C DOM recommendation.
43
44       The CSS::DOM class itself implements the StyleSheet and CSSStyleSheet
45       DOM interfaces.
46
47       This set of modules has two modes:
48
49       1.  It can validate property values, ignoring those that are invalid
50           (just like a real web browser), and support shorthand properties.
51           This means you can set font to '13px/15px My Font' and have the
52           font-size, line-height, and font-family properties (among others)
53           set automatically. Also, "color: green; color: kakariki" will
54           assign 'green' to the color property, 'kakariki' not being a
55           recognised color value.
56
57       2.  It can blithely accept all property assignments as being valid. In
58           the case of "color: green; color: kakariki", 'kakariki' will be
59           assigned, since it overrides the previous assignment.
60
61       These two modes are controlled by the "property_parser" option to the
62       constructors.
63

CONSTRUCTORS

65       CSS::DOM::parse( $string )
66           This method parses the $string and returns a style sheet object. If
67           you just have a CSS style declaration, e.g., from an HTML "style"
68           attribute, see "parse" in CSS::DOM::Style.
69
70       new CSS::DOM
71           Creates a new, empty style sheet object. Use this only if you plan
72           to build the style sheet piece by piece, instead of parsing a block
73           of CSS code.
74
75       You can pass named arguments to both of those. "parse" accepts all of
76       them; "new" understands only the first two, "property_parser" and
77       "url_fetcher".
78
79       property_parser
80           Set this to a PropertyParser object to specify which properties are
81           supported and how they are parsed.
82
83           If this option is not specified or is set to "undef", all property
84           values are treated as valid.
85
86           See CSS::DOM::PropertyParser for more details.
87
88       url_fetcher
89           This has to be a code ref that returns the contents of the style
90           sheet at the URL passed as the sole argument. E.g.,
91
92             # Disclaimer: This does not work with relative URLs.
93             use LWP::Simple;
94             use CSS::DOM;
95             $css = '@import "file.css"; /* other stuff ... ';
96             $ss = CSS::DOM::parse $css, url_fetcher => sub { get shift };
97             $ss->cssRules->[0]->styleSheet; # returns a style sheet object
98                                             # corresponding to file.css
99
100           The subroutine can choose to return "undef" or an empty list, in
101           which case the @import rule's "styleSheet" method will return null
102           (empty list or "undef"), as it would if no "url_fetcher" were
103           specified.
104
105           It can also return named items after the CSS code, like this:
106
107             return $css_code, decode => 1, encoding_hint => 'iso-8859-1';
108
109           These correspond to the next two items:
110
111       decode
112           If this is specified and set to a true value, then CSS::DOM will
113           treat the CSS code as a string of bytes, and try to decode it based
114           on @charset rules and byte order marks.
115
116           By default it assumes that it is already in Unicode (i.e.,
117           decoded).
118
119       encoding_hint
120           Use this to provide a hint as to what the encoding might be.
121
122           If this is specified, and "decode" is not, then "decode => 1" is
123           assumed.
124

STYLE SHEET ENCODING

126       See the options above. This section explains how and when you should
127       use those options.
128
129       According to the CSS spec, any encoding specified in the 'charset'
130       field on an HTTP Content-Type header, or the equivalent in other
131       protocols, takes precedence. In such a case, since CSS::DOM doesn't
132       deal with HTTP, you have to decode it yourself.
133
134       Otherwise, you should use "decode => 1" to instruct CSS::DOM to use
135       byte order marks or @charset rules.
136
137       If neither of those is present, then encoding data in the referencing
138       document (e.g., <link charset="..."> or an HTML document's own
139       encoding), if available/applicable, should be used. In this case, you
140       should use the "encoding_hint" option, so that CSS::DOM has something
141       to fall back to.
142
143       If you use "decode => 1" with no encoding hint, and no BOM or @charset
144       is to be found, UTF-8 is assumed.
145

SYNTAX ERRORS

147       The two constructors above, and also "CSS::DOM::Style::parse", set $@
148       to the empty string upon success. If they encounter a syntax error,
149       they set $@ to the error and return an object that represents whatever
150       was parsed up to that point.
151
152       Other methods that parse CSS code might die on encountering syntax
153       errors, and should usually be wrapped in an "eval".
154
155       The parser follows the 'future-compatible' syntax described in the CSS
156       2.1 specification, and also the spec's rules for handling parsing
157       errors.  Anything not handled by those two is a syntax error.
158
159       In other words, a syntax error is one of the following:
160
161       •   An unexpected closing bracket, as in these examples
162
163             a { text-decoration: none )
164             *[name=~'foo'} {}
165             #thing { clip: rect( ]
166
167       •   An HTML comment delimiter within a rule; e.g.,
168
169             a { text-decoration : none <!-- /* Oops! */ }
170             <!-- /*ok*/ @media --> /* bad! */ print { }
171
172       •   An extra "@" keyword or semicolon where it doesn't belong; e.g.,
173
174             @media @print { .... }
175             @import "file.css" @print;
176             td, @page { ... }
177             #tabbar td; #tab1 { }
178

OBJECT METHODS

180   Attributes
181       type
182           Returns the string 'text/css'.
183
184       disabled
185           Allows one to specify whether the style sheet is used. (This
186           attribute is not actually used yet by CSS::DOM.) You can set it by
187           passing an argument.
188
189       ownerNode
190           Returns the node that 'owns' this style sheet.
191
192       parentStyleSheet
193           If the style sheet belongs to an '@import' rule, this returns the
194           style sheet containing that rule. Otherwise it returns an empty
195           list.
196
197       href
198           Returns the style sheet's URI, if applicable.
199
200       title
201           Returns the value of the owner node's title attribute.
202
203       media
204           Returns the MediaList associated with the style sheet (or a plain
205           list in list context). This defaults to an empty list. You can pass
206           a comma-delimited string to the MediaList's "mediaText" method to
207           initialise it.
208
209           (The medium information is not actually used [yet] by CSS::DOM, but
210           you can put it there.)
211
212       ownerRule
213           If this style sheet was created by an @import rule, this returns
214           the rule; otherwise it returns an empty list (or undef in scalar
215           context).
216
217       cssRules
218           In scalar context, this returns a CSS::DOM::RuleList object (simply
219           a blessed array reference) of CSS::DOM::Rule objects. In list
220           context it returns a list.
221
222   Methods
223       insertRule ( $css_code, $index )
224           Parses the rule contained in the $css_code, inserting it in the
225           style sheet's list of rules at the given $index.
226
227       deleteRule ( $index )
228           Deletes the rule at the given $index.
229
230       hasFeature ( $feature, $version )
231           You can call this either as an object or class method.
232
233           This is actually supposed to be a method of the 'DOMImplementation'
234           object.  (See, for instance, HTML::DOM::Interface's method of the
235           same name, which delegates to this one.) This returns a boolean
236           indicating whether a particular DOM module is implemented. Right
237           now it returns true only for the 'CSS2' and 'StyleSheets' features
238           (version '2.0').
239
240   Non-DOM Methods
241       set_ownerNode
242           This allows you to set the value of "ownerNode". Passing an
243           argument to "ownerNode" does nothing, because it is supposed to be
244           read-only. But you have to be able to set it somehow, so that's why
245           this method is here.
246
247           The style sheet will hold a weak reference to the object passed to
248           this method.
249
250       set_href
251           Like "set_ownerNode", but for "href".
252
253       property_parser
254       url_fetcher
255           These two both return what was passed to the constructor. The
256           second one, "url_fetcher" also allows an assignment, but this is
257           not propagated to sub-rules and is intended mainly for internal
258           use.
259

FUNCTIONS

261       CSS::DOM::parse
262           See "CONSTRUCTORS", above.
263
264       CSS::DOM::compute_style( %options )
265           Warning: This is still highly experimental and crawling with bugs.
266
267           This computes the style for a given HTML element. It does not yet
268           calculate actual measurements (e.g., converting percentages to
269           pixels), but simply applies the cascading rules and selectors.
270           Pseudo-classes are not yet supported (but pseudo-elements are).
271
272           The precedence rules for normal vs important declarations in the
273           CSS 2 specification are used. (CSS 2.1 is unclear.) The precedence
274           is as follows, from lowest to highest:
275
276            user agent normal declarations
277            user normal declarations
278            author normal     "
279            user agent !important declarations
280            author !important "
281            user      "       "
282
283           The %options are as follows. They are all optional except for
284           "element".
285
286           ua_sheet
287               The user agent style sheet
288
289           user_sheet
290               The user style sheet
291
292           author_sheets
293               Array ref of style sheets that the HTML document defines or
294               links to.
295
296           element
297               The element, as an HTML::DOM::Element object.
298
299           pseudo
300               The pseudo-element (e.g., 'first-line'). This can be specified
301               with no colons (the way Opera requires it) or with one or two
302               colons (the way Firefox requires it).
303
304           medium
305           height
306           width
307           ppi (To be implemented)
308
309           The
310

CLASSES AND DOM INTERFACES

312       Here are the inheritance hierarchy of CSS::DOM's various classes and
313       the DOM interfaces those classes implement. For brevity's sake, a
314       simple '::' at the beginning of a class name in the left column is used
315       for 'CSS::DOM::'. Items in brackets do not exist yet. (See also
316       CSS::DOM::Interface for a machine-readable list of standard methods.)
317
318         Class Inheritance Hierarchy  Interfaces
319         ---------------------------  ----------
320
321         CSS::DOM                     StyleSheet, CSSStyleSheet
322         ::Array
323             ::MediaList              MediaList
324             ::StyleSheetList         StyleSheetList
325             ::RuleList               CSSRuleList
326         ::Rule                       CSSRule, CSSUnknownRule
327             ::Rule::Style            CSSStyleRule
328             ::Rule::Media            CSSMediaRule
329             ::Rule::FontFace         CSSFontFaceRule
330             ::Rule::Page             CSSPageRule
331             ::Rule::Import           CSSImportRule
332             ::Rule::Charset          CSSCharsetRule
333         ::Style                      CSSStyleDeclaration, CSS2Properties
334         ::Value                      CSSValue
335         ::Value::Primitive           CSSPrimitiveValue, RGBColor, Rect
336         ::Value::List                CSSValueList
337        [::Counter                    Counter]
338
339       CSS::DOM does not implement the following interfaces (see HTML::DOM for
340       these):
341
342         LinkStyle
343         DocumentStyle
344         ViewCSS
345         DocumentCSS
346         DOMImplementationCSS
347         ElementCSSInlineStyle
348

IMPLEMENTATION NOTES

350       •   Attributes of objects are accessed via methods of the same name.
351           When the method is invoked, the current value is returned. If an
352           argument is supplied, the attribute is set (unless it is read-only)
353           and its old value returned.
354
355       •   Where the DOM spec. says to use null, undef or an empty list is
356           used.
357
358       •   Instead of UTF-16 strings, CSS::DOM uses Perl's Unicode strings.
359
360       •   Each method that the specification says returns an array-like
361           object (e.g., a RuleList) will return such an object in scalar
362           context, or a simple list in list context. You can use the object
363           as an array ref in addition to calling its "item" and "length"
364           methods.
365

PREREQUISITES

367       perl 5.8.2 or higher
368
369       Exporter 5.57 or later
370
371       Encode 2.10 or higher
372
373       Clone 0.09 or higher
374

BUGS

376       The parser has not been updated to conform to the April 2009 revision
377       of the CSS 2.1 candidate recommendation. Specifically, unexpected
378       closing brackets are not ignored, but cause syntax errors; and @media
379       rules containing unrecognised statements are themselves currently
380       treated as unrecognised (the unrecognised inner statements should be
381       ignored, rendering the outer @media rule itself valid).
382
383       If you create a custom property parser that defines 'list-style-type'
384       to include multiple tokens, then counters will become "CSS_CUSTOM"
385       CSSValue objects instead of "CSS_COUNTER" CSSPrimitiveValue objects.
386
387       If you change a property parser's property definitions such that a
388       primitive value becomes a list, or vice versa, and then try to modify
389       the "cssText" property of an existing value object belonging to that
390       property, things will go awry.
391
392       Whitespace and comments are sometimes preserved in serialised CSS and
393       sometimes not.  Expect inconsistency.
394
395       To report bugs, please e-mail the author.
396

ACKNOWLEDGEMENTS

398       Thanks to Ville Skyttä, Nicholas Bamber and Gregor Herrmann for their
399       contributions.
400
402       Copyright (C) 2007-18 Father Chrysostomos <sprout [at] cpan [dot] org>
403
404       This program is free software; you may redistribute it and/or modify it
405       under the same terms as perl. The full text of the license can be found
406       in the LICENSE file included with this module.
407

SEE ALSO

409       All the classes listed above under "CLASSES AND DOM INTERFACES".
410
411       CSS::SAC, CSS.pm and HTML::DOM
412
413       The DOM Level 2 Style specification at
414       <http://www.w3.org/TR/DOM-Level-2-Style>
415
416       The CSS 2.1 specification at <http://www.w3.org/TR/CSS21/>
417
418
419
420perl v5.36.0                      2023-01-20                       CSS::DOM(3)
Impressum