css4j 1.3.1 API
This project is an implementation of W3C's CSS Object Model API in the Java™ language, and also adds CSS support to the DOM4J package. It targets several different use cases, with functionalities from style sheet error detection to style computation.
This implementation can be used in several ways: with stand-alone style sheets, with its own DOM implementation, combined with DOM4J, or by wrapping a pre-existing DOM tree.
You can play with independent style sheets created with the
createStyleSheet("title", "media") method of the
There are three implementations of that interface:
CSSDOMImplementation, the native DOM implementation.
DOMCSSStyleSheetFactoryfor the DOM Wrapper.
- If you use DOM4J, get it through
The document back-end is only important if you plan to use the sheets inside a document.
The resulting style sheets are empty, but you can load a style sheet with the
method (see Parsing a Style Sheet).
One of the most important functionalities in the library is the ability to compute styles for a given element. In practice, to obtain the 'computed' or 'used' values required for actual rendering a box model implementation is needed, and also device information. The library provides a simple box model that could be used, but the details of the rendering device can be more difficult.
Depending on the use case, the target device may not be the same one where the library is running (and some exact details hence not available).
To help in the computation, the library defines the
DeviceFactory interface to supply device and media-specific data (also provides
the objects required by media queries to work).
Prerequisite: Choose a SAC Parser
This library depends on a SAC parser to work. There are three active projects offering a SAC parser:
- Batik's SAC parser. Class name:
- Steadystate's cssparser (
- This library's own parser (
Batik's parser used to be this library's default parser, but its functionality is now lagging behind and cannot be recommended to handle level 3 or 4 CSS.
The Steadystate parser does better and mostly implements CSS3, but does not process
calc() values nor supports SAC comments. Both handle some
selectors in their own, undocumented way (example: pseudo-element support) that is not always easy to support.
Finally, this project's own parser supports level 4 values and selectors; an extension to SAC called NSAC was developed for that. This is the recommended parser.
Once you have chosen your parser, set the
org.w3c.css.sac.parser system property to its qualified class name, e.g.
com.steadystate.css.parser.SACParserCSS3. If you decide to use this project's internal parser you do not need to set that property, as it is
the default parser.
Once you have the SAC parser and the rest of the dependencies (see the Release Notes) available in the classpath, and set the appropriate system property (if not using this library's own parser), you can start using the library. If you build it with Maven, beware that one of the dependencies (JCLF) is not available at any central repository and has to be manually downloaded and installed to your local repository.
Using css4j's native DOM implementation
You can create a DOM document from scratch and use the related DOM methods to programmatically build a document: just use the provided DOM implementation
io.sf.carte.doc.dom.CSSDOMImplementation). If you want to parse an existing document, the procedure depends on the type of document: to parse
an XML document (including XHTML documents), you can use this library's
XMLDocumentBuilder, while to parse an HTML one (or an
XHTML document that does not use namespace prefixes) you can use the validator.nu
An example with that parser follows:
import java.io.Reader; import org.xml.sax.InputSource; import org.xml.sax.SAXException; import org.w3c.dom.css.CSSPrimitiveValue; import io.sf.carte.doc.dom.CSSDOMImplementation; import io.sf.carte.doc.dom.DOMElement; import io.sf.carte.doc.dom.HTMLDocument; import io.sf.carte.doc.style.css.CSSComputedProperties; import io.sf.carte.doc.style.css.CSSPrimitiveValue2; import io.sf.carte.doc.style.css.RGBAColor; import io.sf.carte.doc.xml.dtd.DefaultEntityResolver; import nu.validator.htmlparser.dom.HtmlDocumentBuilder; [...] // Instantiate DOM implementation (with default settings: no IE hacks accepted) // and configure it CSSDOMImplementation impl = new CSSDOMImplementation(); // Alternatively, impl = new CSSDOMImplementation(flags); // Now load default HTML user agent sheets impl.setDefaultHTMLUserAgentSheet(); // Prepare builder HtmlDocumentBuilder builder = new HtmlDocumentBuilder(impl); // Read the document to parse, and prepare source object Reader re = ... [reader for HTML document] InputSource source = new InputSource(re); // Parse. If the document is not HTML, you want to use DOMDocument instead HTMLDocument document = (HTMLDocument) builder.parse(source); re.close(); // Set document URI document.setDocumentURI("http://www.example.com/mydocument.html");
Then you have a CSS-enabled document. To compute styles, use
DOMElement element = document.getElementById("someId"); CSSComputedProperties style = element.getComputedStyle(null); // Next line could be 'String display = style.getDisplay();' String display = style.getPropertyValue("display"); // If you use a factory that has been set to setLenientSystemValues(false), next // line may throw an exception if the 'color' property was not specified. // The default value for lenientSystemValues is TRUE. RGBAColor color = ((CSSPrimitiveValue2) style.getPropertyCSSValue("color")).getRGBColorValue(); // CSSPrimitiveValue2 is an extension to W3C's CSSPrimitiveValue // Suppose that the linked style sheet located at 'css/sheet.css' declares: // background-image: url('foo.png'); String image_css = style.getPropertyValue("background-image"); String image_uri = ((CSSPrimitiveValue) style.getPropertyCSSValue("background-image")).getStringValue(); // Then, because we already set the document URI to "http://www.example.com/mydocument.html", // image_css will be set to "url('http://www.example.com/css/foo.png')", // and image_uri to "http://www.example.com/css/foo.png"
If you are computing styles for a specific medium, tell the document about it (see "Media Handling"):
Conformance with the DOM specification
This library's native DOM implementation has some minor behavior differences with what is written in the DOM
Level 3 Core Specification. For example, on elements and attributes the
Node.getLocalName() method returns the tag name instead of
null when the node was created with a DOM Level 1 method such as Document.createElement(). Read the
description for additional information.
Usage with the DOM Wrapper
If you choose to build your document with your favorite DOM implementation instead of the CSS4J one or the DOM4J back-end, you can use the
method to wrap a pre-existing DOM Document. Example:
DOMCSSStyleSheetFactory factory = new DOMCSSStyleSheetFactory(); CSSDocument document = factory.createCSSDocument(otherDOMdocument);
Unlike the native DOM or the DOM4J back-end, the DOM resulting from the DOM wrapper is read-only, although you can change the values of some nodes.
Consistency of different DOM implementations
Beware that the computed styles found by each method (native DOM, DOM4J back-end or DOM wrapper) may not be completely identical, due to differences in the underlying document DOM implementations. For example, XML-oriented DOM implementations do not implement the case sensitivity subtleties of HTML. If you find a difference in styles computed from different back-ends that you believe to be a bug, please report.
By default, computed styles only take into account generic styles that are common to all media. If you want to target a more specific medium,
you have to use the
CSSDocument.setTargetMedium("medium") method. For example, if your document has the following style sheets linked:
<link href="http://www.example.com/css/sheet.css" rel="stylesheet" type="text/css" /> <link href="http://www.example.com/css/sheet_for_print.css" rel="stylesheet" media="print" type="text/css" />
Computed styles will initially take into account only the "sheet.css" style sheet. However, if you execute the following method:
Then all subsequently computed styles will account for the merged style sheet from "sheet.css" and "sheet_for_print.css".
This way to tie a document with a medium is not totally standard, as the W3C APIs would probably expect a
DeviceFactory-related object implementing the
ViewCSS interface and referencing the document,
but this approach allows to isolate DOM logic inside DOM objects and keep the
DeviceFactory for media-specific information only.
Style Sheet Sets
The library supports alternative style sheets. Use CSSDocument's methods enableStyleSheetsForSet, getStyleSheetSets, getSelectedStyleSheetSet and setSelectedStyleSheetSet. For example, if you have a document with these linked sheets:
<link href="http://www.example.com/commonsheet.css" rel="stylesheet" type="text/css" /> <link href="http://www.example.com/alter1.css" rel="alternate stylesheet" type="text/css" title="Alter 1" /> <link href="http://www.example.com/alter2.css" rel="alternate stylesheet" type="text/css" title="Alter 2" /> <link href="http://www.example.com/default.css" rel="stylesheet" type="text/css" title="Default" />
Initially, sheets 'alter1.css' and 'alter2.css' will not be used to compute styles. But then you can write code like the following:
String defset = document.getSelectedStyleSheetSet(); // Sets 'defset' to "Default" document.setSelectedStyleSheetSet("Alter 1"); // Selects the set with title "Alter 1" document.setSelectedStyleSheetSet("Alter 2"); // Selects the set with title "Alter 2"
These methods have been removed from the DOM standard unfortunately, but you can still read the specification at the CSSOM 5 December 2013 Working Draft.
Style Sheet Error Checking
You can check for errors and warnings in the document's sheets using the non-standard
getErrorHandler method. Example:
if (document.getStyleSheets().item(0).getErrorHandler().hasSacErrors()) ... error processing / reporting
The merged style sheet obtained from the
getStyleSheet method has the merged error/warning state from the document's active sheets.
A typical source of errors are the non-compliant IE hacks, like prefixing property names with an asterisk (you may want to use the proper
NSAC flags when creating the factory, see Compatibility with legacy browsers),
or charset rules found in the wrong place. On the other hand, if you aren't using this library's own SAC parser some errors may mean that the parser
did not recognize a valid syntax (e.g.
calc() values), rather than an error in the style sheet.
Override styles, that come after the author style sheet in the cascade algorithm, are supported. For example:
document.getOverrideStyle(element, null).setCssText("padding: 6pt;");
getOverrideStyle method is defined at the DocumentCSS interface.
Parsing a Style Sheet
Although document's style sheet fetching and parsing is automatic with this library, it is possible to manually parse rules from a source stream with the
ExtendedCSSStyleSheet.parseStyleSheet(InputSource, boolean) method:
Reader re = ... org.w3c.css.sac.InputSource source = new org.w3c.css.sac.InputSource(re); sheet.parseStyleSheet(source, true);
The new css rules found in the source stream are added to the already present ones, i.e. the sheet is not reset by this method (although the error handler is).
When the second argument is
true, the comments in the source stream are ignored when parsing.
Compatibility with legacy Browsers (NSAC-only)
This section only applies if you are using a NSAC parser, like this library's default one.
Today's style sheets often contain non-conformant styles that target specific versions of old web browsers, like Internet Explorer. Several web sites contain information about that, including:
Although it could be argued whether those hacks should be used or not, the point is that actual style sheets do contain them, so this library supports them.
By default, a factory is configured to use a flagless NSAC parser which would produce an error on any of those non-standard constructs, but a set of compatibility flags can be specified in the constructors for the factory implementations. The different flags are documented in the NSAC javadocs.
The flags available at the time of this guide's update are the following:
STARHACK. When set, the parser will handle asterisk-prefixed property names as accepted, normal names.
IEVALUESsupports values ending with
\0, as well as progid filters and IE expressions.
IEPRIOallows values ending with the
IEPRIOCHARaccepts values with an
'!important!'priority hack (note the
'!'at the end).
The object model manages these compatibility values in parallel to standard ones. For example, after parsing this declaration
width: 900px; width: 890px\9;
its serialization would be identical (if the flag was set correctly):
width: 900px; width: 890px\9;
but the declaration's length shall be only
1. And computed styles only use the standard values unless there are
no alternatives (no standard value was set). The workings are similar for
width: 890px !ie; width: 890px !important!;
with the last one being handled as of
important priority. Values created by
IEPRIOCHAR are never used
in computed styles.
Instead, declarations including asterisk-prefixed property names (created by
STARHACK) always increase the declaration's
length. For example, the length of the following declaration would be
width: 890px; *width: 890px;
If you want to use these flags at the NSAC level (instead of the Object Model), you may want to read the 'Parser Flags' section in the
NSAC package description, as well as the documentation for the individual flags in
CSS Style Formatting
The serialization of the
cssText attribute in rules and
style declarations can be customized with an implementation
You can set your
(which produces your customized formatting context) to the sheet factory with the
method, or subclass your base factory and override the
Look at the
DefaultStyleFormattingContext class for an example of a formatting context implementation.
There is also the possibility to customize the default serialization of string values, with the
method. You can set two flags that govern which quotation you prefer, or keep the default behaviour:
- Default: Try to keep the original quotation (single or double quotes), unless the alternative is more efficient.
STRING_DOUBLE_QUOTE: Use double quotes unless single quotes are more efficient (when the string contains more double quotes than single).
STRING_SINGLE_QUOTE: Use single quotes unless double quotes are more efficient (when the string contains more single quotes than double).
Accessing Style Sheet Comments
There is no standard CSSOM API for accessing comments in style sheets, but the
AbstractCSSRule.getPrecedingComments() method is provided for that:
List<String> comments = document.getStyleSheets().item(0).getCssRules().item(3).getPrecedingComments();
Other API models were considered for object-model comments, like having a special type of comment rule, but stylesheet-level comments are often related to a rule and if that rule is moved or deleted, those stand-alone comments would have the potential to create a lot of confusion.
The comments preceding any rule will be included in the text returned by the sheet's
while other comments (located at places that cannot be easily related to a rule) are lost.
BUG: comments that are intended to apply to the previous rule may be assigned to the next one. This is intended to be addressed in version 2.0, when SAC-based parsing is going to be partly replaced.
Comments in the default HTML style sheet are not available, as the parser is instructed to ignore them when parsing.
CSS level 3 and 4 Support
CSS level 3/4 is only partially supported by the library; the following table summarizes the basic support for setting/retrieving the main CSS specifications (as of 2019):
|CSS Spec Name||Support||Observations|
|Background / Border||Yes|
|Color||Partial||Some level 4 functions are not implemented.|
|Media Queries||Partial||Event handling with addListener/removeListener is not supported. Relies on CSSCanvas implementations to match/unmatch media features.|
|Selectors||Yes||Only this library's own SAC/NSAC parser supports level 4 selectors.|
|Values||Yes||Only this library's own SAC/NSAC parser supports |
|Grid / Template / Alignment||Partial||Legacy gap properties (|
The following pseudo-classes are supported by the library (although they may not be supported by the SAC parser that you are using):
State pseudo-classes like
hover are supported through the
CSSCanvas.isActivePseudoClass(CSSElement, String) method.
To help with the determination of 'used' values and the actual rendering, this library provides a few helper interfaces. The most important are:
DeviceFactory. It is not a "factory of devices", but instead the object that delivers the relevant abstractions for a requested medium:
StyleDatabase. Provides medium-specific information like available fonts and colors.
CSSCanvas. Has knowledge of medium-specific information that depends (or may depend) on a specific viewport, like supported media features. It is linked to a viewport, if there is any. This interface is used to determine the state of active pseudo-classes.
Viewport. It represents a viewport defined as per the CSS specifications.
The differences between style databases and canvases can be subtle, and for some media features it could be argued that they belong to one or the other. The basic idea is that style databases should be relatively easy to implement for a given medium, while canvases are probably only going to exist if there is an actual rendering engine implemented.
Java™ Runtime Environment Requirements
The classes in the binary packages have been compiled with a Java SE compiler with 1.7 compiler compliance level,
except for the
module-info file which targets Java 11.