Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docs for LocalAutosaveMonitor and __experimentalUpdateLocalAutosaveInterval #19915

Merged
merged 1 commit into from
Jan 28, 2020
Merged

Add docs for LocalAutosaveMonitor and __experimentalUpdateLocalAutosaveInterval #19915

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
7 changes: 7 additions & 0 deletions packages/edit-post/src/store/actions.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,13 @@ export function updatePreferredStyleVariations( blockName, blockStyle ) {
};
}

/**
* Returns an action object used in signalling that the editor should attempt
* to locally autosave the current post every `interval` seconds.
*
* @param {number} interval The new interval, in seconds.
* @return {Object} Action object.
*/
Comment on lines +199 to +205
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This won't actually be documented in the data handbook as long as it's experimental:

https://developer.wordpress.org/block-editor/data/data-core-editor/#actions

If we want to document it, are we also wanting to make it stable?

Related: #17743

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I came just for the documentation, regardless of its experimental status, but was wondering the same. On one hand, it's been a few months since the introduction of this API and it hasn't required any changes. On the other hand, it's arguably a very isolated piece that seldom receives attention, so its lack of change isn't necessarily indicative of soundness or stability.

For instance, I'm wondering whether this functionality might be better provided by something else, whether that's something generic to more editor settings, whether there's room for it in the recently proposed Features API, etc. WDYT?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Admittedly, I still haven't got around to digest the implementation on the whole, so I can't really speak to specifics about whether it's something we want to commit to. If you're already considering options for potential reimplementations, then I think it would be fair to keep it experimental. Or, at least, it shouldn't necessarily block this pull request, which is an improvement in its own right.

I'm also mindful of our human aversions to committing to anything as final and, given the choice, we'd make everything "experimental" forever. So, there's that ¯\_(ツ)_/¯ . It's always a balance.

export function __experimentalUpdateLocalAutosaveInterval( interval ) {
return {
type: 'UPDATE_LOCAL_AUTOSAVE_INTERVAL',
Expand Down
20 changes: 20 additions & 0 deletions packages/editor/src/components/local-autosave-monitor/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# LocalAutosaveMonitor

`LocalAutosaveMonitor` is a component based on `AutosaveMonitor` that ensures that a local copy of the current post is regularly saved in `sessionStorage`. Additionally, it will:

- attempt to clear the local copy if a copy is successful saved on the server;
- warn the user upon loading a post that there is a local copy that can be loaded;
- defer to remote autosaves, if any is available.

`LocalAutosaveMonitor` observes a saving interval defined specifically for local autosaves, in contrast with remote (server-side) autosaving. See editor setting `__experimentalLocalAutosaveInterval` and setter `__experimentalUpdateLocalAutosaveInterval`.

## Example

```js
const MyLayout = () => (
<main>
<LocalAutosaveMonitor />
<MyEditor />
</main>
);
```