Convert partner profile to step-wise form

[cielf]

Summary

We want to rework the partner profile into a step-wise form, with error checking at each step.

Reasoning

The current form is very large and intimidating enough that it is a barrier to entry for the partners -- or the banks have to fill it in for them. Breaking it up into bite-size chunks will make it easier for the partners to deal with.

Details

This applies to both the partner and bank edits of the form (partner: partners/profile/edit bank: profiles/[partner #]/edit)
See concept below. Expand it for each of the 'cards' in the current partner profile edit forms. At each "save and next", we would want to be able to check the 'local' fields and display any relevant errors. The partners will also need to be able to "Submit for approval", which will check the whole thing, and, if ready, set the status to indicate that it is ready for approval.

Please note:
1/ Several of the cards can be enabled/disabled by the bank in their organization edit (sign in as org_admin1@example.com, "My Organization", click on "Edit" -- the field to look at is: "Partner Profile Sections"). If the card is not available, it should not appear in the "accordion".
2/ The user should be able to navigate to any of the available sections at will.
3/ Intermediate results (at save and next) will need to be saved, possibly over days

Criteria for completion

• ability to navigate the partner profile form for partners, as described above
• ability to navigate the partner profile form for banks, as described above
• replacement of current system/request tests with tests that support the above
• addition of automated tests for the new functionality above

[cielf]

Reserved for @danielabar -- who is fully briefed and interested! (let's say reserved until September 1)

[danielabar]

This is on my radar. Planning to complete partner request confirmation, then will turn my attention to this.

[danielabar]

Now that partner confirmation is done, I could start on this.

[cielf]

Please do!

[danielabar]

Started. Looking into Accordion component to handle expand/collapsible sections.

[cielf]

bringing @dorner into the loop for any early technical guidance.

[danielabar]

This might be simpler than a typical step-wise form in that the underlying model Partners::Profile has already been created by the time an invited partner is filling out the form. Also, very few of the fields are required, and those that are, have default values. This means we don't need to worry about storing form values temporarily in session, they could be saved as the user goes through each section.

Each collapsible section could be a form that submits to the same app/controllers/partners/profiles_controller.rb#update action that is already in use today. The difference being a smaller subset of the permitted params would be incoming.

A complexity could be that on any given "subset" update (i.e. where user clicked Save & Next), we wouldn't want to redirect them to the show view redirect_to partners_profile_path from a successful update, but rather, take them back to the edit view so they can continue. And in this case, it would be nice to know which collapsible section to have open. Although if they can go in any order, maybe this isn't determinable.

Possibly a different action button is needed for user to indicate something like "Save and I'm done with all this", or is that the "Submit for Approval" button?

[danielabar]

It would also be good to clarify how the sections from the current form should get split up? For example, is each existing "card" from the current form to become its own collapsible section?

There is an existing partial for Agency Information, but it also includes Program Delivery Address, which is not shown in the mockups. Should Program Delivery Address be another collapsible section?

[cielf]

Yes, each card should be a step. Program delivery address was moved to its current location after I made up the mockups. (Recall also that the presence of most of the cards is controlled at the bank organization level)

Submit for Approval, in addition to saving, changes the status so that it appears on the banks list of partners to approve.

We'll likely want to make more fields conditionally mandatory (definitely not for this issue) as we go on.
@dorner - What do you think of the approach @danielabar described above?

[danielabar]

Haven't had as much time to work on this but it's still on my todo list. Just wanted to post an update that it is possible to programmatically target the Bootstrap accordion sections whether they should render as expanded or collapsed.

Expanded

• button does not have collapsed class
• button has aria-expanded="true"
• content section has show class

<div class="accordion-item">
  <button class="accordion-button"... aria-expanded="true">
  <div class="accordion-collapse collapse show">
  ...
</div>

Collapsed

• button has collapsed class
• button has aria-expanded="false"
• content section does not have show class

<div class="accordion-item">
  <button class="accordion-button collapsed"... aria-expanded="false">
  <div class="accordion-collapse collapse">
  ...
</div>

[danielabar]

Tricky part may be on each given save of a section, determining which is the next section to render as expanded (and to ensure all the others are rendered as collapsed). It looks like there are 3 static (i.e. always shown) sections, with a number of dynamic sections in the middle (only to be shown if the partner has been configured as such).

Something like this:

n: loop over current_partner.partials_to_show
k: last

1. STATIC, DEFAULT EXPANDED partners/profiles/step/agency_information_form
2. STATIC, DEFAULT COLLAPSED partners/profiles/step/program_delivery_address_form
n. DYNAMIC, DEFAULT COLLAPSED partners/profiles/step/{partial}_form
k. STATIC, DEFAULT COLLAPSED partners/profiles/step/partner_settings_form

[cielf]

Okay, I definitely need input from the rest of the senior team now -- I don't currently have the technical chops to make some of these judgements. I've slacked them asking them to look at it, and am slotting it in for discussion in our Sunday planning meeting.

[danielabar]

@cielf My latest branch has the following changes:

1. Removed scrolling to open section.
2. Using morphing and preserve scroll position to make the transitions less "jumpy".
3. Replace the open/close caret icons with Saving... during form submission. At the moment this only happens on the caret icon clicks.

It's not the same effect that would be from a pure SPA because it still does round trip to server to render the page, but let me know if it's "smooth enough"?

[cielf]

Hey @danielabar -- If one is viewing it at a size where the collapsed form fits on one's screen, it's pretty good!

I want to get some fresh eyes on it re whether the behaviour when you're working with a larger font and hence, have to scroll to get down to the lower bits of the screen is workable. (I don't see the scroll position being preserved in that case.)

Let me show it to / talk with the rest of the senior team tomorrow.

[danielabar]

@cielf In the meantime, I'm continuing to investigate options.

That scroll preservation meta tag mentioned in the Turbo docs:

<meta name="turbo-refresh-scroll" content="preserve">

I was trying to dig through some of the turbo-rails code to understand why it wasn't working. I think it only works in co-ordination with turbo frames.

So I attempted to wrap each form in a turbo-frame. In this case, it did preserve scroll position and had a very smooth effect, even on smaller screen sizes. However, it broke other things including:

1. Clicking "Save and Next" button no longer closes current section and opens the next section
2. Validation no longer renders (it rolls back the changes but doesn't inform user that something went wrong)
3. The newest logic I added to show "Saving..." instead of the open/close caret icons gets stuck in the "Saving..." display, even after save is finished.

There are a number of different options for turbo frames, I've been experimenting, some of them fix one thing but break something else, so this will require further research.

It still might be worth confirming with some user interviews (if possible) - whether most users expect the form data to be saved on the caret icon clicks. If this is not the case, this feature could be simplified by only saving the form data on the "Save and Next" button click.

[cielf]

@danielabar Ok.... We had a significant discussion in the planning meeting, and have decided to pull out of the automatic save / save and next paradigm as too cumbersome. I do apologize for taking you so far down the current road. I hope you learned some good stuff! I do appreciate your willingness to try to make it sing in the original way.

So... here's the new preference, which we think will be much simpler:, and hopefully easier to implement.
1/ "Save progress" and "Submit for approval" buttons at the top and the bottom
2/ No "save and next"
3/ You can have multiple sections open at once (so opening does not close the other sections)
4/ When you attempt to save, but have errors, all the sections that have errors will open.

We tossed around ideas like showing the errors in the subforms, and/or putting a red X in the header of those, but I think, at least for the current iteration, let's just show them up top.

(Note: I would keep the bit where we say "saving" when the save is happening, if it's not a lot of trouble)

Does that sound workable?

[danielabar]

@cielf To clarify, we're going to remove the form submission behaviour from the bootstrap open/close caret icon clicks?

i.e. the only way to save form data is to click the "Save Progress" button?

Also re:

4/ When you attempt to save, but have errors, all the sections that have errors will open.

Given that only one form can be submitted at a time, I don't think it could ever happen that more than one section would be in an error state.

[danielabar]

@cielf Being able to open up multiple sections at once opens up a new scenario.

Suppose user fills in a section, submits, and server sends back an error response, for example, Media Information:

Now user can ignore this, open up any other section, for example, Organizational Capacity, fill it in and submit:

Since each of these are separate forms, what would happen currently is the error state would be cleared from Media Information and it would save Organizational Capacity. Pretty much as if user had navigated away from the page and submitted any other form.

Is this ok?

Or if not, should all other submit buttons be disabled if any section is in an error state. This would mean user has to fix the error to move on.

[dorner]

@danielabar we are suggesting that there should only be a single form encompassing all sections.

[cielf]

(nods) It does mean that when someone saves, they are are going to have to provide media info. Luckily, that's among the easiest bits of information to lay one's hands on.

[danielabar]

@cielf @dorner Sorry for all the clarification questions, just want to be sure on the UI since we're no longer working from original mockups. re:

1/ "Save progress" and "Submit for approval" buttons at the top and the bottom

Since it's now just one big form, does this mean these buttons should appear outside of the collapsible sections at the top and bottom of the overall accordion? Or at the top and bottom of each accordion section?

For now I've updated it with the buttons appearing at the top and bottom of the accordion, does this look ok?

[cielf]

That looks good to me.

[danielabar]

Status update:

1. All the accordion sections are now part of a single form.
2. Action buttons (Save Progress and Submit Profile for Approval) appear only at the top and bottom of the entire accordion section, no longer within each section.
3. User can open and close as many sections as they'd like at a time. There is no server-side behaviour associated with this so the effect is "smooth".
4. If Save Progress is clicked and profile update is successful, user is returned to edit form with all sections closed. The attempt to remember where they were and open next section has been removed, as per earlier discussion.
5. If Save Progress is clicked and profile update fails due to validation errors, user is returned to edit form with all sections that have error(s) opened.
6. When Save Progress is clicked, all the bootstrap open/close caret icons are disabled and replaced with "Saving...".

Notes:

• I had to modify some of the profile validation because some rules were setting the error at the :base level, which would make it impossible to know which specific field is in error. All of these changes are behind a feature flag.
• If a checkbox is in an error state, it doesn't render as such, I believe this is existing behaviour, possibly because there is no specific checkbox error styling in simple form bootstrap.

TODO:

• Feature tests (now that intended interactions are finalized)
• Remove no longer used code from initial solution (re: individual form submissions for each section and jumping to next section in sequence)
• Refactoring

[cielf]

Thanks for the update!

[cielf]

Hurrah!