Skip to content

Commit

Permalink
Update docs for js-sdk v0.4.18 (#125)
Browse files Browse the repository at this point in the history
* Change double quotes to single quotes

* Add docs for doc.subscribe('all')

* Add docs for history pane in Devtools
  • Loading branch information
chacha912 authored Apr 24, 2024
1 parent e3e9d43 commit 1b8299d
Show file tree
Hide file tree
Showing 8 changed files with 57 additions and 16 deletions.
29 changes: 27 additions & 2 deletions docs/devtools.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,19 @@ Once installed, you'll find the `Yorkie🐾` panel within Chrome Developer Tools

<Image alt="devtools" src="/assets/images/docs/devtools.png" width={1400} height={900} style={{ maxWidth: '800px' }} />

<Alert status="warning">Please note that the devtools is available only in yorkie-js-sdk version `0.4.13` or later for development builds.</Alert>
To use devtools, you need to set the `enableDevtools` option when creating the Document.

```javascript
const doc = new yorkie.Document('docKey', {
enableDevtools: true, // Adjust the condition according to your situation
});
```

<Alert status="warning">Please note that the devtools is available only in yorkie-js-sdk version `0.4.18` or later.</Alert>

### Key Features

Within the `Yorkie 🐾` panel, on the left, you will see the `Document` pane, and on the right, there is the `Presence` pane.
Within the `Yorkie 🐾` panel, you will find the `History` panel at the top, the `Document` panel at the bottom left, and the `Presence` panel at the bottom right.

#### Document pane

Expand Down Expand Up @@ -51,3 +59,20 @@ Within the `Yorkie 🐾` panel, on the left, you will see the `Document` pane, a
<video autoPlay loop muted playsInline style={{ maxWidth: '800px' }}>
<source src="/assets/images/docs/devtools-presence.mov"/>
</video>

#### History pane

| Event Type | Document | Presence |
| :------: | :------: | :------: |
| Local Change | <Image alt="object icon" src="/assets/images/docs/devtools-event-local-document.png" width={16} height={16} style={{ width: '16px' }}/> | <Image alt="object icon" src="/assets/images/docs/devtools-event-local-presence.png" width={16} height={16} style={{ width: '16px' }}/> |
| Remote Change | <Image alt="object icon" src="/assets/images/docs/devtools-event-remote-document.png" width={16} height={16} style={{ width: '16px' }}/> | <Image alt="object icon" src="/assets/images/docs/devtools-event-remote-presence.png" width={16} height={16} style={{ width: '16px' }}/> |

- Observe events occurring within the document.
- Local changes are highlighted in yellow, remote changes in blue, presence changes are represented by cursor icons and document changes are indicated by document-shaped icons.
- Easily debug through time-travel and replay.
- Move the slider and click on an event to check event details and see how the document has changed.
- Convenient navigation is possible using the arrow buttons at the top right or using the directional keys.

<video autoPlay loop muted playsInline style={{ maxWidth: '900px' }}>
<source src="/assets/images/docs/devtools-history.mov"/>
</video>
44 changes: 30 additions & 14 deletions docs/js-sdk.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -156,64 +156,64 @@ for (const { clientID, presence } of users ) {
Here is an example of showing a list of users participating in the collaborative application.
- [Profile Stack](/examples/profile-stack)

##### Document.subscribe("presence")
##### Document.subscribe('presence')

This method allows you to subscribe to all presence-related changes.
By subscribing to these events, you can be notified when specific changes occur within the document, such as clients attaching, detaching, or modifying their presence.

```javascript
const unsubscribe = doc.subscribe("presence", (event) => {
if (event.type === "initialized") {
const unsubscribe = doc.subscribe('presence', (event) => {
if (event.type === 'initialized') {
// Array of other users currently participating in the document
// event.value;
}

if (event.type === "watched") {
if (event.type === 'watched') {
// A user has joined the document editing in online
// event.value;
}

if (event.type === "unwatched") {
if (event.type === 'unwatched') {
// A user has left the document editing
// event.value;
}

if (event.type === "presence-changed") {
if (event.type === 'presence-changed') {
// A user has updated their presence
// event.value;
}
});
```

##### Document.subscribe("my-presence")
##### Document.subscribe('my-presence')

This method is specifically for subscribing to changes in the presence of the current client that has attached to the document.

The possible event.type are: `initialized`, `presence-changed`.

```javascript
const unsubscribe = doc.subscribe("my-presence", (event) => {
const unsubscribe = doc.subscribe('my-presence', (event) => {
// Do something
});
```

##### Document.subscribe("others")
##### Document.subscribe('others')

This method enables you to subscribe to changes in the presence of other clients participating in the document.

The possible event.type are: `watched`, `unwatched`, `presence-changed`.

```javascript
const unsubscribe = doc.subscribe("others", (event) => {
if (event.type === "watched") {
const unsubscribe = doc.subscribe('others', (event) => {
if (event.type === 'watched') {
addUser(event.value);
}

if (event.type === "unwatched") {
if (event.type === 'unwatched') {
removeUser(event.value);
}

if (event.type === "presence-changed") {
if (event.type === 'presence-changed') {
updateUser(event.value);
}
});
Expand Down Expand Up @@ -284,7 +284,7 @@ const unsubscribe = doc.subscribe((event) => {
});
```

##### Document.subscribe("$.path")
##### Document.subscribe('$.path')

Additionally, you can subscribe to changes for a specific path in the Document using `doc.subscribe(path, callback)` with a path argument, such as `$.todos`, where the `$` sign indicates the root of the document.
The callback function is called when the target path and its nested values are changed.
Expand All @@ -299,6 +299,22 @@ const unsubscribe = doc.subscribe('$.todos', (event) => {
});
```

##### Document.subscribe('all')

You can subscribe to all events occurring in the document by using `document.subscribe('all', callback)`. This is used for displaying events in [Devtools extension](/docs/devtools).

Events received from the callback function are of type `TransactionEvent`, which is an `Array<DocEvent>`. TransactionEvent represents a collection of events occurring within a single transaction (e.g., `doc.update()`).

The `event.rawChange` value for `local-change` and `remote-change` events, and the `event.value.snapshot` for `snapshot` event, are set only when `enableDevtools` option is configured as `true`.

```javascript
const unsubscribe = doc.subscribe('all', (transactionEvent) => {
for (const docEvent of transactionEvent) {
console.log(docEvent);
}
});
```

#### Changing Synchronization Mode

To change the synchronization mode for a document, you can use `client.changeSyncMode(doc, syncMode)`.
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added public/assets/images/docs/devtools-history.mov
Binary file not shown.
Binary file modified public/assets/images/docs/devtools.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 1b8299d

Please sign in to comment.