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

Block Bindings: Docs API reference. #66251

Merged
merged 26 commits into from
Oct 30, 2024
Merged

Conversation

cbravobernal
Copy link
Contributor

What?

Initial draft for Block Bindings

Why?

Documentation is necessary.

@cbravobernal cbravobernal added the [Type] Developer Documentation Documentation for developers label Oct 18, 2024
@cbravobernal cbravobernal self-assigned this Oct 18, 2024
Copy link

github-actions bot commented Oct 22, 2024

Flaky tests detected in fa3fbe5.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/11597084347
📝 Reported issues:

Copy link

github-actions bot commented Oct 24, 2024

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: cbravobernal <cbravobernal@git.wordpress.org>
Co-authored-by: artemiomorales <artemiosans@git.wordpress.org>
Co-authored-by: justintadlock <greenshady@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: SantosGuillamot <santosguillamot@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Copy link
Contributor

@artemiomorales artemiomorales left a comment

Choose a reason for hiding this comment

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

I found a few typos; I'll push a commit to fix those and left a few other suggestions.

One thing: The parameter definitions throughout the document are inconsistent and repeat themselves unnecessarily. I suggest revising the definitions like in this comment using either colons (:) or hyphens (-) between the property name and its description to make these easier to read.

docs/reference-guides/block-api/block-bindings.md Outdated Show resolved Hide resolved
docs/reference-guides/block-api/block-bindings.md Outdated Show resolved Hide resolved
docs/reference-guides/block-api/block-bindings.md Outdated Show resolved Hide resolved
docs/reference-guides/block-api/block-bindings.md Outdated Show resolved Hide resolved
docs/reference-guides/block-api/block-bindings.md Outdated Show resolved Hide resolved
@artemiomorales
Copy link
Contributor

@artemiomorales I did a push with force-with-lease that should have not deleted your commits, but did 🤦‍♂️ .
I think I re-addressed your comments, but please if you could do a recheck it would be great.

Sorry for the trouble 😞

@cbravobernal No worries, I added back the missing bits and added a few more revisions 👍 Feel free to roll back anything you disagree with.

docs/reference-guides/block-api/block-bindings.md Outdated Show resolved Hide resolved
docs/reference-guides/block-api/block-bindings.md Outdated Show resolved Hide resolved
docs/reference-guides/block-api/block-bindings.md Outdated Show resolved Hide resolved
docs/reference-guides/block-api/block-bindings.md Outdated Show resolved Hide resolved
docs/reference-guides/block-api/block-bindings.md Outdated Show resolved Hide resolved
The `label` argument will override the one defined on the server if they are different.


This example will show a custom post meta date in the editor and, if it doesn't exist, it will show today's date. The user can edit the value of the date. (Caution: This example does not format the user input as a date—it's only for educational purposes.)
Copy link
Contributor

Choose a reason for hiding this comment

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

I would polish the example to show an "e2e process" of how a source should be registered, first in the server and then improved in the editor. I'm saying this because I can see we are defining a different usesContext when in most cases label and usesContext shouldn't be defined in the client.

Copy link
Contributor Author

@cbravobernal cbravobernal Oct 29, 2024

Choose a reason for hiding this comment

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

I added a comment (with the option to skip it). But in my humble opinion, documentation should not follow a tutorial's structure. The developer may access only to this part, skipping previous steps.
Link: 2a6bf13

docs/reference-guides/block-api/block-bindings.md Outdated Show resolved Hide resolved
docs/reference-guides/block-api/block-bindings.md Outdated Show resolved Hide resolved
docs/reference-guides/block-api/block-bindings.md Outdated Show resolved Hide resolved
- `canUserEditValue`: `function` to determine if the user can edit the value. The user won't be able to edit by default. (optional)
- `getFieldsList`: Experimental `function` that should not be used yet by third-party developers in production, as it is subject to change and may be removed in upcoming releases. It creates a list for the block bindings UI with post meta.

The `label` argument will override the one defined on the server if they are different.
Copy link
Contributor

Choose a reason for hiding this comment

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

Should we move this sentence to the label property explanation?

@SantosGuillamot
Copy link
Contributor

This is looking great 👏 We can keep iterating on it once it is merged.

One important aspect is ensuring that every API is annotated with the major WP version it was introduced.

They are already documented in the code, but maybe it makes sense to include something in the docs.

@@ -371,6 +371,12 @@
"markdown_source": "../docs/reference-guides/block-api/block-attributes.md",
"parent": "block-api"
},
{
"title": "Bindings",
Copy link
Member

Choose a reason for hiding this comment

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

So great to see it exposed here ❤️

@cbravobernal
Copy link
Contributor Author

Excellent work putting this reference document together 👏

The new document still needs to be listed in the manifest file to get exposed in the developers portal:

https://github.com/WordPress/gutenberg/blob/trunk/docs/manifest.json

One important aspect is ensuring that every API is annotated with the major WP version it was introduced. It will save a lot of trouble when someone needs to support older versions than WordPress 6.7, which by the way is still not released so some APIs still don't work on production.

Addressed in fa3fbe5

Copy link
Contributor

@SantosGuillamot SantosGuillamot left a comment

Choose a reason for hiding this comment

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

This is looking good to me ☺️ We can work on improvements in follow-up pull requests if needed.

@cbravobernal cbravobernal enabled auto-merge (squash) October 30, 2024 16:35
@cbravobernal cbravobernal merged commit aa2279b into trunk Oct 30, 2024
63 checks passed
@cbravobernal cbravobernal deleted the docs/block-bindings-first-docs branch October 30, 2024 16:42
@github-actions github-actions bot added this to the Gutenberg 19.7 milestone Oct 30, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants