mirror of
https://codeberg.org/E955corp/atrender.com.git
synced 2026-09-16 20:58:08 +00:00
191 lines
5.6 KiB
HTML
191 lines
5.6 KiB
HTML
<!doctype html>
|
|
|
|
<html lang="en-US">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
|
|
<title>About @render for 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;
|
|
}
|
|
|
|
iframe {
|
|
width: 100%;
|
|
height: 24em;
|
|
margin: 2em 0 1em;
|
|
border: 4px solid #676767;
|
|
}
|
|
|
|
footer {
|
|
margin-top: 4em;
|
|
border-top: 1px solid #AAAAAA;
|
|
}
|
|
|
|
</style>
|
|
|
|
<link rel="canonical" href="https://atrender.com/1/"/>
|
|
|
|
<meta name="generator" content="me">
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<header>
|
|
|
|
<h1>About @render for JSON</h1>
|
|
|
|
<p>
|
|
You can use @render in your JSON to provide rich controls to help with
|
|
viewing, filtering, and editing what would otherwise be inert data.
|
|
</p>
|
|
|
|
<p>
|
|
The @render trick depends on well-defined behavior implemented by all
|
|
browsers.
|
|
</p>
|
|
|
|
<p>
|
|
Read on to understand @render and how it works.
|
|
</p>
|
|
</header>
|
|
|
|
<article>
|
|
|
|
<h2 id="1-what-does-it-look-like">1. What does @render look
|
|
like?</h2>
|
|
|
|
<p>In a text editor, it looks like an @render attribute annotating
|
|
your JSON. This references your desired loader to bootstrap the UI builder
|
|
(or "hydration" logic) for working with the JSON data. For example:
|
|
|
|
<pre>
|
|
|
|
{
|
|
"@render": "<script src='https://cdn.example/watchlib.js'></script>",
|
|
"name": "Alice's watchlist",
|
|
"url": "https://alice.example.net/movies",
|
|
"already_watched": [
|
|
{
|
|
"title": "The Iron Giant", "id": "[wikidata:Q867283]",
|
|
"score": ":thumbsup:"
|
|
},
|
|
{
|
|
"title": "Under the Skin", "id": "[wikidata:Q4366287]",
|
|
"score": ":thumbsdown:"
|
|
},
|
|
/* ... */
|
|
</pre>
|
|
|
|
<p>In a browser, it looks however you want it to look—subject to what your
|
|
@render loader chooses to build and put on the screen.
|
|
|
|
<p>Here's a live example of Alice's watchlist data, showing how the
|
|
post-render data looks in the browser:</p>
|
|
|
|
<iframe src="./demo/watchlist.json.html"></iframe>
|
|
|
|
<p>(You can also follow a <a href="./demo/watchlist.json.html">direct link to
|
|
the JSON payload</a> to see it outside the iframe shown here.)</p>
|
|
|
|
|
|
<h2 id="2-how-does-it-work">2. How does it work?</h2>
|
|
|
|
<p>To a JSON parser, @render is just an ordinary property whose value is a string
|
|
(albeit one that we know happens to look like HTML).
|
|
|
|
<p>To an HTML parser, your JSON just looks like a bunch of text surrounding a
|
|
bit of markup describing a lone script element near the beginning of the file
|
|
(in the body rather than the head, but that's no big deal).
|
|
|
|
<p>The trick is to convince browsers to treat the JSON as HTML, whether by
|
|
sending an HTML media type from the server, or by using an HTML file extension
|
|
(instead of .json) for local files opened from your computer.
|
|
|
|
<p>In an HTML parsing context, the browser sees the markup for your loader
|
|
script and then loads and executes the script source. The script, if
|
|
self-aware enough, can read out the JSON data and then attach purpose-built,
|
|
in-browser controls for viewing, editing, and otherwise working with the
|
|
specific type of data contained within the JSON payload (or other data that it
|
|
references, or anything else that you want to put on the screen).
|
|
|
|
|
|
<h2 id="3-why-would-you-want-this">3. Why would you want this?</h2>
|
|
|
|
<p>JSON is an acceptable format for authoring and data exchange, but sometimes
|
|
big blobs of JSON can get unwieldy. Not all user agents have perfect (or your
|
|
preferred) JSON viewing tools, and even browsers that have tools for
|
|
dealing with JSON can't have application-specific affordances for all the
|
|
different shapes of JSON they might be absked to show.
|
|
|
|
<p>The @render trick lets you put your data on the screen in the way that you
|
|
prefer to show it while remaining valid JSON.
|
|
|
|
<p>And of course, the latitude that this gives you means you can use @render
|
|
to make the actual editing experience for JSON-based formats nicer, too.
|
|
|
|
|
|
<h2 id="4-the-app-could-just-do-that-though">4. Shouldn't the apps we're
|
|
building already provide those editing affordances?</h2>
|
|
|
|
<p>Maybe. Using @render can be useful for providing a lower-level interface to
|
|
the data encoded in the file that ordinary users might not be interested in
|
|
(or ever even see).
|
|
|
|
|
|
<h2 id="5-what-else">5. What else?</h2>
|
|
|
|
<p>There are some caveats.</p>
|
|
|
|
<p>In addition to getting it to load in a parsing context that's expecting
|
|
markup, you'll need to make sure to properly escape your JSON content for
|
|
HTML. Doing this successfully isn't super-complicated. It's enough to escape
|
|
all occurrences of <small>U+0026 AMPERSAND</small> and <small>U+003C LESS-THAN
|
|
SIGN</small> using the Unicode escape sequence notation for string literals in
|
|
JSON, i.e., <code>\u0026</code> and \<code>u003c,</code> respectively.</p>
|
|
|
|
<p>There are additional <a title="Authoring notes (using @render with JSON)"
|
|
href="/notes/">authoring notes and tips relevant to @render</a> collected on
|
|
a separate page.</p>
|
|
|
|
|
|
</article>
|
|
|
|
<footer class="colophon">
|
|
<dl>
|
|
<dt>Document identifier</dt>
|
|
<dd><a href="https://atrender.com/1/">https://atrender.com/1/</a></dd>
|
|
<dt>Publication date</dt>
|
|
<dd>2026 September 09</dd>
|
|
<dt>Latest revision</dt>
|
|
<dd><a href="https://atrender.com/latest/">https://atrender.com/latest/</a></dd>
|
|
</dl>
|
|
</footer>
|
|
|
|
</body>
|
|
|
|
</html>
|