Allow users to upload and edit form media within the formbuilder

[tinok]

As a survey administrator, I want to be able to add my images/sounds/videos for my form more easily and to preview them during the form design process so that I can save time.

Proposed path

If using formbuilder:

1. User can upload media files directly in the formbuilder
2. For any question, user can choose among uploaded files in a dropdown (OR user types in the file name) within the question settings
3. User clicks preview and sees the media in the right place

If using xlsform

1. User uploads their xlsform, already specifying which media file should be used where
2. User uploads media files on the form landing page
3. User clicks preview

Current path

At the moment, this is only possible after 1) creating, saving, closing the form; 2) deploying it; 3) going to Settings > Form media, 4) adding media files; 5) downloading the form to XLSForm; 6) adding the relevant filenames as per XLSForm spec; 7) replacing the form; 8) redeploying the form; 9) open EE link from 'collect data' section (not preview).

[tinok]

Previous comment from @jnm

• Move form media file handling to KPI AssetFile
• Remove KC iframe from KPI settings
• Figure out how to pass a manifest to Enketo along with the AssetSnapshot XML preview
• For deployed forms, have KPI serve manifests and have KC formList point at KPI's manifests When (re)deploying, have KPI push the media files to KC, overwriting any that are already there. KC continues to serve manifests for deployed forms.

https://opendatakit.github.io/xforms-spec/#supported-media-types select_one_external (csv only?) select_one_from_file (csv or xml)

[jnm]

For previewing, KPI would have to implement minimal OpenRosa form list and form manifest endpoints

Form list (will only ever contain one form in this context)

<xforms xmlns="http://openrosa.org/xforms/xformsList">
    <xform>
        <formID>agNZGnGtHbpH9hbQPjn6rQ [asset.uid]</formID>
        <name>Media! [asset.name]</name>
        <majorMinorVersion/> [seems to be unused]
        <version/> [seems to be unused]
        <hash>md5:abcdef123567890blah [probably the hash of the asset snapshot xml?]</hash>
        <descriptionText>Media! [also asset.name?]</descriptionText>
        <downloadUrl>asset snapshot xml url</downloadUrl>
        <manifestUrl>https://kc.kobotoolbox.org/jnm_demo/xformsManifest/372177 [new KPI manifest endpoint]</manifestUrl>
    </xform>
</xforms>

Form manifest [zero, one, or many media]

<manifest xmlns="http://openrosa.org/xforms/xformsManifest">
    <mediaFile>
        <filename>nuthatch.png</filename>
        <hash>md5:d1f05ced9b4382e0a0b8c6daf32efc28</hash>
        <downloadUrl>https://kc.kobotoolbox.org/jnm_demo/xformsMedia/372177/966204.png</downloadUrl>
    </mediaFile>
    <mediaFile>
        …
    </mediaFile>
</manifest>

[jnm]

If the new KPI form list for previews lives at, say, https://kpi-host/foo/bar/baz/formList (and it must indeed end with formList), then you would POST https://kpi-host/foo/bar/baz to Enketo's https://apidocs.enketo.org/v2/#/post-survey-preview as the server_url, along with the asset.uid as the form_id.

[tinok]

@Ig-Rebollo We need a mockup design suggestion for this feature. At the moment this is all done in the settings; I suggest we keep a way to add media there but add a modal that can be accessed in the formbuilder.

Current upload method looks like this (using an iframe from kobocat):

[Ig-Rebollo]

Copy that @tinok , will give it some thought and upload here a proposal/quick mockup this week.

[Ig-Rebollo]

@tinok @jnm Ignore my previous comment on this (I deleted it). It took me a while to understand the functionality that was needed (the current path to do this is truly insane, hence my confusion).

Here is what I would propose to upload files to the form builder. Notice the fifth button to upload media, right beside the cascading select:

I'm still going back and forth on how to allow the use of these files for a specific question. Potentially in the question settings as Tino proposed, though I think it would be preferable to have it more visible (i.e. somewhere in the question box)

Another question (maybe I also missed it from previous comments): Why do I need to upload files to the project first, instead of uploading directly to the question I want the media in? Is there a technical restriction there? Otherwise, what is the benefit? (assuming it would be being able to select an already uploaded file several times, but in that case, why not simply duplicate the question with the uploaded file, for example?)

[tinok]

@jnm @noliveleger Just adding a note here for the backend specs: We need to support fetching external files based on media URLs, just as in kobocat.

A user should be able to specify one or more URLs of files to be fetched (CSV, images, etc.). They should have the option to edit or delete them as well.

kobocat creates a unique URL which is just a 302 redirect to the actual URL, unclear if we need to replicate this.

[tinok]

UX notes:

We need two different views / paths:

1. Within the formbuilder Usecase: User creates or edits edits their form in the formbuilder.

2. Outside the formbuilder Usecase: User created their form in XLSForm, already references various images, CSV, etc. They then need a way to upload these files (or specify the URLs).

[Ig-Rebollo]

@tinok one small comment: Not sure I understand the need to edit files once uploaded. I would assume if users need to edit an image, audio or video they would do so with an external software, before uploading to the formbuilder. I included in the wireframes the option to remove files from the project, but in which case would they have to edit those files in the formbuilder?

[Ig-Rebollo]

@tinok @noliveleger @jnm @dorey It took me a bit longer as I fully recreated the screens with all the details in Sketch, but having a high def mockup will be helpful if we want to test with some users, plus, having a detailed template in Sketch of the form builder will be useful in the future regardless.

Here are the designs with the proposed path to upload and manage media: mockups in PDF This would be (I think) the simplest way to go about it without changing much in the current interface. You would be able to do everything directly in the form builder, even if the method is a bit hidden and restrictive. Maybe not a huge change for beginner users as it is not very 'findable', but I think it is still a massive improvement for more advanced users, without changing much of the larger interface of the form builder.

As you can see in the GIF below, the button on the top navigation takes you to the upload and file management modal, while the warning on top of each question would take you directly to the 'Media' section of the question settings. The intention is to lead users through the different steps, as the process is not super intuitive. Also note that if there is no media, the text box in settings would be empty and no warning would appear, one way or another.

Let me know what you think. We can definitely make it even more intuitive and easy to navigate, reducing steps, etc. But that may imply a much deeper redesign. In any case, happy to make more iterations so let the feedback come!

[tinok]

@Ig-Rebollo Here's some feedback based on the mockups:

Screen 1:

• I like how I can see whether a question has media. My first reaction is that I'd rather see a thumbnail of the image (or an icon for audio / video / other) below the label than the text '1 file attached'. I could imagine it's above the label
• What would it look like if a question only has an image but no label? We'd need a new placeholder (that replaces the "Question label is required" error message)
• What does it look like for image response options? Just like questions, they can have either a label, or a media file, or both. (So the implementation would probably be the same..?)

Screen 2:

• Would be good to have a button/link to the help article explaining how form media work
• Could there be a preview thumbnail next to the file names, in the case of an image? For non-images it could just be an icon.
• Could this screen also display whether a filename is mentioned in the form but hasn't been uploaded yet?

Screen 3:

• A question can have multiple files, but the header for each will need to be different (e.g. media::audio, media::image, media::video, media::image::Spanish (es) etc. This will need more discussion. One way would be to just let the user type in whatever they want as the media file header. Nicer would be automatic detection of the file type, so the user would only need to specify the language (if applicable). CC @dorey
• What does the screen look like without an attachment? I.e., how can I add an image if the form wasn't uploaded from an XLSForm?

[Ig-Rebollo]

@tinok Thanks for the feedback. Some comments and questions: Screen 1:

• The current 'file(s)' missing indicates when any of the files are missing, which means either in the question as a whole or in one or several of the options. Basically the warning will appear when it detects anything missing, in any of the fields.
• You're right about the label... as of now it simply focuses on whether it can locate images or not. But we could repurpose my warning message to let you know if anything is missing, whether it is image or label.
• Thumbnails would be nice, though I didn't want to force too many visual changes in the formbuilder as I wasn't sure how much we can/should change at this stage. Will look into incorporating the thumbnails in the design.

Screen 2:

• Button to the help article would indeed be a great idea. Assuming this button would be in the modal? or were you thinking the navigation bar?
• Definitely, I also thought of this.
• Did not think of this, but also good point.

Screen 3:

• Not sure I understand the problem. In the mockup each picture is linked to an available selection of a multiple choice question. If it wasn't a multiple choice question though... would need to think how to organize that section of the settings.
• In this mockup 'title of selection 4' doesn't have any image attached (this is why it doesn't have any warning, either positive or negative). If I wanted to link an image I would have to: a/ upload the file to the project in the 'file management' modal; b/ open settings; c/ go to the media tab, and type the exact name of the file in the option I want the file to be linked to. The system would recognize the matching names and link the image. This is of course not 'ideal' from a user perspective, but it is better than what we have, and it would provide the functionality without too much dev effort on our side.

