@@ -117,19 +117,105 @@ Optional properties:
117- `match`: Tag name to match. If you wanted to only match `h2` tags it could be `match="h2"`
117- `match`: Tag name to match. If you wanted to only match `h2` tags it could be `match="h2"`
118- `noHeader`: By default we add a 'Table of Contents' header to the top. Remove it with `noHeader="true"`.
118- `noHeader`: By default we add a 'Table of Contents' header to the top. Remove it with `noHeader="true"`.
120−## Module basics
120+## Implementation
122−A module is a
122+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.
124−## Implementation
124+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.
126+### `manx` to JSON format
128+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.
130+On the Urbit side we actually 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:
133+"string" || {gn:"string", ga:{key:"string", [...]}, c:[...]}
136+To make this clearer let's look at some HTML and it's JSON representation:
145+{gn:"div", ga:{className:"blue"}, [
146+ {gn:"h1", ga:null, "Title"}
150+To see the mechanics of how this is handled on the frontend, checkout `components/Reactify.coffee` in the `urbit/tree` repo.
128### Async component
152### Async component
130−### manx JSON format
154+Each of our components (even those we fetched from the server) can depend on data that may not exist in our stores we wrap our components in a general-purpose Async component. You can find the component in `components/Async.coffee` in the `urbit/tree` repo.
156+When we say that we just fetch HTML as JSON it's actually slightly more complicated. When we fetch a node in the filesystem we might not want to fetch its entire contents. Sometimes we just get the title as a part of a list of children, sometimes we might get a snippet (in a list with previews), and sometimes we get the whole thing. On the Urbit side these results are provided by `ren/tree/json`.
158+From the perspective of the frontend we just send queries on a path that obey a simple API. To see this in action, here's our `BodyComponent`:
170+Here we're asking for the body, name, path, metadata and parent of the current path. When it loads that data gets passed to our component as props.
174+A module is a special component that can kind of 'take over' the page. It can change properties of the nav bar as well as load custom scripts / css.
176+Talk, for example, looks like this:
179+<module nav_title="Talk" nav_no-dpad="" nav_no-sibs="" nav_subnav="talk-station">
180+ <script src="/~~/~/at/lib/js/urb.js" />
181+ <script src="/talk/main.js" />
182+ <link href="/talk/main.css" rel="stylesheet" />
187+A module will first download all the scripts and styles that it specifies before trying to load any contained components. This means that you can define React components in external scripts and a module can be entirely self contained. The `<talk>` component isn't a part of Tree — it's loaded first before it's executed.
189+If you're interested in seeing how a module works you can check out the source for Talk [here](https://github.com/urbit/talk). Dojo also ships on your Urbit, its source is [here](https://github.com/urbit/sole).
132## `urb.js`
191## `urb.js`
193+The most basic interface between your browser and your Urbit is `urb.js`. This small library provides the basic utilities for sending and receiving messages from an Urbit.
195+### `window.urb.appl`
197+Each JSON message sent to your Urbit needs an app endpoint. Can be set as a global `window.urb.appl` or set on a per-request basis in the payload to `send()`.
199+### `window.urb.oryx`
201+CSRF token. Written to the page by `%eyre`, our webserver, when logged in. Required part of any authenticated request and included by default.
203+### `window.urb.req(method,url,params,json,cb)`
205+Our basic request wrapper. You can see here how a request needs to be packaged to be properly understood by your Urbit.
207+### `window.urb.subscribe({path:"string"})`
209+Subscribe to an endpoint. Subscription data is returned through the continuous long poll.
211+### `window.urb.unsubscribe({path:"string"})`
213+Close subscription on specified path.
215+### `window.urb.poll()`
217+Mechanics of the continuous long poll. Used mostly internally.
219+### `window.urb.util`
221+Library of utility and helper functions.