feat: add documentation for component queries #2881
Merged
+165
−0
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
archiewood
reviewed
Dec 10, 2024
There was a problem hiding this comment.
It's really good to have docs for this, a big step on.
I think we can simplify these to make the docs more accessible.
- Where possible, I think only showing or recommending one approach is preferable to multiple
- A new custom component author is unlikely to know how to choose between at this early stage. (I didn't when reading)
- Are there two types (and therefore sections in the page)
- "Static/One-time" queries: these execute once on page load
- Dynamic queries: these update whenever any query inputs change
A final thing I would consider (but not required) is publishing an example custom component in a standalone repo that implements a component query as a reference?
|
|
||
| 2. We then use the `QueryLoad` component to handle the query execution and loading states. The `let:loaded` syntax gives us access to our query results once they're ready. | ||
|
|
||
| <Alert status="info"> |
There was a problem hiding this comment.
shall we just delete this completely, and document as though this is mandatory
feels like unneccessary info
| // Build a static query | ||
| const query = buildQuery( | ||
| 'SELECT * FROM information_schema.tables', | ||
| 'table-list-query' // Optional unique identifier |
There was a problem hiding this comment.
Suggested change
| 'table-list-query' // Optional unique identifier | |
| 'table-list-query' // unique identifier for the query |
we can just say this is mandatory? no benefit to not using
|
|
||
| ## Working with Loading States | ||
|
|
||
| The `QueryLoad` component automatically handles loading states for your queries. You have three main approaches for managing how loading states appear: |
There was a problem hiding this comment.
not super clear why you would pick between these at the moment.
The recommended option is also the most complex because you have to specify the dimensions of the slot.
Why is the "Default" state not the recommended option
|
|
||
| ## Working with Query Results | ||
|
|
||
| There are several ways to access your query results within the `QueryLoad` component. Here are the different patterns and when to use them: |
There was a problem hiding this comment.
Can we just recommend the named variable approach here and remove the other options
It's not that verbose, and the other options seems less flexible
| - Use descriptive names for your query results that reflect the data they contain | ||
| - Avoid naming conflicts by not reusing variable names | ||
| - Consider using custom loading states for better user experience | ||
| - Include query IDs when debugging or working with multiple queries |
There was a problem hiding this comment.
Suggested change
| - Include query IDs when debugging or working with multiple queries | |
| - Include unique query IDs |
| - Building interactive data exploration interfaces | ||
| - Optimizing query performance | ||
|
|
||
| Remember that dynamic queries are more powerful but also more complex. Start with simple implementations and gradually add more features as you become comfortable with the system. |
There was a problem hiding this comment.
Suggested change
| Remember that dynamic queries are more powerful but also more complex. Start with simple implementations and gradually add more features as you become comfortable with the system. | |
| Dynamic queries are more powerful but also more complex. Start with simple implementations and gradually add more features as you become comfortable with the system. |
|
|
||
| ## Error Handling | ||
|
|
||
| When working with queries in your components, it's essential to handle errors gracefully to provide a good user experience. The `QueryLoad` component provides built-in error handling capabilities through its error slot. |
There was a problem hiding this comment.
Suggested change
| When working with queries in your components, it's essential to handle errors gracefully to provide a good user experience. The `QueryLoad` component provides built-in error handling capabilities through its error slot. | |
| When working with queries in your components, handle errors gracefully to provide a good user experience. The `QueryLoad` component provides built-in error handling capabilities through its error slot: |
|
|
||
| When working with queries in your components, it's essential to handle errors gracefully to provide a good user experience. The `QueryLoad` component provides built-in error handling capabilities through its error slot. | ||
|
|
||
| Here's how you can implement basic error handling: |
There was a problem hiding this comment.
Suggested change
| Here's how you can implement basic error handling: |
|
|
||
| </Alert> | ||
|
|
||
| When working with dynamic queries, you might want to handle errors differently depending on the state of your component: |
There was a problem hiding this comment.
Everything below this section feels pretty in the weeds
Co-authored-by: Archie Sarre Wood <[email protected]>
…evidence-dev/evidence into docs/using-queries-in-custom-components
archiewood
reviewed
Dec 11, 2024
sites/docs/pages/components/custom-components/component-queries.md
Outdated
Show resolved
Hide resolved
archiewood
reviewed
Dec 11, 2024
sites/docs/pages/components/custom-components/component-queries.md
Outdated
Show resolved
Hide resolved
…s.md Co-authored-by: Archie Sarre Wood <[email protected]>
…s.md Co-authored-by: Archie Sarre Wood <[email protected]>
…evidence-dev/evidence into docs/using-queries-in-custom-components
archiewood
approved these changes
Dec 11, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Checklist
For UI or styling changes, I have added a screenshot or gif showing before & afterI have added a changesetI have added to the VS Code extension where applicable