Skip to content

Commit 89c40b1

Browse files
carlosamecarlosame
committed
Usage: various improvements
1 parent f6c49c7 commit 89c40b1

File tree

1 file changed

+31
-22
lines changed

1 file changed

+31
-22
lines changed

‎usage.html‎

Lines changed: 31 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
<meta name="viewport" content="width=device-width, initial-scale=1">
77
<link href="usage-e.css" rel="stylesheet" type="text/css" />
88
<title>CSS4J Quick Start User Guide</title>
9-
<script src="js/usage-d.js" type="text/javascript" charset="utf-8"></script>
9+
<script src="js/usage-d.js" charset="utf-8"></script>
1010
</head>
1111
<body>
1212
<div class="layout">
@@ -42,7 +42,7 @@ <h2>Overview</h2>
4242
<li><a class="codeitem" href="api/latest/io.sf.carte.css4j/io/sf/carte/doc/style/css/om/AbstractCSSStyleSheet.html">AbstractCSSStyleSheet</a>
4343
for style sheets.</li>
4444
<li><a class="codeitem" href="api/latest/io.sf.carte.css4j/io/sf/carte/doc/style/css/om/StyleRule.html">StyleRule</a>
45-
for style rules.</a></li>
45+
for style rules.</li>
4646
<li><a class="codeitem" href="api/latest/io.sf.carte.css4j/io/sf/carte/doc/style/css/property/StyleValue.html">StyleValue</a>
4747
for values like <code>rgb(12% 0% 67%)</code> or <code>var(--customProperty)</code>.</li>
4848
<li><a class="codeitem" href="api/latest/io.sf.carte.css4j/io/sf/carte/doc/style/css/nsac/LexicalUnit.html">LexicalUnit</a>
@@ -283,7 +283,9 @@ <h2>Examples with DOM4J</h2>
283283
<a href="https://github.com/css4j/css4j-dom4j">css4j-dom4j module</a> in addition to the core
284284
module. The -dom4j module optionally depends on the <a href="https://github.com/css4j/css4j-agent">-agent module</a>,
285285
but you do not need the latter unless you plan to use the DOM4J agent.</p>
286-
<p>For example, with Gradle:</p>
286+
<h3 class="subtema" id="dom4j-gradle">Gradle setup</h3>
287+
<p>For example, to set up css4j-dom4j (and the generally useful xml-dtd) with Gradle, put the following in your
288+
build file:</p>
287289
<pre class="code"><code class="language-groovy">dependencies {
288290
implementation "io.sf.carte:css4j-dom4j:${css4jDom4jVersion}"
289291
implementation "io.sf.carte:xml-dtd:4.2"
@@ -305,6 +307,7 @@ <h2>Examples with DOM4J</h2>
305307
}
306308
}
307309
</code></pre>
310+
<h3 class="subtema" id="dom4j-maven">Maven setup</h3>
308311
<p>Same with Apache Maven:</p>
309312
<pre class="code"><code class="language-xml">&lt;!-- This artifact requires the css4j Maven repository --&gt;
310313
&lt;dependency&gt;
@@ -330,6 +333,7 @@ <h2>Examples with DOM4J</h2>
330333
&lt;/repository&gt;
331334
&lt;/repositories&gt;
332335
</code></pre>
336+
<h3 class="subtema" id="dom4j-depend-compat">Dependencies and compatibility</h3>
333337
<p>The <code>css4j-dom4j</code> artifact transitively implies the <code>css4j</code> core module, but since both artifacts have
334338
different release cycles you may want to add an explicit dependency for the core module, with the latest version.</p>
335339
<p>As explained in the <a href="#modules">modules section</a>, recent <code>css4j-dom4j</code> artifacts are
@@ -360,7 +364,9 @@ <h3 class="subtema" id="dom4j-parsing">Loading and parsing an XML document</h3>
360364
</code></pre>
361365
<p>Be careful to have the <code>XHTMLDocumentFactory</code> loaded with the desired defaults, like the user agent style sheet
362366
which was loaded by default in 1.0 but not in 2.0 and later.</p>
363-
<p>It is also possible to parse an HTML5 document into a css4j-dom4j tree with the aforementioned validator.nu HTML5 parser:</p>
367+
<h3 class="subtema" id="dom4j-html">Parsing HTML5 into DOM4J</h3>
368+
<p>It is also possible to parse an HTML5 document into a css4j-dom4j tree, with the aforementioned
369+
validator.nu HTML5 parser:</p>
364370
<pre class="code"><code class="language-java">XHTMLDocumentFactory factory = XHTMLDocumentFactory.getInstance();
365371
// Next line is optional: default is TRUE, and is probably what you want
366372
// factory.getStyleSheetFactory().setLenientSystemValues(false);
@@ -414,18 +420,9 @@ <h3 class="subtema" id="html-caveats">Caveats about DOM4J and HTML</h3>
414420
it is possible to work around this problem if one serializes to XHTML with a <a href="#serial-xml-html">properly
415421
configured <code>Transformer</code></a>, but not with DOM4J.</p>
416422
</div>
417-
<div class="tema" id="domwrapper">
418-
<h2>Usage with the DOM wrapper</h2>
419-
<p>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
420-
<a class="codeitem" href="api/latest/io.sf.carte.css4j/io/sf/carte/doc/style/css/om/DOMCSSStyleSheetFactory.html#createCSSDocument(org.w3c.dom.Document)">DOMCSSStyleSheetFactory.createCSSDocument(document)</a>
421-
method to wrap a pre-existing DOM Document. Example:</p>
422-
<pre class="code"><code class="language-java">DOMCSSStyleSheetFactory cssFactory = new DOMCSSStyleSheetFactory();
423-
CSSDocument document = cssFactory.createCSSDocument(otherDOMdocument);
424-
</code></pre>
425-
<p>Unlike the native DOM or the DOM4J back-end, the DOM resulting from the DOM wrapper is read-only, although you can change the
426-
values of some nodes.</p>
427-
<h3 class="subtema" id="serial-xml-html">Serializing HTML with an XML DOM</h3>
428-
<p>As was <a href="#html-caveats">previously mentioned</a>, if you serialize a plain HTML document
423+
<div class="tema" id="serial-xml-html">
424+
<h2>Serializing HTML with an XML DOM</h2>
425+
<p>As was previously mentioned, if you serialize a plain HTML document
429426
(which does not contain <code>CDATA</code> sections) with an XML-oriented DOM, you can avoid serializing
430427
<code>div&gt;p</code> as "<code>div&amp;gt;p</code>" if you use a <code>Transformer</code> which is
431428
configured for the task. The code would be like the following:</p>
@@ -435,7 +432,7 @@ <h3 class="subtema" id="serial-xml-html">Serializing HTML with an XML DOM</h3>
435432
// Put other Transformer configurations here
436433
// ...
437434
transformer.setOutputProperty(OutputKeys.ENCODING, "UTF-8");
438-
// Put the embedded style sheets inside <code>CDATA</code> sections
435+
// Put the embedded style sheets inside CDATA sections
439436
transformer.setOutputProperty(OutputKeys.CDATA_SECTION_ELEMENTS, "script style");
440437

