gitoria

5.9 KB

1. # hl:web — the web framework
3. `hl:web` serves an app's pages from the server and keeps them live in the browser. It is written
4. in Hybriel: `WebFramework.hl` is the server half, `client.hl` the browser half, and `compile.hl`
5. turns each component's View into that component's own code. The model behind it (components,
6. Views, realms, the boundary) is in [COMPONENTS.md](../../COMPONENTS.md). This page lists the rules
7. an app is held to. Each rule is a located refusal at boot unless it says otherwise.
9. ## Starting an app
11. ```hybriel
12. import WebFramework from 'hl:web'
13. import Home from './components/home.hl'
14. import Styles from './styles.hl'
16. routes = [ { pattern = "/" component = Home } ]
17. server = new WebFramework(routes = routes, styles = Styles, port = 8080)
18. ```
20. Settings may be passed as named arguments. Most of them may instead be members of the file that
21. runs the `new`:
23. | setting | default | meaning |
24. |---|---|---|
25. | `routes` | `[]` | the route table (below); pass it as an argument |
26. | `styles` | none | the app's styles file: the imported class, or a path string. It must be in the project graph |
27. | `port` | 8080 | the port to listen on |
28. | `host` | `HL_HOST`/`HOST`, else 0.0.0.0 | the interface to bind |
29. | `audience` | `{}` | per outward event, who receives it (see Events) |
30. | `minify` | false | one-line HTML and compact modules |
31. | `watchMode` | true | a saved `.hl` file re-analyses the app and reloads every open tab |
32. | `sessionDir` | `<app>/.sessions` | where sessions are stored; `false` keeps them in memory |
33. | `sessionMaxAge`, `sessionIdle`, `sweepInterval` | 14 days, 15 min, 5 min | the session clocks, in seconds |
34. | `sessionCookie` | `hlsid` | the cookie's name: letters, digits, `-` and `_` |
35. | `sessionSecure` | false | set the cookie's `Secure` flag (for an app behind https) |
36. | `appTitle`, `appDescription`, `appImage`, `appFavicon`, `meta` | none | the head every page gets unless it declares its own |
38. An app runs on one web framework. If its files reach two packages that hold a `WebFramework.hl`
39. (for example an old vendored copy beside this one), it is refused at boot, naming the import row
40. of each.
42. ## Routes
44. Each entry has a `pattern` (`/posts/:id`, `/assets/*`) and one kind:
46. | kind | answers with |
47. |---|---|
48. | `component = Home` or `"./components/home.hl"` | the page, rendered on the server; the component must be imported by the app, and must declare a View |
49. | `function = (route, req) => { … }` | what the function returns (a Hybrid becomes JSON); `req.session` is the cookie's session, or null |
50. | `direct = "text"` | that text |
51. | `file = "./x"` | one file |
52. | `directory = "./assets"` | the files under a directory |
54. A named group (`:id`) reaches the component as a construction argument of the same name: declare
55. `id = null` at its root. A named wildcard does the same with the rest of the path:
56. `/code/*path` gives `path = 'src/lib/util.hl'` for `/code/src/lib/util.hl`, on the first load and
57. on a navigation. A bare `*` has no name a member could take; it is what a `directory` route
58. serves from.
60. ## Components
62. A component is a `.hl` file with a `View`. Its root members are its state, and are constructed on
63. the server for each request.
65. **A View attribute is a literal, a member or a field path.** `href = "/"`, `href = url` and
66. `href = p.url` are allowed. `href = '/posts/' + id` is refused at its line: declare
67. `postUrl = '/posts/' + id` at the file's root and write `href = postUrl`. The same holds for a
68. value bound on a component reference (`Card { title = t }`) and for the condition of an `if` in a
69. View, which may also be a `for` row variable.
71. **The tree carries the elements the HTML parser implies.** `table { tr { td { … } } }` is rendered
72. as `table > tbody > tr > td`, because that is the tree the browser builds from the HTML, and the
73. page is continued from the tree the browser built. The pairs are listed in `view.hl`
74. (`impliedElements`): `tr`, `td` and `th` under `table` get a `tbody`, `td` and `th` under `tbody`,
75. `thead` or `tfoot` get a `tr`, and `col` gets a `colgroup`. Consecutive children that need the same
76. container share one.
78. The other rules:
79. - A View reads only names the file declares. A name it declares nowhere is refused.
80. - `parent './main.hl'` wraps a page in a shell. The shell declares `slot = null` and places
81. `slot` in its View exactly once. A component that is filled (`Card { p { … } }`) must declare a
82. slot too.
83. - `body { … }` is allowed only as the root of a View, and a page wrapped by a parent cannot have
84. one: the shell owns the body.
85. - A View cannot render itself, directly or through other components.
86. - A Style rule cannot be written on a component reference. Write it on an element inside that
87. component.
88. - A page's head comes from its members `__title`, `__description`, `__image`, `__favicon` and
89. `__meta`, and falls back to the app's `appTitle`, `appDescription`, `appImage`, `appFavicon` and
90. `meta`. A handler that writes one of them updates the document.
92. ## Events
94. `on name(…)` handlers and `emit` statements cross between the browser and the server over a
95. WebSocket on the app's own port. `POST /__hl/emit` is the fallback for a peer without a socket.
96. A handler that takes `session` as its last parameter gets the connection's session from the
97. server, never from the peer.
99. An outward event reaches the tab that caused it. To send it to other connections, give it an
100. `audience` entry: a function of the event's arguments and the receiving connection's session that
101. answers true or false.
103. A value-form emit (`answer = emit server ask()`) waits for one answer, so it has one answerer.
104. If two files in the target realm answer the event, it is refused.
106. ## What it serves
108. | url | what |
109. |---|---|
110. | `/<file key>` (e.g. `/components/home.hl`) | a component's browser module |
111. | `/__hl/hl-runtime.js` | the runtime every module imports |
112. | `/__hl/web/client.js` | this package's browser half (other packages' halves are at `/__hl/<name>/client.js`) |
113. | `/__hl/app.css` | the one stylesheet, built from the styles file and every component's `Style` |
114. | `/__hl/emit` | the POST fallback for emits |