Documentation: More examples of save() callback of block

[Shelob9]

After spending some time teaching myself Gutenberg, I found the information on the save() callback for blocks and how serializing data to comments works
https://wordpress.org/gutenberg/handbook/block-edit-save/

• More examples of save() function, showing how you would use it for
  • Serializing attributes to main comment
  • Storing attributes in child elements
  • Saving content to be rendered in the front-end using same React component as used to render preview in edit callback.

In regards to serialization of data, it would be helpful if it was explained how automatic serialization of attributes work. A link to the section on attributes is also needed.

[mtias]

From #4071.

The reference page for attributes shows how to register attributes so they are de-serialized from the saved HTML. The examples do not show the corresponding save() callbacks making it harder to understand the concept.
https://wordpress.org/gutenberg/handbook/reference/attributes/

For instance the first example Example: Extract the src attribute from an image found in the block’s markup. shows how to extract from a saved image, but doesn't show how to save an image. That's actually how it's done here: https://wordpress.org/gutenberg/handbook/blocks/introducing-attributes-and-editable-fields/ and that is much better at illustrating the relationship between saving and using attributes.

[chrisvanpatten]

I think something to note here is that some of this is handled automatically and should just be noted, e.g. "Serializing attributes to main comment" — this should be an automatic thing, I believe.

In terms of this, I'm not sure this is really recommended at this point…

Saving content to be rendered in the front-end using same React component as used to render preview in edit callback.

So maybe that's more of a philosophical "here's why they're separate things" question?

[pbiron]

Another thing that should be documented is that if an attribute has the default when the post is saved, that attribute does not get serialized in the comment.

I actually think that behavior is a "bug" (for some definition of "bug"). Consider the following:

1. v1 of plugin X sets the default value of attribute y to z
2. a post with that block is saved on date A.
3. on the front-end the block will render with attribute y set to z
4. v2 of that plugin changes the default value to a.
5. on the front-end the block will now render with attribute y set to a and that might not be what users expect

So, at the vary least, the fact that default attributes values are not serialized should be documented, including the consequences of that fact (like the example above).

[pbiron]

I actually think that behavior is a "bug" (for some definition of "bug")

Related: #7342

[chrisvanpatten]

@ajitbohra This might be another good one for you to review!

[gziolo]

@mkaz or @nosolosw - is it something that was included in your tutorials?

[oandregal]

Not that I remember of. The ones I wrote tend to be more focused on a developer-facing task and don't go deeper on the APIs involved - just use the parts needed, as to familiarize people with them. Perhaps serialization docs in the handbook need to be expanded?