DataViews documentation: add high-level graph explaining DataViews and data sources interaction #65457
Conversation
|
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 If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
oandregal
requested review from
youknowriad,
juanmaguitar,
ryanwelcher and
ntsekouras
oandregal
added
[Type] Developer Documentation
packages/dataviews/README.md
Outdated
| @@ -2,6 +2,10 @@ | |||
|
|
|||
| DataViews is a component that provides an API to render datasets using different types of layouts (table, grid, list, etc.). | |||
|
|
|||
| DataViews is data agnostic, it can work with data coming from a static (JSON file) or dynamic source (HTTP Request) — it just requires the data to be an array of objects that have an unique identifier. Consumers are responsible to query the data source appropiately based on the DataViews props: | |||
|
|
|||
|  | |||
There was a problem hiding this comment.
I'm not sure this is the right way to embed images in the handbook. Do they still need to be in a external source (for example, pointing to the image as stored in this GitHub PR)?
There was a problem hiding this comment.
Also, I'm more than happy to collaborate and improve that graph: it's something I just created with the tools I had but other people may be able to create a better one.
There was a problem hiding this comment.
For the existing image we have in the handbook, we use the full URL https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/explanations/architecture/assets/modules.png. Not sure why or if it's better though.
Also, we do keep the "source" modules.excalidraw file in the repo to be able to edit it in the future if needed.
There was a problem hiding this comment.
Also, we do keep the "source" modules.excalidraw file in the repo to be able to edit it in the future if needed.
I can explore redoing the graph using excalidraw. Happy if anyone else beats me to it (have a bit of an hectic week).
There was a problem hiding this comment.
No need to redo it if you lost your source or did it with some other tool, it was just a suggestion based on what I did before :)
There was a problem hiding this comment.
I just used Obsidian Canvas and I have the source file that I can share. I'm just not sure how useful it'd be to anyone else? 😅 It seems excalidraw would be a more widely known format/app, and I agree having a source file to re-generate the image from is very useful.
There was a problem hiding this comment.
The best way to use images in the Handbook is to upload them to the Media Library for the Handbook's WordPress installation and reference it from that URL (see example)
Happy to help in uploading the required images to the Handbook's WP installation.
There are several excalidraw diagrams in the Block Editor docs. The original diagram link (where things can be modified) can be added to a Resources list at the end of the page, but that's not always needed (I don't think it's needed in this case)
Note: For accesibility issues the link to the image containing the diagram should also point to an image
There was a problem hiding this comment.
I added the image to the https://developer.wordpress.org/files so it can be referenced from there
https://developer.wordpress.org/files/2024/09/368600071-20aa078f-7c3d-406d-8dd0-8b764addd22a.png
There was a problem hiding this comment.
@oandregal if you change the link of the image to point to the URL above I think we can move forward with this PR.
I'm approving it to unlock the merge.
There was a problem hiding this comment.
ok, pushed those changes (be welcome to push them yourself in the future!). In the interest of shipping small improvements regularly, I'm merging this one. Perhaps we need to revisit it to also include DataForm documentation here. At that point, I can try with excalidraw.
What?
Adds a graph to the DataView's README explaining how DataViews works with data sources.
Why?
Through conversations, one consistent struggle people had was "how DataViews work with data?". People either assumes that DataViews is responsible to fetching data from an endpoint or that it can only work with static data. Far from the truth, DataViews can work with data coming from anywhere and it's important to clarify this.
How?
Expands the intro to DataViews component in the README and adds a graph explaining the data flow.