GH-2107: Use a progress bar to show the overall upload status

[kinow]

GitHub issue resolved #2107

Pull request Description:

Display the statuses of file uploads near the top / visible area, so users do not need to scroll the page to track the progress of their uploads.

---

• Tests are included.
• Documentation change and updates are provided for the Apache Jena website
• Commits have been squashed to remove intermediate development commit messages.
• Key commit messages start with the issue number (GH-xxxx, or if in JIRA, JENA-xxxx)

By submitting this pull request, I acknowledge that I am making a contribution to the Apache Software Foundation under the terms and conditions of the Contributor's Agreement.

---

See the Apache Jena "Contributing" guide.

[kinow]

Hi @neumarcx ,

What do you think of this first prototype?

(I used the JS console to both confirm there are no errors, and to hide some uploads so we can see what it would look like -- also developing for mobile/smaller viewport by default.)

Not fully functional as I have to hook another reactive field to compute the number of successes and failures. Any other metric we should include?

Once we have agreed on the UI prototype and how it should behave, I will make it work correctly, add a test, and a changelog entry.

Thanks!

[neumarcx]

very nice Bruno, yes I think that's all we need. Not sure that we need them to be multi functional value boxes though.

how about the following mockup. "Success" and / or "Failure" may actually not need to be shown prior to the upload.

just an additional idea.

[neumarcx]

also "Upload Status" might be sufficient as there is only one status.

[kinow]

Hi @neumarcx !

+1 for "Upload status"!

how about the following mockup. "Success" and / or "Failure" may actually not need to be shown prior to the upload.

My first prototype didn't show the status by default, then I realized it would "move things in the UI". That's considered bad for UX ¹, but more importantly can impact performance negatively ², so it'd be nice if we could find a permanent place that doesn't move things too much.

And I didn't use colors because the red would attract your eyes (at least it does to me when I open a page like that), even if it says 0 (imagine Twitter with the notification symbol enabled by default showing 0, or GitHub's notification icon). So instead of users slowly reading the page, their first eye scanning would be to look at the red, and then proceed to use the page³. Green would have the same effect, and it has also color-blindness issues ⁴.

I tried to place each number in a fixed location using table columns so users would know where to find them, once they learn it. But a single line without a table could work too.

What do you think? Maybe something like your prototype but with the text only? Any thoughts @afs, @rvesse ?

Footnotes

1. that's CLS, and I hate it because some sites (Twitter, DeviantArt, ...) and apps (Zoom, Discord) have this, that when you have your mouse over a button and something happens and the DOM elements shift, and you end up clicking on something else: https://javascript.plainenglish.io/3-ways-to-fix-cumulative-layout-shift-53df8bea1e0f?gi=e99977032785 ↩

2. because it moves other HTML DOM elements, which might cause JS to have to re-render code like Vue.js components, and redraw things ↩

3. related to visual weight & visual direction: https://www.smashingmagazine.com/2014/12/design-principles-visual-weight-direction/#visual-weight ↩

4. https://www.smashingmagazine.com/2016/06/improving-color-accessibility-for-color-blind-users/#6-color-combinations ↩

[neumarcx]

Thank you @kinow for the comprehensive motivation for your design choices and I can follow your position on my idea with the references you have provided.

I also see your point with regards to the Cumulative Layout Shift. I don't have an immediate opinion on it but can intuitively sense the issue. The UI might even feel broken as the user might misread the design.

Could you please elaborate the one liner idea? May main concern with the multi functional table columns was that they indicate more functionality than is never used (sortable).
I may have miss interpreted how the status table works. Will the table expand with multiple errors or always it always be juts one line? One table header row and one table value row?

If it is just one line / row and we remove the sortable function we might already be done as the table outline looks neat and in place with the remain page elements.

[neumarcx]

what's the next step here? I can see the changes in your repo but they are not approved yet.

[kinow]

Sorry, I haven't had time to look at your previous comment, @neumarcx . I'd say we continue discussing to get a good prototype, then I hook up the JS code to make the prototype into actual working code, add unit tests, and then mark as ready for review.

[neumarcx]

Ok good @kinow keep me in the loop. I guess I have to close the issue at some point.

Where do I check out your current version of the work? The current jena github repo is already tagged for Jena 5. I presume that's not the version it will be available for but it will be available for version Jena 4.10.

[kinow]

I think this might go into Jena 5, unless we finish it soon and want to backport it to jena4 (main is jena5 now,

jena/pom.xml

Line 29 in cb23ddc

<version>5.0.0-SNAPSHOT</version>

, see jena4 branch for Jena4 related work). The changes are in the branch of this repo, better-upload-ux.

I will keep updating this PR as I have time, and you should get some GitHub notifications and/or maybe emails. Once we merge this PR it should close the issue automatically (because of the “GitHub issue resolved #2107” at the issue description).

[kinow]

Hi @neumarcx ,

Coming back at this one 👋

I was thinking in moving the status information "inside" the upload component, instead of being a section above the upload form.

And instead of a table with three columns, after thinking a bit I thought maybe we could use progress bar like the rest of the uploads, where you have an upload bar per file.

Here's the first preview. I am prototyping it, but pretend there are files selected and the upload is happening 🙂

The progress bar starts gray. As it progresses, the blue bar increases. In case of errors, the red bar increases. At the end summing both we will get 100%.

The success bar can be green or blue, but I thought green could be confusing because of the select all button (although blue is also mixing with the upload all button). Initially the bars were empty, then I added 30% and 20%, and then I added the 3/10 and 2/10 to have the same information we had before (to answer a question like "how many files were selected).

WDYT?

[kinow]

Refactored to match what we discussed on Twitter, @neumarcx. Edited commit, and did manual tests. It's now missing just the unit/e2e tests, and then it'll be ready to go. Some screenshots of what it looks like in action.

Blank page when you open the page to add data:

Selecting one invalid file, and two valid files.

Hitting upload all:

If you remove one of the files, it's reactive, so it adjusts the progress bar accordingly:

And if you add a new file, it again updates correctly.

I think that will indeed help users who need to upload multiple files at once. Next step the tests (when I find time for that 👍)

[kinow]

Tests added, @neumarcx, tested yarn test:unit, yarn lint, and yarn run test:e2e locally and all passed.

The test is an e2e test, that loads three files. There is a Cypress “interceptor” that, as the name says, intercepts network requests to the URL to handle the upload, and the test-interceptor fails every odd-time it is called.

There are tests for no files selected, showing an empty progress bar (so no content shift, or very minimum, which is good!), and a test that adds three files, and confirms we get 2/3 success, and 1/3 failure, and that the progress bars (4 in total, an overall progress, and one for each file selected) are displayed correctly.

👍

[afs]

upload multiple files at once

Only one file at a time will make real progress actually going into the database. Each may start a little way due to connection buffering but then stop and wait. One will be uploading.

[afs]

Looks great - tested using the uploads page in a few ways.

[kinow]

Looks great - tested using the uploads page in a few ways.

Thanks Andy!

[afs]

Presumably, the branch "better-upload-ux" can be deleted?

[kinow]

Yes, forgot to do that, sorry. Branch deleted.