https://webtil.es/browser/

1<!doctype html>
2<html lang="en" dir="ltr">
3<head>
4  <meta charset="utf-8">
5  <meta name="viewport" content="width=device-width">
6  <title>AT Tiles Browser</title>
7  <link rel="icon" href="/icon.png">
8  <link rel="stylesheet" href="../browser.css">
9  

9<script src="at.min.js" type="module"></script>

9
10</head>
11<body>
12  <main>
13    <atmos-browser></atmos-browser>
14    <section>
15      <h2>Examples</h2>
16      <p>
17        It's still pretty early days and we're still in the process of making
18        demos. There isn't much yet — but we'll keep adding, and you can add
19        yours too!
20      </p>
21      <ul>
22        <li>
23          <a href="#url=at://did:plc:izttpdp3l6vss5crelt5kcux/ing.dasl.masl/3mceykgxbkk2r">Classic</a>
24        </li>
25        <li>
26          <a href="#url=at://did:plc:izttpdp3l6vss5crelt5kcux/ing.dasl.masl/3mcjwwoqjqs2v">Minesweeper</a>
27        </li>
28        <li>
29          <a href="#url=at://did:plc:izttpdp3l6vss5crelt5kcux/ing.dasl.masl/3meis42djm22d">The Internet Transition</a>
30        </li>
31      </ul>
32    </section>
33    <section id="tutorial">
34      <h2>Tutorial</h2>
35      <p>
36        Tiles are extremely simple to create and deploy, on the assumption that:
37        you have an AT account, you have some very basic knowledge of how to use
38        the command line, and you can build simple web content.
39      </p>
40      <p>
41        Let's just dive in!
42      </p>
43      <section>
44        <h3>Preliminaries</h3>
45        <p>
46          This section covers steps that you'll only need to do once to set yourself
47          up.
48        </p>
49        <p>
50          First, let's install the <code>atile</code> command globally.
51        </p>
52        <pre>
53npm install -g @dasl/tiles</pre>
54        <p>
55          If that runs without error, you can check that you have it:
56        </p>
57        <pre>
58$ atile
59Usage: atile [options] [command]
60
61Manipulating tiles on the AT protocol
62
63Options:
64  -V, --version                  output the version number
65  -h, --help                     display help for command
66
67Commands:
68  login &lt;handle> &lt;appPassword>   log a handle into AT so that you can post
69  logout &lt;handle>                log a specific handle out
70  default-user &lt;handle>          set the default handle to use when unspecified
71  list-users                     list all logged in handles you have
72  publish [options] &lt;dir>        publish a tile to the Atmosphere
73  delete [options] &lt;dirOrATURL>  delete a tile from the Atmosphere
74  help [command]                 display help for command</pre>
75        <p>
76          If you see some output similar to the above, then you're good!
77        </p>
78        <p>
79          The next step is that you need to create an app password. Using Bluesky,
80          you can do it from <a href="https://bsky.app/settings/app-passwords">the
81          relevant settings page</a>.
82        </p>
83        <p>
84          Using your app password, you can now login for the corresponding handle:
85        </p>
86        <pre>
87atile login robin.berjon.com hunter2</pre>
88        <p>
89          That's it! You're all set up to be publishing tiles.
90        </p>
91      </section>
92      <section>
93        <h3>Hello World!</h3>
94        <p>
95          Let's start by making a very very boring tile that has zero frills and
96          just says "Hello World!" First, you want a directory for the tile's
97          content to live in:
98        </p>
99        <pre>
100mkdir hello-tile</pre>
101        <p>
102          Then let's just create an HTML document to say "hello world" with. A tile
103          <em>must</em> have a root path (the path of which is <code>/</code>). The
104          <code>atile</code> command just looks for the classic <code>index.html</code>
105          to use for that, so we'll use that name.
106        </p>
107        <pre>
108echo '&lt;p>Hello World!&lt;/p>' > hello-tile/index.html</pre>
109        <p>
110          The other resource that's required for a tile is a manifest. Because
111          producing a correct tile manifest can be a little bit of work,
112          <code>atile</code> generates almost all of it for you. However, you
113          still need a name for your tile (which is like an app name — tile
114          manifestes are derived from Web App Manifests). There are other things
115          that you can put in a manifest, but let's just start with the minimum.
116        </p>
117        <pre>
118echo '{"name":"The Hello Tile"}' > hello-tile/manifest.json</pre>
119        <p>
120          And that's all the coding we'll need — one line in each of two files — to
121          get something up there. We can now publish it:
122        </p>
123        <pre>
124atile publish -s hello-tile/</pre>
125        <p>
126          The command is simple: it publishes the path to the specified directory. The <code>-s</code>
127          option is used to that <code>atile</code> will keep a mapping from that directory to the
128          specific identifier used for that tile. This means that if you run the command again, it
129          will update the tile on AT instead of creating a new one. (If you don't want to rely on the
130          directory path remaining stable, you can use the <code>-t</code>

130 paramters to specify the TID.)
131        </p>
132        <p>
133          The output should look like the following:
134        </p>
135        <p>
136          <img src="publish-output.png" alt="Terminal output example of the command">
137        </p>
138        <p>
139          If you know go to <a href="https://webtil.es/browser/">open the tile in the tile browser</a>,
140          you will see something like this (except with your avatar):
141        </p>
142        <p>
143          <img src="tile-card-01.png" alt="Tile card in the browser">
144        </p>
145        <p>
146          It's important to understand that tiles can be rendered in multiple ways. Because they
147          have metadata that's published on AT, you can simply use that metadata to render a card
148          (just like link cards), which is useful if you don't want potentially hundreds of active
149          tiles executing at the same time as they appear in a feed. Because we've given very
150          limited metadata, there really isn't much to go on for the card, so you only get its
151          name. If you click on the card, you activate the tile, which triggers the most important
152          rendering move: live tiles. It looks like this:
153        </p>
154        <p>
155          <img src="tile-live-01.png" alt="A live tile that says hello world">
156        </p>
157        <p>
158          This tile isn't doing much but it's a full-fledged web app that's safely executing in a
159          secluded context. All you need to do is to add CSS, JS, etc. and republish!
160        </p>
161      </section>
162      <section>
163        <h3>Refinements</h3>
164        <p>
165          First, let's give it an icon. Because I'm lazy, I'll just copy the
166          <a href="https://webtil.es/icon.png">Web Tiles icon</a> into <code>icon.png</code>
167          at the root of the tile. (It doesn't have to be there or to be called that.)
168          Similarly, I'll use <a href="https://www.flickr.com/photos/robin-berjon/3100614634/in/datetaken-public/">this random picture</a>
169          saved to <code>/banner.jpg</code> (also arbitrary) as the banner for the card.
170        </p>
171        <p>
172          We can then update <code>manifest.json</code> to the following:
173        </p>
174        <pre>
175{
176  "name": "The Hello Tile",
177  "description": "An extremely simple tile that just demonstrates how easy it is to get something published and going.",
178  "icons": [{ "src": "/icon.png" }],
179  "screenshots": [{ "src": "/banner.jpg" }]
180}</pre>
181        <p>
182          Note that both <code>icons</code> and <code>screenshots</code> are plural and take an
183          array. This is for compatibility with
184          <a href="https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest">Web App Manifests</a>
185          (and I expect that tiles implementations will make use of the ability to specify alternatives).
186          Also note that the paths are prefixed with <code>/</code>. That's because all paths in the
187          manifest must be absolute with respect to the root of the tile. When <code>atile</code>
188          generates the complete manifest, it creates a <code>resources</code> entry that maps
189          <code>/icon.png</code> and other files to the <a href="https://dasl.ing/cid.html">CID (Content IDentifier)</a>
190          for that file along with important metadata like its MIME type. The <code>icons</code>'s
191          <code>src</code> must map to that so that it can be found at run time.
192        </p>
193        <p>
194          You can then republish:
195        </p>
196        <pre>
197atile publish -s hello-tile/</pre>
198        <p>
199          That generates a much
200          <a href="https://webtil.es/browser/#url=at://did:plc:izttpdp3l6vss5crelt5kcux/ing.dasl.masl/3meggnybzqs2n">more
201          colourful card</a>:
202        </p>
203        <p>
204          <img src="tile-card-02.png" alt="A tile card with banner, icon, description">
205        </p>
206        <p>
207          Clicking through will produce the same result as before because we haven't
208          updated the code. That part is up to you!
209        </p>
210      </section>
211    </section>
212  </main>
213</body>
214</html>