@@ -1,448 +0,0 @@
1−:- :~ navhome/'/docs/'
2− navuptwo/'true'
3− next/'true'
4− sort/'8'
5− title/'Web (Eyre)'
6− ==
7−;>
8−
9−# Web (Eyre)
10−
11−;div(class "row")
12− ;div(class "col-md-8")
13−
14−Your urbit runs its own webserver, Eyre, that handles all things HTTP. Here
15−we'll cover the features of Eyre that most resemble a traditional web server.
16−
17−By default Eyre uses *Tree*. Tree is a simple ui for browsing the contents of
18−the filesystem, statically publishing a blog or any kind of content and for
19−running single-page apps.
20−
21−Tree was built primarily to display both our documentation and the contents of
22−`urbit.org`. If you're interested in doing anything complex, it's worth
23−checking out the [docs source](https://github.com/urbit/docs) and the
24−[urbit.org](https://github.com/urbit/urbit.org) source.
25−
26−We ship `tree` as compiled JavaScript on your urbit, but the source lives in its
27−own repo [here](https://github.com/urbit/tree).
28−
29− ==
30−==
31−
32−## Quickstart
33−
34−Your urbit runs a web server and can be found locally at
35−`http://localhost:8080/` This is the fastest and easiest way
36−to find your urbit's web server. Note that the port that a given urbit uses
37−might be `8081`, `8082`, or so on if you're running other processes that might
38−be occupying `8080`, such as another urbit. Upon the starting of a ship, it will
39−print a message telling you which port it's using.
40−
41−Your urbit's web server can be accessed remotely at
42−`http://your-urbit.urbit.org/`. You'll need to enter a code to access it in this
43−way, one that is generated by running the `+code` command in the Dojo.
44−
45−_(Make sure you have a desk mounted to unix, as covered in the
46−[setup section](../filesystem/))._
47−
48−##### Serving
49−
50−The `/web` directory of the `%home` desk is served by default. You can change
51−which desk you're serving by using the command `|serve` in the Dojo.
52−
53−Let's create a desk for development called `%sandbox`.
54−
55−Use `|merge` to create the new desk containing the contents of `%home`:
56−
57−```
58−~your-urbit:dojo> |merge %home our %sandbox
59−```
60−
61−And use `|sync` to continuously update based on changes to `%home`:
62−
63−~your-urbit:dojo> |sync %home our %sandbox
64−
65−Now let's mount it to unix so that we can save files to it:
66−
67−```
68−~your-urbit:dojo> |mount /=sandbox=
69−```
70−
71−And now, to switch the desk you're serving from:
72−
73−```
74−~your-planet:dojo> |serve %sandbox
75−```
76−
77−##### Hosting files
78−
79−To host a file on the web, save the following in `/sandbox/web/test.udon` in your
80−ship's pier through unix.
81−
82−```
83−# Hello
84−
85−This is a simple Udon file.
86−```
87−
88−Our Tree system allows for pages to be designated as children of other pages.
89−To do this for any given page, simply make a new folder in the directory that
90−contains the page that will be the parent, and give that directory the same
91−name. So, the children of a page `/home/web/foo.udon` will live in a directory
92−called `/home/web/foo/`.
93−
94−Let's continue our with our `test.udon` example. Create `/sandbox/web/test/` and
95−add two more Udon files in `/sandbox/web/test/daughter.udon`
96−`/sandbox/web/test/son.udon`, respectively. Make sure that they contain valid
97−Udon. Udon is our markup language, similar to Markdown; check out the guide
98−[here](../udon/).
99−
100−> NOTE: Due to a bug in Urbit, you may have to create the directory and the file
101− in it in rapid succession using something like `mkdir sandbox/web/test && touch
102− sandbox/web/test/first.md`.
103−
104−Now modify `/sandbox/web/test.udon` to list the children using `;list;`:
105−
106−```
107−# Hello
108−
109−This is a simple Udon file.
110−
111−;list;
112−```
113−
114−To view your file rendered using tree:
115−
116−```
117−http://localhost:8080/test/
118−```
119−
120−To view your file as raw Udon:
121−
122−```
123−http://localhost:8080/test.udon
124−```
125−
126−To view your file as raw `html`:
127−
128−```
129−http://localhost:8080/test.html
130−```
131−
132−Now navigate to the "daughter" file that you created:
133−
134−```
135−http://localhost:8080/test/daughter.udon
136−```
137−
138−In Urbit, there is no distinction between a directory and a file. So, if you're
139−adding files directly from unix, simply `mkdir test` and Urbit will treat the
140−file and directory as the same entity.
141−
142−You can use this feature to change your homepage at `your-urbit.urbit.org` with
143−the page `/home/web.udon`, where `home` is the current mounted desk. By default,
144−`web.udon` will display some info about your urbit, but you can customize it to
145−your heart's content.
146−
147−
148−## Manual
149−
150−## `/web`
151−
152−This is the equivalent of a `public_html` directory. Your urbit looks in this
153−directory to serve content to the world. You can change what desk you're serving from using `|serve`.
154−
155−Switch to the `%sandbox` desk:
156−
157−```
158−|serve %sandbox
159−```
160−
161−Let's quickly step through the default contents of `web/`:
162−
163−- `404.hoon` - The default 404 page.
164−- `dojo.hoon` - Page body that loads the `dojo` React module.
165−- `lib/css/bootstrap.css` - The Urbit-flavored bootstrap
166−- `lib/css/codemirror.css` - Syntax highlighting
167−- `lib/css/fonts.css` - The Urbit custom fonts
168−- `lib/js/hoon.js` - Hoon syntax highlighting
169−- `lib/js/sole.js` - `dojo` operational transformation JS
170−- `lib/js/urb.js` - Base Urbit JS library. Handles AJAX and polling.
171−- `static.udon` - Sample static file
172−- `talk/` - Talk compiled JS / CSS
173−- `talk.hoon` - Page body that loads the `talk` React module.
174−- `testing.udon` - Guide to writing unit tests in Urbit
175−- `tree/` - Tree compiled JS / CSS
176−- `tree.hoon` - Page body that loads the `tree` React module.
177−- `unmark/` - Used for testing `.udon`.
178−- `womb/` - Womb compiled by JS/CSS
179−- `womb.hoon` - Used for issuing planets on the test network.
180−
181−## Tree
182−
183−Tree is a simple publishing tool for files that live on your urbit. You're
184−probably reading this file using Tree right now. The main driving use-case for
185−Tree has been for us to host our own documentation and the surrounding
186−discussion. Tree remains a pretty simple and flexible tool for getting content
187−online. It resembles a cross between [Jekyll](https://jekyllrb.com/),
188−[Kirby](https://getkirby.com/) and macOS's Finder. We think it's pretty great.
189−
190−Tree is also the basic UI for browsing the filesystem. We take it one step
191−further and make it possible to write modules (tiny little apps), like Talk and
192−Dojo, that can be run directly inside of Tree.
193−
194−In the browser Tree is a [React](https://facebook.github.io/react/) /
195−[Flux](https://facebook.github.io/react/blog/2014/05/06/flux.html) app that uses
196−a slightly modifed version of [Bootstrap](http://getbootstrap.com/). On your
197−Urbit Tree is a renderer that translates data in `%clay`, our filesystem, into
198−JSON / JSX that can be read by the client.
199−
200−Your urbit comes with a pre-built copy of the tree (as a single `.js` file). If
201−you're interested in helping to develop tree or learning about how it works, it
202−has its own GitHub repo [here](https://github.com/urbit/tree). We have our own
203−fork of Bootstrap, which lives [here](https://github.com/urbit/bootstrap).
204−
205−## `/web/pages`
206−
207−To render content without the Tree put it in `/web/pages`. Files in this
208−directory aren't wrapped by Tree.
209−
210−## Publishing files
211−
212−Publishing files in Tree is simple. Try dropping a file in `/web` (as covered
213−in the Quickstart) and navigating to it.
214−
215−The best example of more complicated usage of Tree is covered by the Urbit docs
216−themselves. See anything while perusing the docs that you'd like to use
217−yourself? The docs are all on GitHub [here](https://github.com/urbit/docs).
218−
219−## Frontmatter
220−
221−Most `.udon` files begin with some frontmatter, which determines the title and
222−other settings for rendering the file correctly. E.g.:
223−
224−```
225−:- :~ navhome/'/home/'
226− next/'true'
227− sort/'1'
228− title/'Example Frontmatter Title'
229− ==
230−;>
231−```
232−
233−Here are the fields we support:
234−
235−##### title
236−
237−String. Example: `title/'Tree manual'`.
238−
239−This sets the title in the nav or in lists as distinct from the filename.
240−
241−##### next
242−
243−Boolean. Example: `next/'true'`
244−
245−Adds a 'next' link at the bottom of the page that links to the next item as decided by the sort order.
246−
247−##### sort
248−
249−Integer. Example: `sort/'7'`
250−
251−User-defined sort. Indicates the sort order as distinct from alphabetical sort.
252−These numbers should not be overlapping.
253−
254−##### hide
255−
256−Boolean. Example: `hide/'true'`
257−
258−Whether or not to hide the item from the tree.
259−
260−##### date
261−
262−Urbit date. Example: `date/'~2016.2.22'`
263−
264−Used for sorting posts by date.
265−
266−##### Arbitrary Frontmatter
267−
268−Any arbitrary category can be used as long as it's given data of valid types.
269−Arbitrary categories can be used with the ones mentioned above. Below is
270−valid front matter:
271−
272−```
273−:- :~ date/~2018.9.12
274− author/~lodleb-ritrul
275− music/'rad'
276− ==
277−```
278−
279−## Using components
280−
281−Tree is built using React with a small library of components that you can add to your pages using [JSX](https://facebook.github.io/jsx/) tags.
282−
283−If you don't know anything about JSX that's okay: basically we just give you a few custom HTML tags that you can use to create components on the page.
284−
285−For those familiar with React / Flux each JSX tag corresponds to a component in [the source](https://github.com/urbit/tree/tree/master/js/components).
286−
287−### `<list>`
288−
289−Example: `<list src="/posts" titlesOnly="true" />`
290−
291−Creates a list of children at a path. Defaults to the current path.
292−
293−Optional properties:
294−
295−- `src`: Path to load kids from.
296−- `titlesOnly`: Only show the 'title' which is either the filename or the first h1.
297−- `sortBy`: Can be `date` if items have a `date` YAML.
298−- `className`: Class to be assigned to the container.
299−
300−### `<kids>`
301−
302−Example: `<kids src="/posts" />`
303−
304−Includes all the children at the specified path separated by `<hr>` tags.
305−
306−Optional properties:
307−
308−- `src`: Path to load kids from.
309−- `className`: Class to be assigned to the container.
310−
311−### `<toc>`
312−
313−Example: `<toc noHeader="true" />`
314−
315−Creates a table of contents from the `h1` - `h6` tags on the page.
316−
317−Optional properties:
318−
319−- `match`: Tag name to match. If you wanted to only match `h2` tags it could be `match="h2"`
320−- `noHeader`: By default we add a 'Table of Contents' header to the top. Remove it with `noHeader="true"`.
321−
322−## Implementation
323−
324−On the frontend Tree is mostly just a standard Flux app: components generate actions that get dispatched to stores which are picked up by components. If you're not familiar with Flux, [this overview](https://facebook.github.io/flux/docs/overview.html) is a good place to start.
325−
326−As a file browser Tree does a simple job: it fetches data and keeps a cache of what it has seen. To do this simple job we do three fancy things: `manx` to JSON encoding, the Async component and Modules.
327−
328−### `manx` to JSON format
329−
330−Since we want to use React to manage our DOM lifecycle we actually transfer the DOM structure of each page as JSON over the wire, and 'reactify' it on the client side.
331−
332−On the Urbit side we have a type for html: `++manx`. Our wire format for sending HTML as JSON is really similar to a `++manx`. If you're not interested here's what the json looks like:
333−
334−```
335−"string" || {gn:"string", ga:{key:"string", [...]}, c:[...]}
336−```
337−
338−To make this clearer let's look at some HTML and its JSON representation:
339−
340−```
341−<div class="blue">
342− <h1>Title</h1>
343−</div>
344−```
345−
346−```
347−{gn:"div", ga:{className:"blue"}, [
348− {gn:"h1", ga:null, "Title"}
349−]}
350−```
351−
352−To see the mechanics of how this is handled on the frontend, checkout
353−`components/Reactify.coffee` in the `urbit/tree` repo.
354−
355−### Async component
356−
357−Each of our components (even those we fetched from the server) can depend on
358−data that may not exist in our stores, so we wrap our components in a
359−general-purpose Async component. You can find the component in
360−`components/Async.coffee` in the `urbit/tree` repo.
361−
362−When we say that we just fetch HTML as JSON it's actually slightly more
363−complicated. When we fetch a node in the filesystem we might not want to fetch
364−its entire contents. Sometimes we just get the title as a part of a list of
365−children, sometimes we might get a snippet (in a list with previews), and
366−sometimes we get the whole thing. On the Urbit side these results are provided
367−by `ren/tree/json`.
368−
369−From the perspective of the frontend we just send queries on a path that obey a
370−simple API. To see this in action, here's our `BodyComponent`:
371−
372−```
373−query {
374− body:'r'
375− name:'t'
376− path:'t'
377− meta:'j'
378− sein:'t'
379−}
380−```
381−
382−Here we're asking for the body, name, path, metadata and parent of the current
383−path. When it loads that data gets passed to our component as props.
384−
385−### Module basics
386−
387−A module is a special component that can kind of 'take over' the page. It can
388−change properties of the nav bar as well as load custom scripts / css.
389−
390−Talk, for example, looks like this:
391−
392−```
393−<module nav_title="Talk" nav_no-dpad="" nav_no-sibs="" nav_subnav="talk-station">
394− <script src="/~~/~/at/lib/js/urb.js" />
395− <script src="/talk/main.js" />
396− <link href="/talk/main.css" rel="stylesheet" />
397− <talk />
398−</module>
399−```
400−
401−A module will first download all the scripts and styles that it specifies before
402−trying to load any contained components. This means that you can define React
403−components in external scripts and a module can be entirely self contained.
404−The `<talk>` component isn't a part of Tree — it's loaded first before it's
405−executed.
406−
407−If you're interested in seeing how a module works you can check out the source
408−for Talk [here](https://github.com/urbit/talk). Dojo also ships on your urbit,
409−its source is [here](https://github.com/urbit/sole).
410−
411−## `urb.js`
412−
413−The most basic interface between your browser and your urbit is `urb.js`. This
414−small library provides the basic utilities for sending and receiving messages
415−from an urbit.
416−
417−### `window.urb.appl`
418−
419−Each JSON message sent to your urbit needs an app endpoint. Can be set as a
420−global `window.urb.appl` or set on a per-request basis in the payload to
421−`send()`.
422−
423−### `window.urb.oryx`
424−
425−CSRF token. Written to the page by Eyre, our webserver, when logged in.
426−Required part of any authenticated request and included by default.
427−
428−### `window.urb.req(method,url,params,json,cb)`
429−
430−Our basic request wrapper. You can see here how a request needs to be packaged
431−to be properly understood by your urbit.
432−
433−### `window.urb.subscribe({path:"string"})`
434−
435−Subscribe to an endpoint. Subscription data is returned through the continuous
436−long poll.
437−
438−### `window.urb.unsubscribe({path:"string"})`
439−
440−Close subscription on specified path.
441−
442−### `window.urb.poll()`
443−
444−Mechanics of the continuous long poll. Used mostly internally.
445−
446−### `window.urb.util`
447−
448−Library of utility and helper functions.