6Sail is Hoon markup that’s used to render a web page with XML. But what makes
7it special is that you can run arbitrary Hoon code within such a web page
8without using a separate markup language. In this tutorial, we will
9be dealing with Sail as it renders to HTML, a subset of XML.
13Before starting, make sure that your urbit is
14[mounted to Unix](https://urbit.org/docs/using/setup/)
16To host that output, your ship also has a web-server, called
17[Eyre](https://urbit.org/docs/using/web/), that can be found at
18`http://localhost:8080/` if it’s your first ship that’s running on the a
19machine, `http://localhost:8081/` if it’s the second ship on that same machine,
20and so on. In the startup messages, a ship will tell you which HTTP port it's
23The `/web` directory of the `%home` desk is served by default. You can change
24which desk you're serving by using the command `|serve` in the Dojo. If you
25have already created and mounted a desk named `%sandbox`, for example, you can
26switch to serving it with this command:
32The first time you serve a desk, `/web` will be included as default. After that,
33you will need to explicitly append `/web` to the desk you're switching to --
34otherwise, you'll need to write `http://localhost:8080/web` every time you
35navigate to your web-server. Newly served desks not automatically having `/web`
36as their root directory is a bug.
38To switch back to your `%home` desk and set `/web` as your root directory, run:
44We'll be serving the `%home` desk for the examples in this tutorial.
48That server has access to source files located in `/<your-urbit>/home/web` and
49any sub-folders thereof. For the purposes of this tutorial, we will only be
50using files that are located in the `/<your-urbit>/home/web/pages` path.
52There is an important distinction between these two paths. According to
53`/ren/urb.hoon`, any file inside of `/web` or any of its sub-directories
54is put through a tree of renderers specified at `/ren/urb/tree.hoon`
55-- _except_ for files inside of `/web/pages`. All of the files in `/web` and
56its non-`/pages` children directories have various operations on files, such as
57wrapping your Sail the `html`, `head`, and `body` nodes. This rendering tool,
58called simply *Tree*, also adds certain formatting polish, such as a sidebar
59that lists sibling files in the same directory.
61The `/web/pages` sub-directory is a unique case with its own rendering rules.
62The Tree is not used when rendering files in this path. The existence of no tag
63is inferred, and no special formatting is applied. Such simplicity is ideal for
64introducing the basics of Sail. Any source file located in `/web/pages` must
65produce a complete HTML node with "head" and "body" nodes as children.
67Understanding the details of the rendering pipeline is not necessary to complete
68this tutorial. But, if you are curious, you might find it illuminating to
69explore the contents of the `/ren` directory.
71So, if a Sail source file named `sailtest.hoon` is saved in your `/web/pages`
72folder on your only running urbit process, you can view that source rendered
73into a web-page at `localhost:8080/pages/sailtest/`.
77It’s easy to see how Sail can directly translate to HTML:
84 ;title: My first webpage
91 ;script@"http://unsafely.tracking.you/cookiemonster.js";
101 <title>My first webpage</title>
108 <script src="http://unsafely.tracking.you/cookiemonster.js"></script>
113Save the above Sail code in `/home/web/pages/firstsail.hoon`, and the above
114HTML code in `/home/web/pages/firsth.html`. Access the resulting pages by
115navigating to `http://localhost:8080/pages/firstsail` and
116`http://localhost:8080/pages/firsth.html`, respectively, in your browser. The
117resulting pages should be identical!
119It shouldn't be hard to see the similarities here. So let's go into more
120detail about what the differences are.
124In Sail, tag heads are written with the tag name prepended by `;`. Unlike in
125HTML, there are different ways on closing tags, depending on the needs of the
126tag. One of the nice things about Hoon is that you don’t have to be constantly
127closing expressions; Sail inherits this convenience.
131Empty tags are closed with a `;` following the tag. Example:
145Filled tags are closed via line-break. To fill text inside, add `:` after the
146tag name, then insert your plain text following a space. Example:
160To nest tags, simply create a new line. Nested tags need to be closed
161with `==`, because they expect a list of sub-tags. If we nest a line of plain
162text with no tag, a `<p>` is prepended.
164Sail, like Hoon, is white-space sensitive. Unlike in Hoon, however, two spaces
165(called a "gap") is not necessarily equivalent to a line-break in Sail.
170 This is some good content.
179 <p>This is some good content.</p>
184Conversely, if we want to write a string with no tag at all, then we can prepend
185those untagged lines with `;`.
208Attributes are key-value pairs that go into an HTML node.
210Adding attributes is simple: just add the desired attribute between parentheses,
211right after the tag name without a space. We separate different attributes of
212the same node by using `,`.
214Attributes can be used in two forms: flat, which uses one line; and tall, which
215uses multiple lines, when a single line would not be practical. Flat forms and
216flat forms are two syntaxes of semantically equivalent expressions.
221The code below produces a “Submit” button on the page.
226;input(type "submit", value "Submit");
241<input type="submit" value="Submit">`
253<nav id="header">Menu</nav>
256Add `#` after tag name to add an ID.
260`;h1.text-blue: Title` equals `<h1 class="text-blue">Title</h1>`
262Add `.` after tag name to add a class. However, if you want a class name that
263contains a space, you will need to use use the syntax of a generic attribute:
265`;div(class "logo inverse");` equals `<div class="logo inverse"></div>`
274`<img src="example.png"/>`
276Add `@` after the tag name to link your source.
278To add attributes to the image, like size specifications, add the
279desired attribute after the `"` of the image name and before the final `;` of
284`;img@"https://urbit.org/example.png"(width "100%");`
288`;a/"urbit.org": A link to Urbit.org`
292`<a href="urbit.org">A link to Urbit.org</a>`
294Add `/` after tag name to start an href.
298Our first example is useful to understand how Sail syntax translates to HTML
299syntax, but Sail finds its usefulness in the fact that it can be used seamlessly
302One place where Sail diverges from HTML is that it supports string
303interpolation. In Sail, the contents of all tags are a string type called `tape`
304unless otherwise designated. Tapes are delineated by the double quotes `""`.
305That’s important, because tapes can be interpolated with Hoon expressions,
306provided that those expressions produce something a tape as well. Interpolation
307is done by wrapping the code to be inserted in `{}`. In your Dojo prompt, try
308the command below (without the `>`):
311> "I am a l{(mul 3 11)}t Urbit user."
315Oh no! That command produced a nest-fail error, which indicates that there was
316a problem related to Hoon type-system. We used the proper `{}` syntax for
317interpolation, and we used the proper function-call syntax inside of it. So
320Trying the `mul` function on its own will help answer this question. Try the
321following command in your Dojo:
328This should work, producing `33`, an atom. That’s our problem. The
329interpolation expression expects a tape, but our first command tried to
330interpolate with something that results in an atom. Try this now:
337We get a similar result, but we know that it’s a tape because it’s wrapped in
338`""`. Bingo! With this knowledge, let’s perform a successful interpolation:
341> "I am a l{<(mul 3 11)>}t Urbit user."
342"I am a l33t Urbit user."
349The default subject of a Sail file is different from the subject that
350expressions in the Dojo or a Hoon generator are evaluated against.
352To see this difference, first save the code below to a file at
353`home/web/pages/sub.hoon` and view the rendering at
354`http://localhost:8080/pages/sub`.
365Then enter the following command in the Dojo:
371You'll notice that the Sail subject is like a stripped-down version of the Dojo
372subject. Its final line should match the Dojo subject.
374Now swap the code below into your Sail file.
386You'll find that the resulting Sail subject is much larger. If you look closely,
387you'll see that there's some new similarities with the Dojo subject, such as
388containing the name of your ship. There's also some new differences, since
389`fuel:html` contains things that are specifically useful for performing
390web-related operations.
392### A More Interesting Example
394Now let’s apply knowledge of string interpolation and the Sail subject in a Sail
395source file. The following code produces more interesting things than the
396example we saw before.
401=+ wid=(met 3 p.bem.gas)
403?: (lte wid 1) "galaxy"
405?: (lte wid 4) "planet"
410 ;meta(charset "utf-8");
411 ;title: A more advanced page
414 ;h1: This is the Title
416 ;a/"http://urbit.org": link to Urbit.org.
420 ;li(style "color: green"): We're doing interesting stuff now.
421 ;li: We're pretty-printing this sum with Hoon: {<(add 50 50)>}.
422 ;li: The code above is shorthand for {(scow %ud (add 50 50))}.
423 ;li: I am {(trip '~lodleb-ritrul')}.
424 ;li: Actually, my name is {<p.bem.gas>}. I'm a {what-kind}.
426 ;div: My name is {<p.bem.gas>}. I'm a {what-kind}.
431Save the above Sail code in to `home/web/pages/secondsail.hoon` and access the
432resulting page by navigating to `http://localhost:8080/pages/secondsail` in
435There are some interesting things here. Let’s go through this code piece by
442Later in this code we want produce the name of the ship is hosting it, something
443that looks like ~lodleb-ritrul. In a generator, we could produce our ship name
444by writing `our` -- try it in the Dojo. But remember that Sail is rendered
445against its own subject, `our` is not part of the default subject. To augment
446our subject with the information that we need, we use `/= gas /$ fuel:html`.
448The above expression uses two Ford runes, `/=` and `/$`, to add the relevant
449information to the current subject. We can pull the ship’s name out of this
450augmented subject later. It's important to note that these runes are not part of
451Hoon. They are part of Ford, our build system.
453`/$` is used to get data from the environment, and `/=` adds that data to
454subject in the face `gas`. The
455[Ford user manual](https://urbit.org/docs/arvo/internals/ford/runes/) has
456details on these and other Ford runes, but understanding these runes isn’t
457necessary for the purposes of this tutorial.
459`fuel:html` gets extra data from your ship’s Eyre module, which handles all
460things HTTP, and sticks it in the subject when Eyre renders a page. This
461includes the name of the ship, which is what we look for in the next line, but
462it includes much more.
464`p.bem.gas` is an expression that looks for `p` within `bem` within `gas`, the
465face that we stored the above `fuel:html` expression in. That wing happens to
466resolve to the name of the ship that is hosting the web-server. If we wanted to
467access the current desk, we would use the wing expression `q.bem.gas`.
469You can take a look at what you can access by typing `fuel:html` in the Dojo,
470and then explore it by modifying your wing expression in your Sail file
477The above line of code stores a variable used later for a conditional. `&` means
478`true`, meaning that any evaluation of `show-list` will be true until changed in
482=+ wid=(met 3 p.bem.gas)
484 ?: (lte wid 1) "galaxy"
486 ?: (lte wid 4) "planet"
487 ?: (lte wid 8) "moon"
491This code chunk is a series of conditionals that checks the host ship’s name to
492see what its value is.
494The first line, `=+ wid=(met 3 p.bem.gas)`, combines a new noun with the
495subject and gives it the face `wid`. This noun is produced by the the
496standard-library function [`met`](/docs/reference/library/2c), which measures the number of
497[blocks](/docs/reference/library/1c/) of size `a` within `b`. Blocks are units that have a
498bitwidth of `2^a`. So, in this case, it measures how many bytes (blocks of size
4993 are bitwidths of 8; `2^3 = 8`) are fully contained in your ship's address.
501Galaxies contain zero to one 3-blocks; stars contain two 3-blocks; planets
502contain three to four 3-blocks; moons contain five to eight 3-blocks; comets
503contain nine to sixteen 3-blocks. Each test uses `lte`, the
504less-than-or-equal-to function, to determine if `wid` is of a given size. The
505result of this series of tests is added to the subject and given the face
508Ship names are simply another representation of atoms, and ship
509categories are different ranges of possible atomic values. Because of this, we
510perform less-than tests to see what kind of ship is running the web-server.
515 ;meta(charset "utf-8");
516 ;title: A more advanced page
520Sail proper begins here. These four lines are four nodes. The `;html` node
521indicates that the contained code should be rendered as HTML; this tag is closed
522on the final line. The `;head` node contains metadata, and is closed three lines
523later. The `;meta` node sets the character set to UTF-8, and the `;title` node
524sets the title of the page that shows up in the browser tab.
528 ;h1: This is the Title
530 ;a/"http://urbit.org": link to Urbit.org.
534The first line here opens, of course, the body node. The second line creates
537The third, fourth, and fifth lines of code here construct a single line with an
539`; This is a` begins the rendered line with plain text.
541`;a/"http://urbit.org": link to Urbit.org.` continues that same rendered line,
542and creates hyperlinked text out of `link to Urbit.org.`
544`;span: Check it out!` continues that same rendered line further. `;span:`
545has the same use as `<span>` in HTML, and by following it with just a `:` and no
546attributes, it continues the line without formatting. Following `;span:` with
547**two** spaces causes there to be single space following the produced `<span>`
548element, because one of those spaces is syntactically necessary.
550In the following lines, we beginning to use some Hoon expressions again.
557In the top line in the chunk above, we use the `;+` Sail rune, which
558resolves an expression to a single node. That expression, in this case, is
559`?:`, which tests the truth value of `show-list`, which we assigned the value
560`&` (meaning “true”) at the beginning of the program. It’s closed by the `==` on
563Thus, this program resolves to the first child of `show-list`, the node `;ol`.
564That node creates an ordered list, and the items contained within that node.
567 ;li(style "color: green"): We're doing more interesting stuff now.
570The line above is the only element of this list that does not use
571Hoon proper. The line renders as green, as interpreted by the browser,
572because of the Sail attribute.
574The next items in the list use `{}`. Recall that these braces, pronounced “lob”
575and “rob” in Hoon-speak, allow for the interpolation of code within a string.
578 ;li: We're pretty-printing this sum with Hoon: {<(add 50 50)>}.
581The line above is interpolated with Hoon code that produces the sum of 50 plus
58250, which is wrapped in `<>` to put the product in double quotes to make it a
583tape, like the rest of the line.
587 ;li: The code above is shorthand for {(scow %ud (add 50 50))}.
590The `{(scow %ud (add 50 50)}` on this line is just a different way
591writing the `{<(add 50 50)>}` expression. `scow` is a Hoon function that turns a
592noun into a `tape`, Hoon’s string type. `%ud` tells `scow` that its argument
593should be displayed in the form of an unsigned decimal.
597 ;li: I am {(trip '~lodleb-ritrul')}.
600`trip` is a function that takes a `cord` and produces a `tape`. A piece of
601data of the cord type is one big atom formed from adjacent unicode bytes and
602delineated by `''`. Remember that all text rendered in Sail is treated as a
603tape. So, by converting `~lodleb-ritrul` to a tape, it can be included in the
604tape that we are trying to insert it into without getting a type error.
607 ;li: Actually, my name is {<p.bem.gas>}. I'm a {what-kind}.
611The line above has interpolated code that uses a wing expression to access the
612name of the host ship, and then accesses the face `what-kind` contains a string
613describing what type of ship it is. We declared `gas` on the very first line so
614that we could add that sort of information to the subject that our Sail is
615rendered against. The wing expression `p.bem.gas` looks for `p` within `bem`
616within `gas`, which happens to be where the name of the ship is located.
618Note that `{what-kind}` does not have a `<>` wrapper. Why do you think this is?
621 ;div; My name is {<p.bem.gas>}. I'm a {ship}.
626The `;div;` node above is only rendered, as an alternative to the above list,
627if `show-list` is evaluated as true. This means it won’t be shown with your
628default code. To show this line, change the `&` on line 2 to `|` (“false”).
632In the previous example, we used a few special runes that aren’t used in typical
633Hoon code. But there are others that are worth learning about at this point.
635`;+` is an expression that resolves to a single node. We saw this on line 20
636in our Sail example above: `;+ ?: show-list` resolves to the node `;ol` and
637all of that node’s children.
639`;*` is an expression that resolves to a list of nodes. If we want to render
640multiple nodes side-by-side, and not just the children of a single node, this
641is the expression that we use.
643`;=` turns a tuple of nodes into a list of nodes.
646To see how these runes work, let’s take a chunk of our previous code starting at
647line 20 and modify it a bit:
652 ;li: I am {(trip '~lodleb-ritrul')}.
653 ;li: Actually, my name is {<p.bem.gas>}.
656 ;div: My name is {<p.bem.gas>}. I'm a {what-kind}.
662We changed the conditional branches so that each contains two Sail nodes,
663side-by-side -- notice that the `;ol` is absent from the first branch.
665We begin with the `;*` rune, which resolves to a list of nodes, instead of the
666`;+` rune, which only resolves to a single node.
668But that’s not enough on its own. `;*` needs to resolve to a list, and a few
669Sail nodes aren’t lists until they are explicitly made into lists. Until we wrap
670those nodes in `;=`, the nodes treated as mere tuples. All branches must be
671valid lists for the `;* ?: show-list` expression to resolve.
676You should now have foundational knowledge for making web pages with Sail. There
677is, of course, more to learn. If you’re curious, there’s more advanced
679The [Ford manual](https://urbit.org/docs/arvo/internals/ford/runes/)
680can show you how to access various ship resources for user in your pages. To
681learn more about how the renderer works, take a look at the
682`/home/ren/urb.hoon` file inside your urbit.
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list