CSS4J RELEASE NOTES
===================
Release 2.0.4 - July 8, 2020
----------------------------
Highlights
----------
Bugfixes, and the nu.validator htmlparser artifact is used instead of the (very
similar) nu.validator.htmlparser's.
Upgrading from 1.0
------------------
The 2.0 branch features NSAC 2.0 and a new Object Model Value API; it is not
backwards-compatible with 1.0, but the new 2.0 APIs are more appropriate to deal
with modern CSS.
NSAC 2.0 no longer inherits from stuff in the org.w3c.css.sac package (provided
by the -not needed anymore- sac.jar file) but is an independent API, with its
methods and features being sort of an hybrid between the old SAC and newer code.
Some interfaces have changed significantly, and the usage of the InputSource
class was reduced and is discouraged (a Reader is being used instead).
Of course this means that other SAC parsers are not supported, which may seem a
loss of flexibility. However, the other parsers are stuck with CSS2 (or partial
support for CSS3) and weren't really usable for real-world sheets. Without the
need to support other SAC parsers, code can be cleaner and is less error-prone
(other parser projects would be welcome to implement NSAC 2 if they wanted to).
The new Value API still uses the interface names CSSValue and CSSPrimitiveValue
but adds others like CSSTypedValue. In the end, its usage is somewhat different
to the old (and deprecated) W3C CSSValue API, requiring almost no type casts to
obtain information to make decisions about value handling (type casts are only
required when retrieving the actual encapsulated value). The categorization of
values is different, and the dimension units are shared with NSAC 2.0 from a
common source interface. But some methods have names similar to the old API to
ease the transition (for example I keep getCssValueType() to retrieve the value
category, instead of a more proper getCategory()).
The extended CSS interfaces in 1.0 ('css' and 'nsac' packages) have now adopted
the names of the interfaces that they were extending, due to the fact that they
are no longer an extension but a full fork. This means that if you are using
interfaces prefixed with 'Extended' or having the '2' suffix from those 'css'
and 'nsac' packages, you need to remove that prefix/suffix to begin the upgrade,
and then use the interfaces from css4j instead of the old W3C ones. Note that
this is only for the CSS interfaces, so the 'Extended'-prefixed interfaces in
the 'doc.dom' package were not changed.
SAC/NSAC 1.x users need to look closely at the new CSSHandler interface, and to
the changes in LexicalUnit; the rest of the API changes should be easy to apply.
The type identifiers in 2.0 use enumerations instead of integers (CSS unit
identifiers are now separate from type identifiers and are still integer).
If you are using the CSSValue API, the upgrade is non-trivial and you should
look at the new interfaces. In many cases where you were using the
CSSPrimitiveValue interface, you should be using the new CSSTypedValue, although
sometimes the renewed CSSValue type may be all that you need.
For example, calls to CSSPrimitiveValue.getRGBColorValue() should be changed to
CSSTypedValue.toRGBColorValue(), but be sure that the type is a COLOR value in
the RGB space before trying to edit the color (and you can use
RGBColorValue.getRGBColorValue() to access the RGBAColor object).
DOM4J users should be aware that the document factory no longer automatically
loads a default User Agent sheet. This backwards-incompatible change may seem
gratuitous, but the old behaviour has shown to be problematic for users.
Finally, the source-level compatibility is now for Java SE version 8 instead of
7: be sure that you are able to use Java 8 or higher.
Description
-----------
This software contains Java(tm) classes covering CSS document style formatting.
Unless otherwise noted, this software is provided under a BSD-style licence
(see the LICENSE.txt file, and also LICENSES.txt for included files that have a
different licensing).
The functionality in this library can be divided in the following areas:
- A CSSOM API very similar to the standard W3C CSS Object Model API, that allows
accessing the CSS information (style sheets, inline styles, etc.) in a DOM
Document, as well as getting computed styles for its elements.
- A CSS-enabled native DOM implementation.
- A DOM wrapper that can be used with an external DOM implementation.
- A DOM4J backend (module css4j-dom4j) which uses documents and elements that
extend those of dom4j (for those who are comfortable with dom4j).
- A device profile API to encapsulate target device-specific information.
- A few AWT helper classes (AWT module).
- Some helper XML-DTD classes.
Packaging
---------
This project is divided in several modules:
- Core module: file css4j-<version>.jar
- User agent module: file css4j-agent-<version>.jar
- Dom4j backend module: file css4j-dom4j-<version>.jar
- AWT module, with AWT helper classes: file css4j-awt-<version>.jar
Depending on your use case, you may just need the core module, the core module
plus the dom4j one, or all four modules.
Java(tm) Runtime Environment requirements
-----------------------------------------
All the classes in the binary package have been compiled with a Java SE
compiler set to 1.8 compiler compliance level, except the module-info files.
Building the library requires JDK 12 or higher, although the resulting jar
files can be run with a 1.8 JRE.
W3C Compliance
--------------
Some parts of the code may throw DOMExceptions that are not covered by the
CSS Object Model specification. Those cases are documented in the code.
The behaviour of the documents and sheets varies according to the 'compliance
mode' of the associated document (DTD-less documents are in 'quirks' mode).
If your use case is broken due to non-conformant behaviour, please report.
CSS3 Support
------------
CSS3 is partially supported by the base CSS interfaces, and is not supported
by the experimental visual formatting model. The following table summarizes
the basic support for setting/retrieving the main CSS level 3/4 features (other
specifications are also supported):
___________________________________________
| CSS3 Spec Name | Support |
|-----------------------------|-------------|
| Background / Border | Yes |
| Color | Yes |
| Media Queries | Partial (1) |
| Selectors | Yes |
| Transitions | Yes |
| Values | Yes |
| Grid / Template / Alignment | Partial (2) |
|_____________________________|_____________|
Notes:
1) Event handling with addListener/removeListener is not supported, given that
the library's user is supposed to be in control of the CSSCanvas instances where
the information about such events should be available.
2) Legacy gap properties (grid-row-gap, grid-column-gap, and grid-gap) are not
supported, although the longhands can be used if declared explicitly).
Using CSS4J
-----------
The usage guide at the website and the Javadoc overviews of the different
packages can be a starting point for users. Unit tests may also be useful
in showing different uses of the library. Generally, the library will be used in
the context of a document object model tree, but stand-alone use of style
declarations and style sheets is also possible.
Software dependencies
=====================
To build this library you need:
- The JCLF package. Version 4.0.4 or higher is required. Go to
https://sourceforge.net/projects/jclf for downloads.
- The SLF4J package, which is a logging package. See http://www.slf4j.org/
for more information.
To build the dom4j module the following is required:
- The dom4j JAR package (tested with 2.1.1).
URL: https://github.com/dom4j
- The XPP3 Pull Parser (which is supported by this library but beware that it
does not support entities). See:
http://www.extreme.indiana.edu/dist/java-repository/xpp3/distributions/
Optional packages:
To run the unit tests you need a recent version of JUnit 4. Tests and the agent
module also require the validator.nu html5 parser:
https://about.validator.nu/htmlparser/
- Dom4j module: unit tests require Jaxen (https://github.com/jaxen-xpath/jaxen).
This software was tested with 1.2.0.
A Maven build (which requires Java 12 or higher) is provided. The dom4j module
requires dom4j 2.x to build, although you should be able to run the resulting
jar file with dom4j 1.6 if you are stuck with it.
Project Sites
=============
Project home: https://css4j.github.io/
Development site: https://github.com/css4j
Task
Major