Closed jeremybradbury closed 3 years ago
LeeLenaleee
commented
3 years ago The reason those actions are not documented is because they are not part of chart.js, they are part of the documentation plugin that is used and generate buttons that apply the logic we want them to do,
Good solution to solve this might be to just hide the actions tab entirely as is done by the datalabels plugin: https://v2_0_0--chartjs-plugin-datalabels.netlify.app/samples/charts/line.html
etimberg
commented
3 years ago Honestly, there is not a good solution to this problem because every user has their own expectations of the documentation and each iteration of the docs over the 7 years I've maintained this library has had complaints and issues filed. As a result, we have tried to address and balance many competing priorities and visions for the documentation.
The current solution was chosen because it provides:
I think @LeeLenaleee has a good suggestion here. We can hide the action handlers from the deployed view since they are purely to power the buttons and are not required to use the library. I would recommend that we show the handlers if the docs are built locally. We had left the actions visible to give an understanding of common updates that could be performed and tried to keep the boilerplate to a minimum to improve the burden on the maintainers. It would be possible to show more of the boilerplate, however that code would mostly be read only.
Another possible option would be to add something to https://github.com/simonbrunel/vuepress-theme-chartjs that builds out a single HTML file of the sample with all of the code added in. I am not sure if that could be done within the confines of the vuepress plugin or if @simonbrunel would accept such a change. It may even be possible to do this entirely in this repo without changing the plugin.
jeremybradbury
commented
3 years ago The handlers being in a JSON array makes them look an option to be passed in and the tab layout is confusing.
the lack of html in the examples is a problem.
How about we start by helping me complete my codepen of the actions performed on the bar chart?
Nothing fancy, using a cdn copy, something a dev using any web platform can understand and implement.
At the very least it would be one complete example that could help clarify the current docs.
LeeLenaleee
commented
3 years ago If you want a complete example you can check out the normal docs on the usage page: https://www.chartjs.org/docs/master/getting-started/usage.html
If you want to see how to add actions using buttons to your chart you can check out the V2 samples because there it's done with pure html, some syntax is bit outdated but it will give you a great idea on how to implement such button actions: https://www.chartjs.org/samples/2.9.4/charts/bar/vertical.html
jeremybradbury
commented
3 years ago yeah i'm working on it in my codepen now
how do i resolve "Utils is not defined"?
it doesn't seem to be exported/created globally inside the CDN export.
is this a missing helper the examples do not provide? any reason it's not open source and part of the docs?
etimberg
commented
3 years ago The utils are from https://github.com/chartjs/Chart.js/blob/master/docs/scripts/utils.js. They aren't part of Chart.js itself and are just used for the documentation. The fiddle with the utils filled in looks like https://codepen.io/etimberg/pen/jOmmwgd
jeremybradbury
commented
3 years ago Thanks for adding those... pretty silly for the docs and examples to be missing these. would be nice to even just have a link to that url in the docs to explain what the heck you're doing in the "samples"/"examples". Note: Utils comes from here.
as it is now your "samples"/"examples" don't work without extra code, which shows me they are incomplete. as soon as I get these buttons worked out... I'm sure there are LOTs of developers who would love to use this example.
LeeLenaleee
commented
3 years ago There is a link on the samples page to the utils file: https://www.chartjs.org/docs/master/samples/utils.html, the reason the utils file is being used is to keep the samples maintainable and keeping them dry is a big help for that
Also in the normal docs it isnt getting referenced afaik
jeremybradbury
commented
3 years ago So after a bit more tweaking of the colors and scraping of styles I have created a complete example in a codepen.
jeremybradbury
commented
3 years ago @LeeLenaleee the issue isn't that the utils file is needed. it's that the link is nowhere to be found on the sample pages, even like a small "required Utils* found here" link in the footer.
@etimberg you've both been very helpful with all these resource.
I tried to build something simple, flexible (dark mode), complete (includes a function for for colored grids) and exactly as intended from the examples, docs and other resources you have both pointed me to.
https://codepen.io/jeremybradbury/pen/xxdddoB
Feel free to close this, especially if you plan on adding this example or something like it to the docs.
dcts
commented
3 years ago thanks so much @jeremybradbury for this codepen! I wish we had full examples like this for all the documentation examples... The actions thing was confusing for me as well.
jeremybradbury
commented
3 years ago I may actually be able to make a Svelte REPL with some complete component examples soon.
I tried to use some libs with pre-built components but couldn't get them working properly and ultimately I wanted more control over the component api, with less config boilerplate.
Ive been adding more props with defaults, moving the boilerplate into the component logic, rather than a more complex "config" state with nuances per type. This allows me to normalize my data and ignore the config unless I need to add/override something. I can present the same 3 datasets as 3 pies/donuts, a 3 set bar/line or scatter/bubble etc, in the same component, without transforming the config, just changing the "type" property.
The datasets can include the chart type, so that was one config property example it's nice to abstract rather than passing a full config for each chart. The config and data are well commingled in v3, it's fun to try and separate the largely static portions out.
I'd love to see config, and data in separate objects in the core, but we can use a component library to workaround that "design choice".
Until then, feel free to fork my codepen and make other examples. Line is a simple change... But pie and scatter need config formatted differently (which is why reusable components are so useful). You may need to grab more of the "utils" from that page in the docs for some of the complex examples.
jeremybradbury
commented
3 years ago @dcts as promised... I made a pretty powerful/flexible Svelte example based on data mocks from Postgraphile + Aggregations plugin. The plugins makes aggregations stuff you can consume with ChartJS, allwoing GROUP BY etc. I extended the timestamp truncation features so we can group by the most common intervals: year, quarter, month, week, day.
You can generate GraphQL schema from good PostgreSQL schema, then use GraphQL Code Generator to make the Svelte client functions exposing an observable store for each query/mutation/subscription. Meaning you just watch/sub to any graphql query, but subscriptions can also change the UI without resending a query.
Read the notes, there's a small workaround to get it working inside the REPL and how to actually implement it in a project. There are also links to all the required materials to reproduce this locally.
https://svelte.dev/repl/96fff1ea92ec46d2b465a0830d958782?version=3.42.1
dcts
commented
3 years ago Hey @jeremybradbury thats great for svelte devs, but for me personally I was just happy with unpacking how the actions are implemented in the chart in the examples of chart js, which in your codepen is covered pretty well! :) I think there should be a button "confused about how actions should be implmeneted? See fully working html / css / js example" with a link to your codepen that shows the full setup.
jeremybradbury
commented
3 years ago thats great for svelte devs...
Well the plan is to eventually expand it to show scatter graphs with prediction curves (or polynomial regression), like is so easily done with NumPy, but we can use PosgreSQL functions (implemented in Potgraphile Aggregates, as GraphQL schema) on the data to make the standard deviation and sample calculations simpler & far more efficient (running inside the database engine) with ChartJS which is a much better presentation layer compared to NumPy (or more specifically PyPlot style renderings).
And also not only does Svelte closely mirror React, it's much more readable (and if you hate it GraphQL Code Generator supports React, Vue & Angular out of the box). I can present Svelte prototypes to a "c-level" audience who understands basics of html (think "has used Wordpress content management" slightly beyond "knows M$ Word"), and without much/any explanation they understand the code's intent.
So anyone with html/css knowledge should be able to recreate this in nearly any framework that supports web components, like Lit, or React type component libs that become markup rather than web components.
"confused about how actions should be implmeneted? See fully working html / css / js example" with a link to your codepen that shows the full setup.
I agree, something like that was the hope of this issue... but I purposely suggested the maintainers fork/recreate mine. This way they can remove the motivation of "attention seeking" from the equation, leaving only "improved documentation for all".
Documentation Is:
Please Explain in Detail...
There are "actions" and the implication we can add event handlers to in chart buttons by passing in actions. However, in the examples, the actions are never passed into the config and the API docs lack any mention of actions.
Same issue is described in detail here: https://www.reddit.com/r/learnjavascript/comments/msomp2/chartjs_actions/
If you follow this "example", if you could call it that, you are supposed to just add an array called actions to the page and it just works?
No, it does not, I have tried that.
https://www.chartjs.org/docs/latest/samples/bar/vertical.html
Your Proposal for Changes
Show complete examples instead of several small tabs, that require scrolling and don't put it all together anywhere. These examples are incomplete and it's very hard to google for more complete examples. This library is quite mature and this issue has persisted for quite a long time. We should be able to have complete docs with clear examples.
From here it almost seems like you don't want ppl to use ChartsJS. Providing incomplete and misleading examples are worse than providing none. When there are none provided, a Google search becomes more useful with ppl sharing their own examples.
Why not a single small, whole html document, for each example so there isn't guessing/assumptions about where the actions array is supposed to go etc?
Example
This is the entire example copied from here: https://www.chartjs.org/docs/latest/samples/bar/vertical.html
It renders nothing without some html with a canvas, a one-liner to make this example more complete. I can kinda figure that part out, but why not show it?
Even then, it renders no buttons and no actions are passed to the chart. That part is not clear to anyone... see the replies to that reddit thread... everyone is still in the dark.
https://codepen.io/jeremybradbury/pen/xxdddoB