Fix usability problem for file template

Problem to solve

The templates picker UI is confusing and has usability problems due to double terminology used for example .GitLab-ci.yml templates.

See https://gitlab.com/gitlab-org/gitlab/uploads/5a5228d8850278508b9678898d7c3702/image__34_.png

Intended users

Devon (DevOps Engineer)

Further details

This problem has been surfaced through the baseline experience recommendations effort of 2019 Q2: gitlab-design#518 (closed)

User thoughts:

There is a template option with the same name which I can apply. It is not clear if it has been applied already yes or no. Though the file seems empty.

Apparently this is for choosing different template types... Are those immediately related to setting up gitlab-ci?

UX Proposal

See the prototypes in the Designs section of this issue.

• Move the dropdown for choosing a template Choose type next to the file name input field.
• Update the button labels, dropdown, and interaction as per acceptance criteria below:

Scenario 1: Acceptance criteria

1. User leaves the input field blank, and clicks the dropdown button. A dropdown displays a list of template types available.
   • The dropdown button should have the label updated from Choose a type to Select a type. Select means to carefully choose, so let's adapt the language here.
   • Remove the close button from the dropdown. We don't have this dropdown variation in Pajamas, and the fact that the user triggers a dropdown and a close option is available is odd. The default behavior of the dropdown is to be dismissed upon click anywhere outside the dropdown body.
   • Remove the Choose a template type dropdown header.
   • Once the user selects an option in the dropdown, the dropdown should close. The button label should remain Select a type. The input field should be populated with the template type selected. For example: .gitignore
   • Once the user triggers the dropdown again, the latest selection should be identified with a check icon placed in front of the item name.
2. After a type is selected, a new button should be displayed. The button label should read Apply a template.
   • Clicking the button should trigger a dropdown.
   • Remove the close button from the dropdown.
   • Remove the Apply a template dropdown header.
   • Fix the dropdown section header. Right now it is displayed in a small grey text, but we should display it in a bold, dark text. See Pajamas guidelines.
   • Once the user selects an option in the dropdown, the dropdown should close. The button label should remain Select a template.
   • Once the user triggers the dropdown again, the latest selection should be identified with a check icon placed in front of the item name.
3. After making the final selection, a TOAST component is shown to display the system message, replacing the inline message.

Scenario 2: Acceptance criteria

1. User enters .gitignore in the input field, before choosing a template type.
2. gitignore should be then selected in the first dropdown menu (choose type). The Apply a template button is shown.
3. The Apply a template dropdown is filtered by the templates that match the previous type selected.
4. After making the final selection, a TOAST component is shown to display the system message, replacing the inline message.

Click me to collapse/fold the first proposal.

- Move closer to the 2019-08-30_00.15.55 and consolidate towards one button for template picking. - It should be positioned next to the file name input like so: . - This will make the template picker UI always available regardless of the file name. - The dropdown search will be prefilled with the file name, so the search immediately filters the dropdown results to what is most interesting. - The default dropdown results will now be named for example `.GitLab-ci.yml - Docker` - image should be retained but can be made a default tertiary button instead of an info button similar to the Web IDE.

Permissions and Security

Documentation

Testing

What does success look like, and how can we measure that?

Links / references

added UX debt UI polish devopsverify + 1 deleted label

marked this issue as related to gitlab-design#518 (closed)

added UX label

mentioned in issue gitlab-design#518 (closed)

changed milestone to %12.4

added 1 deleted label

added [deprecated] Accepting merge requests label

added Category:Continuous Integration label

Setting gitlab-ce~10690708 based on ~"Category::Continuous Integration".

added grouppipeline execution label

mentioned in issue ux-research#330 (closed)

@dimitrieh - I'm cleaning up ux debt labels to reflect issues that emerged from a previous issue that wasn't correctly implemented. Is that the case here? If so, should we link to the previous MR in the description?

@clenneville . I will for now remove that label.

removed UX debt label

assigned to @dimitrieh

@dimitrieh are there any more specifics on the proposal available here?

See https://gitlab.com/gitlab-org/gitlab-ce/issues/65842#note_210150033

removed [deprecated] Accepting merge requests label

added frontend label

@pburdette can you please take a look at this issue for %12.4. Thank you!

@pburdette This can potentially touch two places (image and image), though for this issue's scope we will focus on the web file edit header UI only.

The web ide is not yet part of the default flow of creating/editing a GitLab-ci.yml file.

---

In terms of a potential solution, the problem originates from incorrect IA and interaction options:

