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

Improve documentation on the query-builder-container and query-builder classes #1041

Open
peterkmurphy opened this issue May 8, 2024 · 0 comments

Comments

@peterkmurphy
Copy link

Firstly, thank you, react-awesome-query-builder developers, for your product. It is allowing us to build queries awesomely in our work (and allow our users to build awesome queries). However, I think you really need to improve the documentation when it comes to the query-builder-container and query-builder classes.

This is what the existing documentation is:

<Builder />

Render this component only inside Query.renderBuilder() like in example above:

renderBuilder = (props) => (
<div className="query-builder-container">
<div className="query-builder qb-lite">
<Builder {...props} />
</div>
</div>
)

Wrapping <Builder /> in div.query-builder is necessary.
Optionally you can add class .qb-lite to it for showing action buttons (like delete rule/group, add, etc.) only on hover, which will look cleaner.
Wrapping in div.query-builder-container is necessary if you put query builder inside scrollable block.

My feature request is to add notes explaining that these classes are necessary for the "Reordering (drag-n-drop) support for rules and groups of rules" behavior of react-awesome-query-builder.

Why do I think this feature request is necessary? The issue here is that developers can remove query-builder-container and query-builder, from their renderBuilder method, find that people can build queries fine, combining them using "AND", "OR" and "NOT", with no obvious issues. Then they discover a month later that dragging and dropping is broken, no-one knows why, and there's nothing in the docs to indicate the reason. And in case you are wondering, this is exactly what happened to our team.

Yes, we diagnosed the problem, by the tried-and-true method of "doing a search of commits to find the commit which broke things; then doing a search of files in that commit to find the file that broke things; then doing a search of lines in that file to find the line that broke things". It's not something terribly pleasant, and I'd rather spare other people the stress. So please, add some extra documentation to these classes, so that everyone can be happy, and nobody has to go though the pain we did.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant