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.

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

Documentation: More examples of save() callback of block #4070

Closed
Shelob9 opened this issue Dec 18, 2017 · 7 comments
Closed

Documentation: More examples of save() callback of block #4070

Shelob9 opened this issue Dec 18, 2017 · 7 comments
Assignees
Labels
[Feature] Extensibility The ability to extend blocks or the editing experience Good First Issue An issue that's suitable for someone looking to contribute for the first time [Type] Developer Documentation Documentation for developers

Comments

@Shelob9
Copy link
Contributor

Shelob9 commented Dec 18, 2017

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.

@ntwb ntwb added the [Type] Developer Documentation Documentation for developers label Dec 19, 2017
@danielbachhuber danielbachhuber added the [Feature] Extensibility The ability to extend blocks or the editing experience label Apr 11, 2018
@gziolo gziolo added the Good First Issue An issue that's suitable for someone looking to contribute for the first time label Jun 12, 2018
@gziolo gziolo added this to the Merge Proposal: Documentation milestone Jun 12, 2018
@mtias
Copy link
Member

mtias commented Oct 7, 2018

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
Copy link
Contributor

chrisvanpatten commented Nov 6, 2018

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
Copy link

pbiron commented Nov 6, 2018

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
Copy link

pbiron commented Nov 6, 2018

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

Related: #7342

@chrisvanpatten
Copy link
Contributor

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

@gziolo
Copy link
Member

gziolo commented Jan 23, 2019

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

@oandregal
Copy link
Member

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Feature] Extensibility The ability to extend blocks or the editing experience Good First Issue An issue that's suitable for someone looking to contribute for the first time [Type] Developer Documentation Documentation for developers
Projects
None yet
Development

No branches or pull requests

10 participants