dasl.ing/tp-data.html at main · darobin/dasl.ing · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
<!DOCTYPE html><html lang="en"><head>

<!--

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!   GENERATED SPEC — DO NOT EDIT. Look for the .src.html instead   !!!!
!!!!!                                                                  !!!!
!!!!!   HEY YOU                                                        !!!!
!!!!!   YES ***YOU****!                                                !!!!
!!!!!                                                                  !!!!
!!!!!   You're about to edit a generated document.                     !!!!
!!!!!   Don't do that! Why would you do that.                          !!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

-->


    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">

    <title>Tiles Protocol: Data Passing</title>
  <link rel="stylesheet" href="spec.css"><link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><rect x=%220%22 y=%220%22 width=%22100%22 height=%22100%22 fill=%22%2300ff75%22></rect></svg>"><link rel="alternate" type="text/markdown" href="https://dasl.ing/tp-data.md"><meta name="twitter:card" content="summary_large_image"><meta name="twitter:title" property="og:title" content="DASL: Tiles Protocol: Data Passing"><meta name="twitter:description" property="og:description" content="Passsing data to and from tiles is key to integrating tiles in arbitrary         environments. This protocol specifies precisely that."><meta name="twitter:image" property="og:image" content="https://dasl.ing/tp-data.png"><meta name="twitter:image:alt" content="Very colourful stripes, so colourful it hurts"><meta name="twitter:url" property="og:url" content="https://dasl.ing/"><meta property="og:site_name" content="DASL"><meta property="og:locale" content="en"><meta name="theme-color" content="#00ff75"></head>
  <body><div class="nav-back">A specification of the <a href="/">DASL Project</a>.</div><main><header><h1>Tiles Protocol: Data Passing</h1><table><tbody><tr><th>date</th><td>2026-08-06</td></tr><tr><th>editors</th><td><a href="https://berjon.com/">Robin Berjon</a> &lt;<a href="mailto:robin@berjon.com">robin@berjon.com</a>&gt;</td></tr><tr><th>issues</th><td><a href="https://github.com/darobin/dasl.ing/issues">list</a>, <a href="https://github.com/darobin/dasl.ing/issues/new">new</a></td></tr><tr><th>abstract</th><td><div id="abstract">
      <p>
        Passsing data to and from tiles is key to integrating tiles in arbitrary
        environments. This protocol specifies precisely that.
      </p>
    </div></td></tr></tbody></table></header>

    <section>
      <h2>Introduction</h2>
      <p>
        Since tiles are cut off from the network, they cannot load data for
        themselves or post it to servers. This protocol enables a tile and its
        hots environment to exchange data so that the tile may process or render
        it and so that it can hand results back to its host.
      </p>
    </section>
    <section>
      <h2>Data Loading Protocol</h2>
      <p>
        The data protocol is loaded from <code>/.well-known/web-tiles/data.js</code>.
        The interface exported from that has the following functions:
      </p>
      <ul>
        <li>
          <code>addDataHandler(handler)</code>: sets function <code>handler</code>
          up to receive data sent by the host. The data is provided to the function
          as an object that is the structured clone of whatever the host sent.
        </li>
        <li>
          <code>removeDataHandler(handler)</code>: removes function <code>handler</code>
          from the list of functions that can receive data payloads from the host.
        </li>
        <li>
          <code>listen()</code>: tells the host that the tile is all set up and
          ready to start receiving data. This is necessary in some environments
          in which the host may not easily know that a tile has loaded. Always
          call it when ready.
        </li>
        <li>
          <code>sendData(payload)</code>: sends data back to the host, with
          <code>payload</code> being structured-cloned on the way there.
        </li>
      </ul>
      <p>
        A simple example:
      </p>
      <pre><code data-highlighted="yes" class="hljs language-javascript"><span class="hljs-keyword">try</span> {
  <span class="hljs-keyword">const</span> { listen, addDataHandler, sendData } = <span class="hljs-keyword">await</span> <span class="hljs-keyword">import</span>(<span class="hljs-string">'/.well-known/web-tiles/data.js'</span>);
  <span class="hljs-title function_">addDataHandler</span>(<span class="hljs-function">(<span class="hljs-params">payload</span>) =&gt;</span> {
    <span class="hljs-title function_">alert</span>(<span class="hljs-string">`Hello <span class="hljs-subst">${payload.name}</span>!`</span>);
    <span class="hljs-title function_">sendData</span>({ <span class="hljs-attr">response</span>: <span class="hljs-string">'How do you do?'</span> });
  });
  <span class="hljs-title function_">listen</span>();
}
<span class="hljs-keyword">catch</span> (err) {
  <span class="hljs-title function_">alert</span>(<span class="hljs-string">"Sorry, this tile can't receive data."</span>);
}
      </code></pre>
    </section>
    <section>
      <h2>Web Runtime Context Notes</h2>
      <p>
        Tiles may be embedded in all kinds of contexts, and those may determine
        the exact way in which the <code>/.well-known/web-tiles/data.js</code>
        resource is implemented. This section only gives guidance for web runtimes
        as they are likely to mostly work in similar ways.
      </p>
      <p>
        In web runtime contexts, the integration works in the following way:
      </p>
      <ul>
        <li>
          The tile signals that it's ready to engage with data (<code>listen()</code>) by
          sending a message with <code>action</code> set to <code>tiles-protocol-up-data-ready</code>
          and no <code>payload</code>.
        </li>
        <li>
          The tile receives data (handlers are called) by receiving a message with
          <code>action</code> set to <code>tiles-protocol-down-data-payload</code>
          and <code>payload</code> set to the content that the handler receives.
        </li>
        <li>
          The tile sends data (<code>sendData()</code>) by sending a message with
          <code>action</code> set to <code>tiles-protocol-up-data-payload</code>
          and <code>payload</code> set to the content being sent.
        </li>
      </ul>
    </section>


</main></body></html>