[Ig-Rebollo]

@tino @jnm @dorey Here are some additional mockups incorporating most of the feedback. The first couple of screens show the case of a file missing (the form is uploaded from excel, with the file name included, but the file itself hasn't been uploaded to the project yet). The following screens develop the example of files uploaded and linked to a question, but with a label missing.

Here is the link to the mockups, which can also be found in the KoBo UX/UI GDrive > UX & Design Projects > Upload Media to Formbuilder.

A question that came up from creating these: I wasn't sure if a file can have more than 1 label per project. If I upload a photo to the project, and then I use the same photo in two different questions, could the label for that picture be different for each question? Would the picture be technically 'duplicated' when I use it twice, or is it always the same picture that must therefore always have a consistent label?

Anyhow, there are many details like these we can discuss in the call, though I think we're getting closer. Let me know what you think.

[Ig-Rebollo]

@tinok @jnm @dorey here are the new mockups for the file uploads in the form builder using the system we discussed last week (uploading files directly to questions and labels). As you can see the overall project file management modal is still there, as it will be useful to manage files for projects created in Excel and imported into KoBo. As you will see the modal for uploading directly into a question is slightly different from the project modal, to reduce complexity, but quite similar in nature.

Here is an example user flow:

And here you can find the PDF mockups, with some additional screens showing what happens when you drag and drop, or when you hover over the thumbnails (spoiler alert: and eye icon shows up, and clicking on it would open the image in a new tab).

Let me know what you think. If you have any comments I can try to fix it in the upcoming days, so we can hopefully implement something soon and test it.

[tinok]

@Ig-Rebollo This looks great. Some feedback:

• I like the icons and buttons for media files. But I wonder if we can place it in the same row as the label to avoid making the boxes even larger. Generally they are already quite high and for many users they should be more compact to fit more questions on a screen while editing/browsing a form.
• Same comment but for response labels - doubling the height could be avoided if buttons are on the same line somehow.
• Pages 1-4: Each question or response can only have one image, so having 2 or 3 images as in the mockup isn't possible. But you could have an image and a recording, so a better example might be having an image and an audio file.
• I would expect to see the missing file message in the label editing view already, i.e. page 6.
• Page 7-8: If users can attach a media file next to the label why would there still be a need for the other screen under the question settings?
• Page 9: The modal showing which file is used with which question is nice, but this could be overwhelming for some forms where a small number of files are used many times for some reason (e.g. if audio files are used to say 'yes' / 'no' in a particular language in hundreds of questions).

[Ig-Rebollo]

@tinok thanks for the feedback. Some notes for each point:

• I considered placing it in the same row, but the current design doesn't really work well with that set up (i.e. looks strange to have the upload media button on the right, but then the four question buttons even further to the right in a box. Placing it to the right might require a bit of a larger redesign of the form builder, as @magicznyleszek suggested before.
• Pages 1-4: Didn't realize of this. May I ask why? I might want to show a group of pictures for each question as in the example... though of course this is not very important.
• Page 6: Correct, this was a mistake on my part. It appear on this screen as well.
• Page 7-8: The setting screen was kept just for those users uploading from an excel file. They might need to keep managing file names so they link to the right upload.
• Page 9: Makes sense. Maybe then would be better to use the simpler modal type, the one from page 4

[Ig-Rebollo]

@tinok @jnm @dorey here is the latest version of the media upload feature in the form builder. As you can see in this animated flow, this design tries to accommodate three use cases:

1. User uploads files directly to the question or selection within question as it builds the form
2. User uploads a bulk of files to the project, and then links files to specific questions or selections within Q.
3. User builds the form in Excel, importing the file with the cascading select option. In this case file names are already in the excel file, and files will have to be uploaded to the project, linking automatically.

In the PDF version I included some additional mockups. For instance, the last slide shows what would happen in the case the form is created in Excel, imported with the file names in place, and finally the files are uploaded to the project, but either the file name is misspelled or the file is making reference to has not been uploaded yet.

Let me know if you have any comments, questions, or feedback!

[tinok]

@Ig-Rebollo This is looking better and better! Some quick question/feedback: Screens 2 and 3 don't completely make sense to me. Could the link and upload screens not be combined somehow (and therefore the link and upload buttons)?

Example: A question has no media but user wants to add media. A click on a single 'add media' button could bring up both the list of available media previously uploaded, as well as a way in the same screen (or a button to a different modal) to upload new media.

[Ig-Rebollo]

@tinok yes, this is the only tricky part. There are a few reasons I didn't combine those two buttons into one (and therefore one modal):

• Uploading media is both uploading and 'linking' directly to the question, while 'linking' is using files that have previously been uploaded to the project. I find these two things get a bit confusing, and placing them in the same modal might lead to more problems (i.e. if you upload a file into the question, some might think they also need to 'link' it afterwards, despite the fact that this would already be done automatically)
• It is generally a good idea to have these modals and windows as focused as possible, instead of trying to fit too many functions into one of them. Since I found those two functions (uploading and linking) to be clearly differentiated from each other, I made two separate modals.

Now, that being said, I also considered the possibility of having everything in the same modal, but with two separate tabs (one to upload and another one to link). This might work well... but may also need some additional clarifying text.

We can also do as you say and make everything look like the general 'import and manage files' modal, but then we would need to figure out a way to show that once uploaded to a specific question, a file would be: a/ linked to that question automatically (no need to do anything else) and b/ also uploaded to the overall project and therefore available to be selected in other questions

[Ig-Rebollo]

Some updates on this front @tinok @jnm @dorey. After the last call with Tino came up with a simplified solution that avoids having to use the 'Settings' section. Below some animations for you to see the process:

Upload files to a specific option of a multiple choice question:

Fix a file name that was placed in the XLS file beforehand, but due to a misspelling the file cannot be found from the files uploaded to the project. Note that there would be a warning on the question if the error was in a specific answer of a multiple selection question. This animation also shows how the 'upload to project' modal looks, at the end.

Finally how it would look uploading a file to a question, instead of a specific option within a question. Note that the thumbnail in this case would be visible in the question itself, unlike in the previous questions.

See screens in high def PDFs here

[tinok]

@Ig-Rebollo I think this is great, thanks for making the last round of changes!

I think we still need a help hint/link in the upload modal where users can click to learn more, right?

My only question is whether we would want to include 'File name:' in front of the file name here: For the value fields we preface it with 'Value:', so this would seem more consistent to me.

[Ig-Rebollo]

@tinok True same than for https://github.com/kobotoolbox/kpi/issues/2673, the help icon would be the circle with the '?'. In this case however I think it should be placed in the blue section, where the title is. Will add it to the mockups.

Regarding your question, I didn't include the 'file name' just to save space, but I agree, it might be better to include it.

[Ig-Rebollo]

@tinok @jnm @dorey added Tino's suggestions and created an online prototype on the Sketch Cloud. It doesn't have many options at the moment but I wanted to test how/if it works, so we can use a link as opposed to be sending PDFs:

Link to the prototype

Let me know what you think. We can add more paths and clickable spots for a broader user testing.

[tinok]

Thanks, @Ignacio - the prototype is very useful. More clickable paths would be great but not necessary, I think it's ok. For user testing it would be nice to start out with a regular form that doesn't have any media yet.

I found a small inconsistency: When a file is specified that is not yet uploaded (or wrong file name) then there are no context buttons; only the file name is displayed (with a 'file name:' prefix):

I would expect that the same buttons are displayed, though maybe preview might be grayed out, so that you're able to click the edit or delete buttons.