Skip to content

Commit f9a7c9a

Browse files
committed
add examples for sendUpdate, setUpdateListener
Closes #60 Some might say that the setUpdateListener example is too convoluted, but you can't really showcase the usage of `serial` without this much code. Plus, a briefer example is already shown in `sendUpdate()` docs. The code has been tested with the `webxdc-dev` tool, and (mostly) fomatted with Prettier.
1 parent afcea51 commit f9a7c9a

File tree

2 files changed

+65
-0
lines changed

2 files changed

+65
-0
lines changed

src-docs/spec/sendUpdate.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,21 @@ Send an update to all peers.
2929
- `descr`: short, human-readable description what this update is about.
3030
this is shown e.g. as a fallback text in an e-mail program.
3131

32+
Example:
33+
34+
```js
35+
window.webxdc.sendUpdate(
36+
{ payload: "Hello from Alice" },
37+
"A 'hello' message"
38+
);
39+
40+
// Peers can receive messages as such:
41+
window.webxdc.setUpdateListener((update) => {
42+
console.log(update.payload);
43+
});
44+
// 'Hello from Alice' is printed in the console
45+
```
46+
3247
All peers, including the sending one,
3348
will receive the update by the callback given to [`setUpdateListener()`](./setUpdateListener.html).
3449

src-docs/spec/setUpdateListener.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,56 @@ Each `update` which is passed to the callback comes with the following propertie
2929

3030
- `update.summary`: optional, short text, shown beside icon (see [`sendUpdate()`])
3131

32+
Example:
33+
34+
```js
35+
let myDocumentState = localStorage.getItem("myDocumentState") ?? "";
36+
37+
let initialPendingUpdatesHandled = false;
38+
const initialPendingUpdatesHandledPromise = window.webxdc.setUpdateListener(
39+
(update) => {
40+
// Remember that the listener is invoked for
41+
// your own `window.webxdc.sendUpdate()` calls as well!
42+
43+
applyDocumentUpdate(update.payload);
44+
localStorage.setItem("myDocumentState", myDocumentState);
45+
localStorage.setItem("lastHandledUpdateSerial", update.serial);
46+
47+
const areMoreUpdatesPending = update.serial !== update.max_serial;
48+
if (
49+
!areMoreUpdatesPending &&
50+
// We'll make the initial render when the promise resolves,
51+
// because if there are no pending updates,
52+
// the listener will not be invoked.
53+
initialPendingUpdatesHandled
54+
) {
55+
renderDocument();
56+
}
57+
},
58+
parseInt(localStorage.getItem("lastHandledUpdateSerial") ?? "0")
59+
);
60+
61+
initialPendingUpdatesHandledPromise.then(() => {
62+
initialPendingUpdatesHandled = true;
63+
renderDocument();
64+
});
65+
66+
function applyDocumentUpdate(myDocumentUpdate) {
67+
// Dummy `applyDocumentUpdate` logic.
68+
// Yours might be more complex,
69+
// such as applying a chess move to the board.
70+
myDocumentState = myDocumentUpdate;
71+
};
72+
// Let's only call this when there are no pending updates.
73+
function renderDocument() {
74+
document.body.innerText = myDocumentState;
75+
};
76+
77+
// ...
78+
// Other peers, or you:
79+
window.webxdc.sendUpdate({ payload: "Knight d3" }, "Bob made a move!");
80+
```
81+
3282
Calling `setUpdateListener()` multiple times is undefined behavior: in current implementations only the last invocation works.
3383
3484
[`sendUpdate()`]: ./sendUpdate.html

0 commit comments

Comments
 (0)