Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This adds documentation, under `docs/zones`, for each of the zone plugins. It provides usage examples and signatures.
- Loading branch information
Showing
15 changed files
with
447 additions
and
16 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,29 @@ | ||
Provides a simple DOM interface for applications. [can-simple-dom](https://github.com/canjs/can-simple-dom) doesn't attempt to be fully standards complaint, but rather to provide the basic interfaces that most applications need. If you need a more complaint DOM, use [can-zone-jsdom](https://github.com/canjs/can-zone-jsdom). | ||
|
||
```js | ||
const Zone = require("can-zone"); | ||
const dom = require("done-ssr/zones/can-simple-dom"); | ||
|
||
require("http").createServer(async function(request, response){ | ||
|
||
let zone = new Zone([ | ||
dom(request) | ||
]); | ||
|
||
function app() { | ||
let div = document.createElement("div"); | ||
div.textContent = "Hello world!"; | ||
document.body.appendChild(div); | ||
} | ||
|
||
let {html} = await zone.run(); | ||
response.end(html); | ||
|
||
}).listen(8080); | ||
``` | ||
|
||
# Signature | ||
|
||
## dom(request) | ||
|
||
The *can-simple-dom* zone requests a request object. It uses this to set up a few things, including the `window.location` and `navigator.language`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,27 @@ | ||
The *done-ssr/zones/canjs* zone is used for integration with [canjs](https://canjs.com/) applications, mostly involving `can.route`. | ||
|
||
```js | ||
const Zone = require("can-zone"); | ||
const canjs = require("done-ssr/zones/canjs"); | ||
|
||
require("http").createServer(function(request, response){ | ||
|
||
new Zone([ | ||
canjs(response) | ||
]) | ||
|
||
}).listen(8080); | ||
``` | ||
|
||
This zone provides the following features: | ||
|
||
* [can-globals/location/location](https://canjs.com/doc/can-globals/location/location.html) will be set to the correct location throughout the zone's lifetime. | ||
* [can-globals/document/document](https://canjs.com/doc/can-globals/document/document.html) will be set to the correct location throughout the zone's lifetime. | ||
* can-route's [route.data](https://canjs.com/doc/can-route.data.html) property will be set throughout the zone's lifetime (this allows multiple requests to be processed at the same time). | ||
* Additionally, if the *route.data* property contains a __statusCode__ value, that value will be set on the `response.statusCode`. | ||
|
||
# Signature | ||
|
||
## canjs(response) | ||
|
||
In order to set the status code, this zone needs the http(s) *response* object. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
The *done-ssr/zones/cookies* zone will set the `document.cookie` property. It must be used after a DOM zone. | ||
|
||
```js | ||
const Zone = require("can-zone"); | ||
const dom = require("done-ssr/zones/can-simple-dom"); | ||
const cookies = require("done-ssr/zones/cookies"); | ||
|
||
require("http").createServer(function(request, response){ | ||
|
||
new Zone([ | ||
dom(request), | ||
|
||
cookies(request, response) | ||
]) | ||
|
||
}).listen(8080); | ||
``` | ||
|
||
The cookies zone will extract the cookies from the request and place them on the `document.cookie`, and then later on the `response.cookie`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,38 @@ | ||
The *done-ssr/zones/debug* zone is used to debug applications when they timeout. This zone expects either a *can-zone/timeout* zone, or a Number of milliseconds before timing out (in which case it will create a *can-zone/timeout* itself). | ||
|
||
```js | ||
const Zone = require("can-zone"); | ||
const debug = require("done-ssr/zones/debug"); | ||
|
||
require("http").createServer(function(request, response){ | ||
new Zone([ | ||
debug(5000); | ||
]); | ||
}).listen(8080); | ||
``` | ||
|
||
# Signature | ||
|
||
## debug(timeout) | ||
|
||
Creates a debug zone using the provided *timeout*, in milliseconds: | ||
|
||
```js | ||
debug(5000) | ||
``` | ||
|
||
## debug(timeoutZone) | ||
|
||
Creates a debug zone, using the provided *can-zone/timeout* zone. | ||
|
||
```js | ||
const timeout = require("can-zone/timeout"); | ||
|
||
... | ||
|
||
let timeoutZone timeout(5000); | ||
|
||
new Zone([ | ||
debug(timeoutZone) | ||
]) | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,22 @@ | ||
The *done-ssr/zones/donejs* zone is used to set up *done-ssr/zones/steal* and *done-ssr/zones/canjs*. This prevents users from needing to configure each of those zones individually. | ||
|
||
```js | ||
const Zone = require("can-zone"); | ||
const donejs = require("done-ssr/zones/donejs"); | ||
|
||
require("http").createServer(function(request, response){ | ||
|
||
new Zone([ | ||
donejs({ | ||
config: __dirname + "/package.json!npm" | ||
}, response) | ||
]); | ||
|
||
}).listen(8080); | ||
``` | ||
|
||
# Signature | ||
|
||
## donejs(stealConfig, response) | ||
|
||
Since this zone mainly just combines the steal and canjs zones, it needs each of those zones arguments. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,68 @@ | ||
The *done-ssr/zones/mutations* zone creates the `data.mutations` stream, for which serialized DOM mutations are written. Usually you will want to use *done-ssr/zones/push-mutations* rather than this zone. | ||
|
||
Use this zone if you want to handle the mutations yourself (pushing them to the browser and then applying the patches in the browser). | ||
|
||
```js | ||
const Zone = require("can-zone"); | ||
const mutations = require("done-ssr/zones/mutations"); | ||
|
||
require("donejs-spdy").createServer({ | ||
key: ..., | ||
cert: ... | ||
}, async function(request, response){ | ||
|
||
let zone = new Zone([ | ||
mutations() | ||
]); | ||
|
||
let runPromise = zone.run(); | ||
|
||
zone.data.mutations.on('data', function(chunk){ | ||
// Chunk is a string of DOM mutations | ||
}); | ||
|
||
let stream = response.push("/mutation-stream", { | ||
status: 200, | ||
method: "GET", | ||
request: { accept: "*/*" }, | ||
response: { | ||
"content-type": "text/plain" | ||
} | ||
}); | ||
|
||
// This pushes mutations into this PUSH promise stream | ||
// it is up to you on how to handle this in the browser. | ||
zone.data.mutations.pipe(stream); | ||
|
||
response.end(zone.data.html); | ||
|
||
}).listen(8081); | ||
``` | ||
|
||
# Signature | ||
|
||
## mutations() | ||
|
||
This zone takes no arguments. | ||
|
||
# Data properties | ||
|
||
These are the can-zone *data properties* that the mutations stream either creates or consumes. | ||
|
||
### Input | ||
|
||
These are data properties that *done-ssr/zones/mutations* will use, if present. | ||
|
||
#### zone.data.startMutations | ||
|
||
A Promise, used to delay when the zone starts listening to DOM mutations. You might use this if you want to modify the document and do not want these modifications to be part of the mutation stream. | ||
|
||
### Output | ||
|
||
These are data properties the zone creates. | ||
|
||
### zone.data.mutations | ||
|
||
A Node.js [readable stream](https://nodejs.org/api/stream.html#stream_readable_streams) of DOM mutations. Pipe this into a writable stream. | ||
|
||
## |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,46 @@ | ||
*done-ssr/zones/push-fetch*, when used on an HTTP/2 server, will initiate a PUSH promise for any URLs when using the [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) API. | ||
|
||
```js | ||
const Zone = require("can-zone"); | ||
const pushFetch = require("done-ssr/zones/push-xhr"); | ||
const requests = require("done-ssr/zones/requests"); | ||
const app = require("./app"); | ||
|
||
require("donejs-spdy").createServer({ | ||
key: ..., | ||
cert: ... | ||
}, function(request, response){ | ||
|
||
new Zone([ | ||
requests(request), | ||
pushFetch(response) | ||
]) | ||
.run(app); | ||
|
||
}).listen(8081); | ||
``` | ||
|
||
Where *app.js* looks like: | ||
|
||
```js | ||
module.exports = function(){ | ||
let ul = document.createElement('ul'); | ||
document.body.appendChild(ul); | ||
|
||
// In the browser this URL will be PUSHed | ||
fetch('/api/todos').then(res => res.json()) | ||
.then(todos => { | ||
todos.forEach(todo => { | ||
let li = document.createElement('li'); | ||
li.textContent = todo; | ||
ul.appendChild(li); | ||
}); | ||
}); | ||
}; | ||
``` | ||
|
||
# Signature | ||
|
||
## pushFetch(response) | ||
|
||
*done-ssr/zones/push-fetch* expects a http(s) response object, which it uses to initiate the PUSH promise. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,39 @@ | ||
*done-ssr/zones/push-images* is a zone that is used to initiate PUSH promises on images created using `new Image()` or `document.createElement('img')` APIs. Pushing these images will result in faster load times for your page. | ||
|
||
```js | ||
const Zone = require("can-zone"); | ||
const dom = require("done-ssr/zones/can-simple-dom"); | ||
const pushImages = require("done-ssr/zones/push-images"); | ||
const app = require("./app"); | ||
|
||
require("donejs-spdy", { | ||
cert: ..., | ||
key: ... | ||
}, function(request, response){ | ||
|
||
new Zone([ | ||
dom(request), | ||
pushImages(response) | ||
]) | ||
.run(app); | ||
|
||
}).listen(8081); | ||
``` | ||
|
||
where *app.js* looks like: | ||
|
||
```js | ||
module.exports = function(){ | ||
let img = document.createElement("img"); | ||
img.src = "/images/cat.png"; | ||
document.body.appendChild(img); | ||
}; | ||
``` | ||
|
||
Will result in `/images/cat.png` being PUSHed. | ||
|
||
# Signature | ||
|
||
## pushImages(response) | ||
|
||
*done-ssr/zones/push-images* expects an http(s) response object, which it uses to initiate the PUSH promise. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,34 @@ | ||
The *done-ssr/zones/push-mutations* zone is used for incremental rendering. It initiates a PUSH promise on the HTTP/2 connection, and pushes out DOM mutations that will be handled by a small client-side script that is injected into the page. | ||
|
||
```js | ||
const Zone = require("can-zone"); | ||
const dom = require("done-ssr/zones/can-simple-dom"); | ||
const pushMutations = require("done-ssr/zones/push-mutations"); | ||
const app = require("./app"); | ||
|
||
require("donejs-spdy", { | ||
key: ..., | ||
cert: ... | ||
}, function(request, response){ | ||
|
||
let zone = new Zone([ | ||
dom(request), | ||
|
||
pushMutations(response/* , url */) | ||
]); | ||
|
||
zone.run(app); | ||
response.end(zone.data.html); | ||
|
||
}).listen(8081); | ||
``` | ||
|
||
This will establish a PUSH promise for DOM mutations. These mutations will be streamed to the browser and applied in patches by a small client-side script. | ||
|
||
# Signature | ||
|
||
## pushMutations(response, url) | ||
|
||
This zone expects a *response* object, which is used to initiate the PUSH promise. | ||
|
||
Optionally you can provide a *url* string, the URL that will be used for the mutations stream. By default pushMutations will create a URL that is unlikely to conflict with one your app uses; in the form of `"/_donessr_instructions/" + Date.now()` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,43 @@ | ||
*done-ssr/zones/push-xhr*, when used within an HTTP/2 server, will establish a PUSH promise for all requests that are made with the `XMLHttpRequest` API. | ||
|
||
```js | ||
const Zone = require("can-zone"); | ||
const pushXHR = require("done-ssr/zones/push-xhr"); | ||
const requests = require("done-ssr/zones/requests"); | ||
const app = require("./app"); | ||
|
||
require("donejs-spdy").createServer({ | ||
key: ..., | ||
cert: ... | ||
}, function(request, response){ | ||
|
||
new Zone([ | ||
requests(request), | ||
pushXHR(response) | ||
]) | ||
.run(app); | ||
|
||
}).listen(8081); | ||
``` | ||
|
||
Where *app.js* looks like: | ||
|
||
```js | ||
module.exports = function(){ | ||
let xhr = new XMLHttpRequest(); | ||
xhr.open('/api/todos'); | ||
xhr.onload = function(){ | ||
let todos = JSON.parse(xhr.responseText); | ||
// todo do something with the todos | ||
}; | ||
xhr.send(); | ||
}; | ||
``` | ||
|
||
This will establish a PUSH promise for `/api/todos`. If the browser requests this URL (for example if you are running the same code in the browser), it will already be available to it in the PUSH cache. | ||
|
||
# Signature | ||
|
||
## pushXHR(response) | ||
|
||
push-xhr needs the server's *response* object in order to set up the PUSH promise. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
Enables polyfills for the XMLHttpRequest, fetch, and WebSocket APIs. Enables routing server-relative URLs such as `/api/todos` to resolve as `http://example.com/api/todos`. | ||
|
||
```js | ||
var requests = require("done-ssr/zones/requests"); | ||
var Zone = require("can-zone"); | ||
|
||
require("http").createServer(function(request, response){ | ||
|
||
new Zone([ | ||
requests(request) | ||
]) | ||
|
||
}).listen(8080); | ||
``` | ||
|
||
# Signature | ||
|
||
## requests(request, options) | ||
|
||
Takes an [IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage) (commonly called the __request__ object) and optionally an __options__ object with the shape of: | ||
|
||
* __options.auth.cookie__: Specifies a cookie to include with API requests. | ||
* __optiosn.auth.domains__: Specifies an Array of domains for which the *options.auth.cookie** will be set for. |
Oops, something went wrong.