search

vaadin / docs

Official documentation for Vaadin and Hilla.
https://vaadin.com/docs
Other
29 stars 195 forks source link

Documentation on the Upload component is inadequate #1321

Open bsutton opened 2 years ago

bsutton commented 2 years ago

I'm trying to use the Upload component with vaadin 23 flow (java)

https://vaadin.com/docs/latest/ds/components/upload

I'm guessing that Upload is a component but no of the examples show adding the Upload to a layout. There are lots of discussions around Upload showing a progress UI but little on the upload UI itself.

The doco shows an UploadExamplesI18N but no source code for it so it's just a magic box.

Also, the doco should discuss how to start an upload via a method other than drag/drop.

Finally, the doc says that all files are uploaded to the current working directory. I'm hoping this is an error in the doco as this makes no sense in a production environment where write access is limited to very specific directories and the working directory of the container is probably not going to be one of them.

bsutton commented 2 years ago

So on a second read, I notice the docs do mention a method of setting an alternate path to upload to. I think this information needs to be in the grid that discusses the FileBuffer and MultiFileBuffer.

jouni commented 2 years ago

The doco shows an UploadExamplesI18N but no source code for it so it's just a magic box.

That class should be included in all examples. Maybe you missed the second source file in the examples?

Screen Shot 2022-04-19 at 10 11 42
bsutton commented 2 years ago

I did miss the second source. Perhaps it needs to be made more prominent. We are still missing the broader concept of adding it to a layout. Possibly my path is contaminated by using vaadin 7 where there were some shenanigans of adding a button/component to the upload widget rather than the upload widget to the component. I do note in the documenters defence, that not showing the component being added to a layout seems to be consistent with other documentation. I'm however not a big fan of this philosophy as it leaves people guessing.

jouni commented 2 years ago

Perhaps it needs to be made more prominent.

I don't disagree. I’ve been struggling how to style those “tabs”, to make them prominent enough but at the same time subtle enough to fit the overall visual style.

jouni commented 2 years ago

not showing the component being added to a layout

I assume it is this line that you’d like to see in the code example, right? Screen Shot 2022-04-21 at 15 49 05

I think we do show that in some of the examples, and the intention has been to include that in the snippet, but apparently we haven't been following that.

bsutton commented 2 years ago

Yes, that would make the example a lot clearer. thanks.

S. Brett Sutton Noojee Contact Solutions 03 8320 8100

On Thu, 21 Apr 2022 at 22:51, Jouni Koivuviita @.***> wrote:

not showing the component being added to a layout

I assume it is this line that you’d like to see in the code example, right? [image: Screen Shot 2022-04-21 at 15 49 05] https://user-images.githubusercontent.com/66382/164461510-54e7c51b-840f-4fb8-919d-3ca7e7d154e8.png

I think we do show that in some of the examples, and the intention has been to include that in the snippet, but apparently we haven't been following that.

— Reply to this email directly, view it on GitHub https://github.com/vaadin/docs/issues/1321#issuecomment-1105168515, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAG32OC6L2G2B7GV4UCITHTVGFFLPANCNFSM5TXBJ3KQ . You are receiving this because you authored the thread.Message ID: @.***>