Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 19 additions & 22 deletions packages/docs/docs/guides/configure/serialization.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,9 @@ guide].
:::

The JSON serialization system is made up of multiple serializers. There are
built-in serializers for blocks and variables, and you can also register
additional serializers. Each serializer is responsible for serializing and
deserializing the state of a particular plugin or system.
built-in serializers for blocks, variables, and workspace comments, and you can
also register additional serializers. Each serializer is responsible for
serializing and deserializing the state of a particular plugin or system.

### Saving and Loading

Expand Down Expand Up @@ -104,6 +104,7 @@ The order for deserialization of built-in serializers is:
value inputs and statement inputs. Individual inputs are deserialized in
an _arbitrary order_.
4. **Next blocks are deserialized.**
6. **Workspace comments are deserialized.**

### When to save extra state

Expand Down Expand Up @@ -142,21 +143,19 @@ documentation.

The JSON system allows you to register serializers which serialize and
deserialize some state. Blockly's built-in serializers take care of serializing
information about blocks and variables, but if you want to serialize other
information you'll need to add your own serializer. For example, workspace-level
comments are not serialized by default by the JSON system. If you want to
serialize them, you will need to register an additional serializer.
information about blocks, variables, and workspace comments, but if you want to
serialize other information you'll need to add your own serializer.

Additional serializers are often used to serialize and deserialize the state of
a plugin.

```js
Blockly.serialization.registry.register(
'workspace-comments', // Name
'myPlugin', // Name
{
save: saveFn, // Save function
load: loadFn, // Load function
clear: clearFn, // Clear function
save: savePluginState, // Save function
load: loadPluginState, // Load function
clear: clearPluginState, // Clear function
priority: 10, // Priority
},
);
Expand All @@ -181,14 +180,11 @@ function will be called, and its data will be added to the final JSON output:
```json
{
"blocks": { ... },
"workspaceComments": [ // Provided by workspace-comments serializer
{
"x": 239,
"y": 31,
"text": "Add 2 + 2"
},
// etc...
]
"myPlugin": { // Provided by the myPlugin serializer
"x": 239,
"y": 31,
"text": "Add 2 + 2"
}
}
```

Expand All @@ -199,9 +195,10 @@ are triggered before serializers with less positive priority values.
When a serializer is triggered, two things happen:

1. The provided `clear` function is called. This ensures that the state of your
plugin/system is clean before more state is loaded. For example, the
workspace-comments serializer would remove all existing comments from the
workspace.
plugin/system is clean before more state is loaded. For example,
`clearPluginState` would remove the `x`, `y`, and `text` values that
`myPlugin` is currently storing for the workspace, so they aren't mixed
with the state being loaded.
2. The provided `load` function is called.

## XML system
Expand Down
Loading