• .GitLab-ci.yml is shown all over the place, without it making clear what UI relationship they have.
• The template picker is placed above the file name
• The template picker UI consists out of 2 dropdowns and which

Because of that, I would like to:

• Move closer to the 2019-08-30_00.15.55 and consolidate towards one button for template picking.
• It should be positioned next to the file name input like so: .
• This will make the template picker UI always available regardless of the file name.
• The dropdown search will be prefilled with the file name, so the search immediately filters the dropdown results to what is most interesting.
• The default dropdown results will now be named for example .GitLab-ci.yml - Docker
• image should be retained but can be made a default tertiary button instead of an info button similar to the Web IDE.

@pburdette I would love to get to know what you think in terms of feasibility. I have the feeling we might be conflicting or altering some existing functionality which I haven't thought of yet.

cc: @vkarnes @jlenny

assigned to @pburdette

added Deliverable label

changed the description

@dimitrieh I've been working on this some and this is what I have so far! It seems the issue template picker has just one set template for whatever the user happens to choose. Where as if a user chooses a .Gitlab-ci.yml template they have many templates to choose from. I'm curious about what you think the best way to achieve this with one button would be?

I think I believe you are wanting to get rid of the step to choose a template type and rely on the template type from the filename?

The screenshot below shows the same two button step moved beside the filename input (styles aren't finished yet)

Screen_Shot_2019-08-30_at_10.04.02_AM

cc: @jhampton

Thanks for the great info @pburdette!

@pburdette

I think I believe you are wanting to get rid of the step to choose a template type and rely on the template type from the filename?

That is correct. The user will be able to choose any template they want, but the list will already be filtered down to what the filename represents.

The screenshot below shows the same two button step moved beside the filename input (styles aren't finished yet)

This seems like a step in the right direction! What is your next move? :)

@dimitrieh thanks for clarifying! Next move will be capturing the input value from the filename and using that to determine the dropdown value.

@dimitrieh MR is open here.

I've got everything working right now except having the dropdown default with Docker. Working on that...

What color do you want the Template applied text to be? Keep it blue?

Still working on styles. The width of the inputs need to change for it to work well on one line. The screenshot shows the filename input at 200px and the template picker is at 250px

@pburdette

What color do you want the Template applied text to be? Keep it blue?

Are you able to convert this to a toast instead, including the undo action? A component should be ready for use I think

The width of the inputs need to change for it to work well on one line. The screenshot shows the filename input at 200px and the template picker is at 250px

Can you show me what you mean with a screenshot? If need be we can broaden the dropdown menu! And I would welcome broadening the file name input as well.

If possible, can you make it so that the review app is available in https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/32717 so I can play around with it?

@dimitrieh Here is a video of the current UI. I need to fix the pipeline errors for ruby tests before the review app will show up for you.

video

Thanks for showing @pburdette, great progress already!

I have a slightly different idea as to how the filename influences the dropdown. Forgive me if you are already working towards that.

• The dropdown label to be static Choose a template
• The dropdown menu search field will be auto-populated with the filename filtering the menu results automatically to the ones that make sense for that file type.
  • In theory, you could apply any known template to any file that way if you adjust the search field input value.

Let me know if that corresponds with your thinking.

@dimitrieh Is this your thinking?

• The dropdown for choosing a template, always shows with Choose a template.
• The dropdown results will have templates for any file name?
• If we have templates for a particular filename, the dropdown menu will then filter automatically to only show templates for the filename?

Jumping into this discussion to help out while @dimitrieh is OOO.

From reading the previous comments, here's my input for the next steps @pburdette. Please review the acceptance criteria below and let me know if there's anything that needs an update.

Scenario 1

1. User leaves the input field blank, and clicks the dropdown button. A dropdown displays a list of template types available.
   • The dropdown button should have the label updated from Choose a type to Select a type. Select means to carefully choose, so let's adapt the language here.
   • Remove the close button from the dropdown. We don't have this dropdown variation in Pajamas, and the fact that the user triggers a dropdown and a close option is available is odd. The default behavior of the dropdown is to be dismissed upon click anywhere outside the dropdown body.
   • Remove the Choose a template type dropdown header.
   • Once the user selects an option in the dropdown, the dropdown should close. The button label should remain Select a type. The input field should be populated with the template type selected. For example: .gitignore
   • Once the user triggers the dropdown again, the latest selection should be identified with a check icon placed in front of the item name.
2. After a type is selected, a new button should be displayed. The button label should read Apply a template.
   • Clicking the button should trigger a dropdown.
   • Remove the close button from the dropdown.
   • Remove the Apply a template dropdown header.
   • Fix the dropdown section header. Right now it is displayed in a small grey text, but we should display it in a bold, dark text. See Pajamas guidelines.
   • Once the user selects an option in the dropdown, the dropdown should close. The button label should remain Select a template.
   • Once the user triggers the dropdown again, the latest selection should be identified with a check icon placed in front of the item name.
3. After making the final selection, a TOAST component is shown to display the system message, replacing the inline message.

Scenario 2

1. User enters .gitignore in the input field, before choosing a template type.
2. gitignore should be then selected in the first dropdown menu (choose type). The Apply a template button is shown.
3. The Apply a template dropdown is filtered by the templates that match the previous type selected.
4. After making the final selection, a TOAST component is shown to display the system message, replacing the inline message.

I have added the prototypes to the Designs section in this issue.

fyi @vkarnes @dimitrieh

@rverissimo this is so helpful. Thank you for taking the time to write this out. I'll be sure to let you know if I run into anything while building this out.

@pburdette Great! Let me know if you need my input or ux review in your merge request! I've also updated the issue description with this acceptance criteria

@rverissimo thanks for updating this issue for me. Is it correct, you intend for the 2 dropdowns to remain as a selection mechanism?

I am wondering about this as my intention was to move towards a single dropdown for selecting in order to speed up and simplify choosing templates.

@pburdette your thoughts and feedback regarding any progress are welcome too

Ohh, it wasn't clear to me you wanted to keep one dropdown. What I understood was that you wanted the dropdowns to function two ways: pre-populating the input field, and filtering the second dropdown selection; and filtering the dropdown selection depending on the file name entered in the input field.

This is what I added to the scenarios above, but I see what you mean.

How would the selection work with a single dropdown? Can you use this prototype as a baseline and exemplify your flow?

#30807[scenario-1_file-template.png]

I've got the new prototype implemented here. A single dropdown to handle template selections gets a little tricky. Because the amount of templates returned for a single template type. Also the API doesn't currently have a way for returning all templates for any type. We would still have to rely on a first step in the process of choosing a template if we moved to one dropdown.

@pburdette thanks for the explanation! Let's work with the 2 dropdowns in that case for now. I will review the merge request with the requirements as detailed in #30807 (comment 219553937) for now.

---

@pburdette As a last stab at unifying the 2 dropdowns but also to fit the limitations we have to work with:

Would it be possible to merge the two dropdowns into one with a tokenfield? https://sliptree.github.io/bootstrap-tokenfield/

The field would always continue to display template text similarly to https://sliptree.github.io/bootstrap-tokenfield/. Though the template text changes depending if a template type has been already selected yes or no.

The dropdown results will also change depending if a template type has already been selected. If it has not, the dropdown will only feature template type selections. If it has, the dropdown will feature only templates based on that template type.

If a template type is selected, a token will show up like depicted in the following mockup. Similarly to the flow right now, if the file name field is filled with a known template type name, the template will be autoselected.

The flow would look like this:

1. No template type selected yet
2. Selecting a template type (note mock data)
3. Template type applied. Copy changes to Apply a template
4. Selecting a template, if applied no additional token is rendered and the text will continue to read Apply a template.

Hey @dimitrieh as of right now we should either go with what I've done or hold off on this until https://gitlab.com/gitlab-org/gitlab/issues/26611 is complete. Right now a lot of that functionality is built into ruby and we have an open issue to move it over into a Vue component.

@pburdette let's go for what we have now. I'll open up an issue with this solution if need be after we have merged the current solution.

added 1 deleted label and removed 1 deleted label

Hey @dimitrieh when we have our meeting to discuss the button component changes, I'd love to ask a few questions about this issue. There are a few new use cases that are present that I'd like to hear your input on usability and the right route to go. Speaking of that meeting I don't believe @shampton or I actually got the scheduled invite? Thank you!

@pburdette if you meant the meeting on skeleton loaders, i just got that scheduled. Very strange, because I thought I already had.

changed milestone to %12.4

mentioned in issue gitlab-foss#65842 (moved)

changed the description

mentioned in merge request !17522 (merged)

closed via merge request !17522 (merged)

mentioned in commit 37a7dd8e

marked this issue as related to ux-research#330 (closed)

reopened

closed

reopened

mentioned in merge request !19376 (merged)

closed

mentioned in issue #38034

mentioned in epic &2226 (closed)

added to epic &2288 (closed)

added 1 deleted label

added UX scorecard-rec label

removed 1 deleted label