Skip to content

Commit 733d6dc

Browse files
carlosamecarlosame
committed
Add two documentation files, upgrade PrismJS to 1.25.0
1 parent ecce0e3 commit 733d6dc

13 files changed

+349
-149
lines changed

Diff for: ‎code-c.css

+1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

Diff for: ‎embed-svg.html

+148
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
<!DOCTYPE html><html lang="en"><head>
2+
<title>Embedding SVG in HTML</title>
3+
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
4+
<meta name="viewport" content="width=device-width, initial-scale=1" />
5+
<link href="code-c.css" rel="stylesheet" type="text/css" />
6+
<script src="js/code-a.js" type="text/javascript" charset="utf-8"></script>
7+
</head>
8+
<body>
9+
<div class="layout">
10+
<div id="hdr01"></div>
11+
<a id="mylinkhome" href="/"><span>CSS4J</span></a>
12+
</div>
13+
<div class="container">
14+
<div class="menu">
15+
<ul class="menulist">
16+
<li><a id="mnuindice" href="/"><span>Home</span></a></li>
17+
<li><a id="mnuusage" href="usage.html"><span>Usage</span></a></li>
18+
<li class="menulvl2"><div id="mnuembedsvg-sel"><span>Embed SVG</span></div></li>
19+
<li class="menulvl2"><a id="mnuresolver" href="resolver.html"><span>Resolver</span></a></li>
20+
<li><a id="mnuapi2" href="api/3/"><span>API 3.x</span></a></li>
21+
<li><a id="mnufaq" href="faq.html"><span>FAQ</span></a></li>
22+
<li><a id="mnubenchmarks" href="benchmarks.html"><span>Benchmarks</span></a></li>
23+
<li><a id="mnugithub" href="https://github.com/css4j"><span>Github</span></a></li>
24+
</ul>
25+
</div>
26+
<div class="beforemain"></div>
27+
<div class="main">
28+
<div id="presentacion_top" class="textheader"><span>Embed SVG</span></div>
29+
<div class="cos">
30+
<h1>Embedding SVG in HTML documents</h1>
31+
<div class="tema" id="overview">
32+
<h2>Overview</h2>
33+
<p><a href="https://developer.mozilla.org/en-US/docs/Web/SVG">SVG images</a> can be used as stand-alone files, but the
34+
most efficient way to include them in an HTML document is by embedding them. However, this may cause unexpected problems due to
35+
two factors:</p>
36+
<ul>
37+
<li>Element IDs that were unique in the SVG image and the main document may collide, causing the HTML to become non-conformant
38+
due to the presence of two (or more) <a href="https://html.spec.whatwg.org/multipage/introduction.html#restrictions-on-content-models-and-on-attribute-values:the-id-attribute">elements with the same ID</a>.</li>
39+
<li>The way that <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style"><code>STYLE</code></a> elements are handled in HTML documents may cause further collisions (see below).</li>
40+
</ul>
41+
<p>The <code>STYLE</code> elements contained inside the hierarchy of the <code>SVG</code> elements are used for the
42+
computation of the styles of the whole document. That is, the rules located in a style sheet that was written for a
43+
specific SVG image are accounted like if the <code>STYLE</code> was located at the <code>HEAD</code> element (but applying
44+
the CSS precedence rules).</p>
45+
<p>Due to that, there could be a collision between IDs and class names in the CSS from the SVG image(s) and the main document,
46+
or among the embedded SVG images.</p>
47+
</div>
48+
<div class="tema" id="visitor">
49+
<h2>Using the visitor pattern to replace identifiers</h2>
50+
<p>Fortunately, the css4j library provides the necessary tools to visit the CSS rules and make the necessary checks and
51+
modifications to the relevant selectors. You can use your favourite DOM implementation to check and modify duplicate <code>id</code>
52+
attributes (if you use css4j's <a href="https://css4j.github.io/api/3/io/sf/carte/doc/dom/package-summary.html">native DOM</a>,
53+
a <a class="codeitem" href="https://css4j.github.io/api/3/io/sf/carte/doc/dom/NodeIterator.html"><code>NodeIterator</code></a>
54+
could be a good choice), but the changes must be consistent with what you apply on the selectors.</p>
55+
<p>For example, the
56+
<a class="codeitem" href="https://css4j.github.io/api/3/io/sf/carte/doc/style/css/parser/AttributeConditionVisitor.html"><code>AttributeConditionVisitor</code></a>
57+
class can be of help for the task. Let us subclass it to provide our own logic:</p>
58+
<pre class="code"><code class="language-java">package com.example;
59+
60+
import io.sf.carte.doc.style.css.nsac.AttributeCondition;
61+
import io.sf.carte.doc.style.css.nsac.Condition.ConditionType;
62+
import io.sf.carte.doc.style.css.parser.AttributeConditionVisitor;
63+
64+
class DupeConditionVisitor extends AttributeConditionVisitor {
65+
66+
@Override
67+
public void visit(AttributeCondition condition) {
68+
ConditionType type = condition.getConditionType();
69+
if (type == ConditionType.ID || type == ConditionType.CLASS) {
70+
String currentName = condition.getValue();
71+
if (isBadName(currentName)) {
72+
String newName = getNewName(currentName);
73+
setConditionValue(condition, newName);
74+
}
75+
}
76+
}
77+
78+
private boolean isBadName(String name) {
79+
// Your logic comes here
80+
...
81+
}
82+
83+
private String getNewName(String oldName) {
84+
// Your logic comes here
85+
...
86+
}
87+
88+
}
89+
</code></pre>
90+
<p>As you can see, for each visit it is checked whether the selector condition is a ID or class, and
91+
in that case checks for the name (for which you need to provide your own logic).</p>
92+
<p>Your visitor based on the above code is now prepared to perform the task, but first you need to find the
93+
right CSS rules to apply it, for which we will use another visitor. For example, this is an excerpt from Carte's
94+
<a class="codeitem" href="https://sourceforge.net/p/carte/carte/ci/master/tree/carte/src/io/sf/carte/report/SelectorRuleVisitor.java"><code>SelectorRuleVisitor</code></a>:</p>
95+
<pre class="code"><code class="language-java">package io.sf.carte.report;
96+
97+
import io.sf.carte.doc.style.css.CSSStyleRule;
98+
import io.sf.carte.doc.style.css.nsac.SelectorList;
99+
import io.sf.carte.doc.style.css.parser.AttributeConditionVisitor;
100+
import io.sf.carte.util.Visitor;
101+
102+
class SelectorRuleVisitor implements Visitor&lt;CSSStyleRule&gt; {
103+
104+
private final AttributeConditionVisitor visitor;
105+
106+
SelectorRuleVisitor(AttributeConditionVisitor visitor) {
107+
super();
108+
this.visitor = visitor;
109+
}
110+
111+
@Override
112+
public void visit(CSSStyleRule rule) {
113+
SelectorList selist = rule.getSelectorList();
114+
visitor.visit(selist);
115+
rule.setSelectorList(selist); // Refresh serialization
116+
}
117+
118+
}
119+
</code></pre>
120+
<p>Then you can visit the style sheets by using any of the DOM backends that the library provides.
121+
You could gather identifier information from the main document first, then check with the SVG files that you
122+
want to embed. Or you may prefer to apply a systematic approach with the identifiers declared in the SVG files.</p>
123+
<p>Here is an example that visits the sheets contained by an element, it uses css4j's native DOM (adapted from Carte's
124+
<a class="codeitem" href="https://sourceforge.net/p/carte/carte/ci/45750bce9ad0ea75026f96c8f4d9ce2fa9ffed66/tree/carte/src/io/sf/carte/report/DocumentStore.java#l206"><code>DocumentStore</code></a>):</p>
125+
<pre class="code"><code class="language-java">DOMElement svg = ... [the SVG element containing the image]
126+
127+
DupeConditionVisitor dupeVisitor = new DupeConditionVisitor();
128+
Visitor&lt;CSSStyleRule&gt; ruleVisitor = new SelectorRuleVisitor(dupeVisitor);
129+
Iterator&lt;DOMElement&gt; styleIt = svg.getElementsByTagNameNS("*", "style").iterator();
130+
while (styleIt.hasNext()) {
131+
DOMElement style = styleIt.next();
132+
AbstractCSSStyleSheet sheet = (AbstractCSSStyleSheet) ((LinkStyle&lt;?&gt;) style).getSheet();
133+
if (sheet != null) {
134+
sheet.acceptStyleRuleVisitor(ruleVisitor);
135+
style.normalize(); // Write the result to the inner text node
136+
}
137+
}
138+
</code></pre>
139+
<p>And now you only need to serialize the resulting document. (To serialize the native DOM, look at the powerful
140+
<a class="codeitem" href="https://css4j.github.io/api/3/io/sf/carte/doc/dom/DOMWriter.html"><code>DOMWriter</code></a>
141+
or just call <code>toString()</code>).</p>
142+
</div>
143+
</div>
144+
<div class="footnote">
145+
</div>
146+
</div>
147+
</div>
148+
</body></html>

Diff for: ‎index.html

+3
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,9 @@ <h1>CSS4J</h1>
3838
<h2>Documentation</h2>
3939
<ul>
4040
<li><a href="usage.html">CSS4J basic usage.</a></li>
41+
<li><a href="embed-svg.html">Embedding SVG in HTML documents.</a></li>
42+
<li><a href="resolver.html">XML parsing in Java with <code>DefaultEntityResolver</code>.</a></li>
43+
<li><a href="faq.html">The F.A.Q.</a></li>
4144
<li><a href="api/3/">CSS4J non-modular javadocs (3.x).</a></li>
4245
</ul>
4346
<h3>Old javadocs:</h3>

0 commit comments

Comments
 (0)