mirror of
https://codeberg.org/E955corp/atrender.com.git
synced 2026-09-16 20:58:08 +00:00
123 lines
4.0 KiB
HTML
123 lines
4.0 KiB
HTML
<!doctype html>
|
|
|
|
<html lang="en-US">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
|
|
<title>Authoring notes (using @render with JSON)</title>
|
|
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
|
|
|
<style>
|
|
|
|
body {
|
|
max-width: 99ch;
|
|
margin: auto;
|
|
padding: 2em;
|
|
line-height: 1.5em;
|
|
font-family: Helvetica, Arial, sans-serif;
|
|
}
|
|
|
|
h1 {
|
|
margin: 2em 0 1em;
|
|
}
|
|
|
|
h2 {
|
|
margin-top: 2em;
|
|
}
|
|
|
|
pre {
|
|
padding: 1em;
|
|
overflow-x: auto;
|
|
line-height: 1.45;
|
|
background: #F4F4F4;
|
|
}
|
|
|
|
footer {
|
|
margin-top: 4em;
|
|
border-top: 1px solid #AAAAAA;
|
|
}
|
|
|
|
.name {
|
|
font-weight: bold;
|
|
}
|
|
|
|
</style>
|
|
|
|
<link rel="canonical" href="https://atrender.com/notes/1/"/>
|
|
|
|
<meta name="generator" content="me">
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<article>
|
|
|
|
<h1>Authoring notes</h1>
|
|
|
|
<p>Is there anything else to be mindful of with the use of
|
|
<span class="name">@render</span>? Yes. There
|
|
are a few things—</p>
|
|
|
|
<p>To re-iterate the most important: forcing JSON into an HTML parsing context
|
|
means that any text that's not escaped for HTML poses a risk to whether and
|
|
how the loader does its job. In the worst cases, <strong>it could lead to
|
|
cross-site scripting if you act without care. It's important to escape the
|
|
data to prevent this</strong>. A good rule of thumb is to treat any open
|
|
angle bracket in your payload (after the @render line, that is) as an
|
|
oversight that needs immediate correction, regardless of the provenance of the
|
|
data.</p>
|
|
|
|
<p>While consistently escaping <small>U+003C LESS-THAN-SIGN</small> (as
|
|
<code>\u003c</code>) in all other parts of the JSON payload is enough to
|
|
eliminate the cross-site scripting threat, for good measure, you may wish to
|
|
always escape <small>U+0026 AMPERSAND</small> (as <code>\u0026</code>), too,
|
|
since if the input goes through multiple rounds of parsing, then the sequence
|
|
<code>&lt;script</code> can become <code><script</code> if you are
|
|
inconsistent.</p>
|
|
|
|
<p>Secondly, if you don't have enough influence over the server configuration
|
|
to control the Content-Type header (example: you have a static site), then
|
|
you'll probably want to save your data with a .json.html file extension. This
|
|
is also/already more or less required for any files that you intend to share
|
|
that are "unhosted" and expected to be opened straight from the file
|
|
system—it's what will get the correct double-click behavior in most system
|
|
file managers and hint to the browser how you want it to be parsed.</p>
|
|
|
|
<p>Additionally, when your loader runs, be aware that browsers will by default
|
|
put any UI elements that you add to the page into a document in quirks mode
|
|
rather than standards mode. This can affect layout and cause
|
|
hard-to-track-down issues. It's not impossible to address, but your
|
|
application logic does have to be aware of it if you hope to be able get out
|
|
of quirks mode.</p>
|
|
|
|
<p>Lastly, be aware that, although @render heretofore has had no particular
|
|
significance in JSON, we do want to play well with the JSON-LD ecosystem.
|
|
It's anticipated that it will be useful to define semantics for the fragment
|
|
in the script element src attribute. (It may be beneficial for the fragment
|
|
to serve as shorthand for a @type annotation, for example.) For that reason,
|
|
use of the fragment identifier in the script element src attribute should be
|
|
avoided for now until there has been an opportunity work out the exact
|
|
semantics.</p>
|
|
|
|
<p>Remember that wherever feasible, you should probably try to use existing
|
|
standards like JSON Schema and JSON-LD attributes to describe the data, but
|
|
this is not necessary for @render to work.</p>
|
|
|
|
</article>
|
|
|
|
<footer class="colophon">
|
|
<dl>
|
|
<dt>Document identifier</dt>
|
|
<dd><a href="https://atrender.com/notes/1/">https://atrender.com/notes/1/</a></dd>
|
|
<dt>Publication date</dt>
|
|
<dd>2026 September 09</dd>
|
|
<dt>Latest revision</dt>
|
|
<dd><a href="https://atrender.com/notes/">https://atrender.com/notes/</a></dd>
|
|
</dl>
|
|
</footer>
|
|
|
|
</body>
|
|
|
|
</html>
|