441438
Writer wri = ... [put your writer here]
@@ -453,6 +450,18 @@ <h3 class="subtema" id="serial-xml-html">Serializing HTML with an XML DOM</h3>
453450
<p>To handle HTML, the <a href="https://css4j.github.io/api/latest/io.sf.carte.css4j/io/sf/carte/doc/dom/package-summary.html">native DOM</a>
454451
is recommended over any XML DOM.</p>
455452
</div>
453+
<div class="tema" id="domwrapper">
454+
<h2>Usage with the DOM wrapper</h2>
455+
<p>If you choose to build your document with your favorite DOM implementation instead of the CSS4J
456+
one or the DOM4J back-end, you can use the <a class="codeitem" href=
457+
"api/latest/io.sf.carte.css4j/io/sf/carte/doc/style/css/om/DOMCSSStyleSheetFactory.html#createCSSDocument(org.w3c.dom.Document)">DOMCSSStyleSheetFactory.createCSSDocument(document)</a>
458+
method to wrap a pre-existing DOM Document. Example:</p>
459+
<pre class="code"><code class="language-java">DOMCSSStyleSheetFactory cssFactory = new DOMCSSStyleSheetFactory();
460+
CSSDocument document = cssFactory.createCSSDocument(otherDOMdocument);
461+
</code></pre>
462+
<p>Unlike the native DOM or the DOM4J back-end, the DOM resulting from the DOM wrapper is read-only, although you can change the
463+
values of some nodes.</p>
464+
</div>
456465
<div id="dom-impls-diff" class="tema">
457466
<h2>Consistency of different DOM implementations</h2>
458467
<p>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
@@ -496,7 +505,7 @@ <h3 class="subtema" id="rule-iterators">Rule iterators</h3>
496505
* It is possible to use iterators to retrieve the rules.
497506
*/
498507
sheet = sheets.item(0);
499-
Iterator<AbstractCSSRule> it = sheet.getCssRules().iterator();
508+
Iterator&lt;AbstractCSSRule&gt; it = sheet.getCssRules().iterator();
500509
// Assume it.hasNext() returns true
501510

502511
// Access the first rule in the sheet
@@ -541,11 +550,11 @@ <h3 class="subtema" id="selectors">Dealing with selectors</h3>
541550
Selector selector = selist.item(0);
542551
// Selector type (which we can use to cast the selector)
543552
SelectorType selType = selector.getSelectorType();
544-
// For "div > .myClass" selType would be SelectorType.CHILD
553+
// For "div &gt; .myClass" selType would be SelectorType.CHILD
545554

546555
// Cast to CombinatorSelector (see CHILD javadoc)
547556
CombinatorSelector comb = (CombinatorSelector) selector;
548-
// Obtain the two selectors that are combined by ">"
557+
// Obtain the two selectors that are combined by "&gt;"
549558
Selector firstSel = comb.getSelector();
550559
SimpleSelector secondSel = comb.getSecondSelector();
551560

@@ -888,7 +897,7 @@ <h3 class="subtema" id="media-queries">Media queries</h3>
888897
/*
889898
* Parsing a Media Query
890899
*/
891-
MediaQueryList mql = cssFactory.createMediaQueryList("screen and (600px <= width < 1200px)",
900+
MediaQueryList mql = cssFactory.createMediaQueryList("screen and (600px &lt;= width &lt; 1200px)",
892901
null);
893902

894903
// How many queries we got?
@@ -912,7 +921,7 @@ <h3 class="subtema" id="media-queries">Media queries</h3>
912921
// It is BooleanCondition.Type.AND
913922

914923
// As the AND javadoc suggests, call getSubConditions()
915-
List<BooleanCondition> andConds = cond.getSubConditions();
924+
List&lt;BooleanCondition&gt; andConds = cond.getSubConditions();
916925
// andConds.size() is 2
917926

918927
// The first operand of the AND

0 commit comments

Comments
 (0)