This is the browser client library for Treetop enabled web servers. See Treetop Library for more details.
This library defines a window.treetop API instance. See API Docs for more details
A Treetop request can be triggered from a script like so,
treetop.request(
"POST",
"/example",
"a=123&b=987",
"application/x-www-form-urlencoded",
[["X-Custom-Header", "header_value"]]
)
The treetop.js script is old school, it is intended to be self-contained, portable
and work without tooling. You can use the file directly if you wish.
Releases are published to npm treetop-client if you are using NPM as your frontend dependency manager.
$ npm install treetop-client
Ultimately the treetop.js script must be sourced by the web browser.
Note that the browser footprint is kept to a minimum. Some form of
initiation is required before the library will add any browser bindings beyond
assigning window.treetop.
To make use of custom integration hooks or the built-in components, the client
must have configuration assigned before any treetop.request(...) calls are made.
Initialization can be triggered actively using treetop.init({...}) or passively by
declaring a global variable window.TREETOP_CONFIG before the client script loads.
The config object is identical in both cases.
<script>
window.TREETOP_CONFIG = {
treetopAttr: true,
mountAttrs: {
"my-attr": (el) => { /*...*/ },
},
unmountAttrs: {
"my-attr": (el) => { /*...*/ },
},
merge: {
"my-custom-merge": (next, prev) => { /*...*/ }
},
onNetworkError: (xhr) => { /*...*/ },
onUnsupported: (xhr) => { /*...*/ }
};
</script>
<script src="treetop.js" async></script>
Once the configuration is set it cannot be modified.
When an element has been added or removed from the DOM by the Treetop library, the node hierarchy is scanned for elements matching the configured mount/unmount functions.
mountAttrs: match attribute name after being attachedunmountAttrs: match attribute name after removal
Custom JS components should use these to configure integration hooks.
Some build-in components are available when treetop is initialized. Built-in components can be enabled or disabled in the config.
Properties supported by Treetop config allow control of build-in components.
| Config Flag | Type | Default | Component |
|---|---|---|---|
| treetopAttr | boolean |
true |
Enable the "treetop" attribute |
| treetopLinkAttr | boolean |
true |
Enable the "treetop-link" attribute |
| treetopSubmitterAttr | boolean |
true |
Enable the "treetop-submitter" attribute |
The treetop attribute component overrides any HTMLAnchorElement or HTMLFormElement node it is attached to. Activating "href" or "action" behavior on those elements will trigger a Treetop XHR request instead of browser navigation.
<a treetop href="/some/path">treetop link</a>
A click event on this anchor will result in the following Treetop request via the client library.
treetop.request("GET", "/some/path")
Here is an example with a form tag:
<form treetop action="/some/path" method="POST">
<input name="foo" value="bar" type="text"/>
<input type="submit"/>
</form>
Submit event here will result in the following library call,
treetop.request("POST", "/some/path", "foo=bar", "application/x-www-form-urlencoded")
The treetop-link attribute component will trigger a treetop GET request when an element is clicked.
This is a useful alternative to the treetop attribute when you wish to avoid the semantics of the href anchor tag.
For example,
<ANY treetop-link="/some/path/">...</ANY>
This is similar to the following,
<ANY >...</ANY>
The treetop-submitter triggers a treetop submit on a target form element with the attached element as the designated submitter. The following 'submitter' attributes are supported:
- form - specify the form to be submitted by node ID (not necessary if the submitter is enclosed)
- formmethod - override the method of the target form
- formaction - override the action of the target form
- formenctype - override the enctype of the target form
- formnovalidate - override client-side validation when submitting form
If a field name and value are specified on the submitter element, that will be included in the form data.
For example,
<form>
<button treetop-submitter formaction="my-action" name="which" value="my-button">My Submit</button>
</form>
This is similar to the following,
treetop.request("GET", "my-action?which=my_button")
When a new fragment is matched to an existing DOM node the default behavior is to replace one with the other, then mount and unmount synchronously. It is possible however, to define a custom 'merge' function which merges the two elements in some way, for example...
treetop.init({
...
"merge": {
"append-children": (next, prev) => {
Array.from(next.children).forEach((child) => {
treetop.mountChild(child, prev);
})
}
}
})
This custom merge implementation will be triggered if both new and old elements have matching treetop-merge attributes. Like so,
<!-- old -->
<ul id="list" treetop-merge="append-children"><li...
<!-- new -->
<ul id="list" treetop-merge="append-children"><li...
When the client library is used to make an XHR request, events will be dispatched to indicate overall loading status. Note that, by design, the context of specific requests cannot be accessed this way.
This event is dispatched when an XHR request is initiated. It will only execute once for concurrent requests.
This event is dispatched when all active XHR requests are completed.
document.addEventListener("treetopstart", function () {
document.body.classList.add("loading");
});
document.addEventListener("treetopcomplete", function () {
document.body.classList.remove("loading");
});
Backwards compatibility is a priority for the client library. It has been designed to rely on long-supported APIs where possible. However, if broad browser support is important to you, the following modern browser features require a ployfill:
history.pushState, so that the location can be updated following partial navigation.history.replaceState, to support Treetop 'X-Response-History' header, fallback to pushState.FormData, required for multipart form data to be encoded for XHR.HTMLTemplateElement, for reliable decoding of HTML strings.- Suggested polyfill library https://github.com/webcomponents/template
The Treetop client library will abort loading and throw an error if these features are not available.
TODO: More browser testing is needed, please help!