Spike: How to consolidate code/UX flow of clicks on Search and Detail pages

[wesrowe]

Description

As a Veteran, I want to have the same experience downloading a PDF regardless of whether I'm on the Form Search or Form Detail page so that I trust the experience.

As a Find-a-form maintainer, I want the code to be the same for downloading a PDF across the Form Search and Form Detail pages so that it's simpler to maintain high quality.

Background

In #10509 we discovered that code (all in vets-website) is very different across Form Search and Form Detail pages when the user clicks a "Download PDF" link. The two flows are documented in this Mural.

Key differences:

• Modals (driving use of Adobe Reader) are different visually, as one has a button and the other has a link for the actual download action.
• The JS that runs on click has several "extra" API calls on the Form Detail page, and these are the ones that break download functionality when the Forms API is down.

We want to re-use the same code such that a download click on either page type (Search or Detail) leverages the same JS and UI code, thus delivering an identical experience to Veterans.

Things to identify the better version of:

• Modal UI (the one with the button)
• Simpler JS logic (e.g., no extra API hits)
  • Note: we don't care about the 24-hr cookie logic around the modal display, we plan to remove that logic completely
  • No extra API calls
  • No pre-fetch of the file HEAD

Another Key question – Error Alerts There is currently an Alert UI component that sometimes displays when a download fails (the one with a mailto link for Forms Mgr).

• Is this alert only triggered by Form API latency/failures?
  • If Yes, this means that the alert really only indicates the API has issues, not that the form itself has issues.
• Is there a way to trigger an alert when an actual PDF download from its server fails? Would that event be available to our javascript?

Acceptance Criteria

• [x] Document results of "things to identify" investigation above
• [x] Create ticket(s) for implementing recommended changes
• [x] Schedule call with Wes, Ryan, Bryan, Josh (optional), Jill to review findings

CMS Team

Please check the team(s) that will do this work.

• [ ] Program
• [ ] Platform CMS Team
• [ ] Sitewide Crew
• [ ] ⭐️ Sitewide CMS
• [x] ⭐️ Public Websites
• [ ] ⭐️ Facilities
• [ ] ⭐️ User support

[jilladams]

Goal: assess & propose API calls next steps, specifically.

[dsasser]

Spike Recommendations Summary

The spike details recommendations for each goal below, and are summarized here for convenience:

• Modal design consolidation - #10850
• Create and use a Form Download Links component - #10851
• Remove runtime form validations (if allowed) - #10235
• Create and use a single modal component -
• Remove modal cookie behavior - #10524
• Maintain existing GA event triggers

Code Reuse

Code reuse options are currently limited due to how the two page types’ "components" are built. The detail page leverages bespoke javascript via a javascript widget injected into the detail pages. The widget adds a click handler for each download link in the DOM.

The search page uses a set of react components driven by state produced by the forms data retrieved during content release.

Code Reuse Recommendations

Modal consolidation - #10850

Moving the modal to a single, reusable component shared amongst both page types will drastically reduce modal-related technical debt, and provide optimal code reuse.

React-ify All Form Download Links - #10851

Move to a single react component for both page types. This would be a bit of a refactor for the detail pages and the respective liquid template structure. However, this presents the best approach to reuse and technical debt. (this concept needs FE review)

Lift: Medium to Large

Better UX

Current UX Challenges

The UX presents several challenges in current form:

Forms validation checks are problematic

Runtime form validations exist for detail pages. Both of them require network requests and they can prevent downloading a valid PDF, depending on responses. As currently written the validations occur without UI updates, and can delay the download for as long as the network request elapses. Having experienced Forms API degradation and outages recently brought the previously unknown issue to the surface. This issue is imperceptible on quality broadband internet connections during low latency Forms API performance, but reveals itself quickly if either of these is degraded.

PDF Guidance modal inconsistent

The modals used for PDF guidance between page types have an inconsistent design. The search page modal uses a download link whereas the detail page uses a download button. The detail page design is the preferred design.

PDF Guidance modal is visible only once per 24 hours - #10524

The cookie prevents firing of the PDF helper modal consistently. The modals, despite being unique components on both page types, only display once per 24 hours.

UX recommendations

Form Validations

Form validations present challenging UX scenarios to solve for, and cause additional network traffic on the client side. As such, it is recommended to remove these ‘runtime’ form validations should they not be determined as required. However, if that is not possible, validation recommendations are presented below.

The first recommendation is to consolidate to a single form validation method, using the “HEAD prefetch” method. This method is a lightweight client-side callback that retrieves the HTTP headers from a request for the filename–meaning that the file itself isn’t downloaded, but just enough information to know if the file would be delivered if a download was attempted. However, due to current CORS limitations, this method is only capable of firing for PDFs hosted by va.gov. To overcome this, the va.gov domain needs to be added to the HTTP response Access-Control-Allow-Origin header property. So the bulk of the work to achieve 100% coverage with this validation will be in working with forms admins and their developer/IT resources.

The validation should would be non-blocking (any failure or delay will not prevent the user from attempting to download the file), and provide UI feedback. This would likely require rearchitecting the validation code to suit these requirements. UX research and design may be necessary to realize a quality experience that also produces the necessary validation.

PDF Guidance

Consolidate both modals into one component. The design from the detail page (the one with the download button) should be used. #10850 Remove the cookie logic, and instead always toggle the modal immediately. - #10524

Lift: Large

Logging

If runtime form validation is NOT required: Consider removing sentry logging calls, as were used for flagging runtime errors, and therefore no longer relevant. - #10235

Maintain existing GA analytics event triggers with opening/closing of the modal and link click events.

If runtime form validate IS required: consolidate sentry logging to reflect changes to validations from above, whereby we remove all but one validation. This will allow for more directed information to the user and for our analysis purposes. - #10236

[dsasser]

Tickets created: https://github.com/department-of-veterans-affairs/va.gov-cms/issues/10524 https://github.com/department-of-veterans-affairs/va.gov-cms/issues/10235 https://github.com/department-of-veterans-affairs/va.gov-cms/issues/10236 https://github.com/department-of-veterans-affairs/va.gov-cms/issues/10850 https://github.com/department-of-veterans-affairs/va.gov-cms/issues/10851

[jilladams]

@dsasser My questions:

1. 10235 & #10236 are written as dependent on this, and findings sound like we would go ahead with both if we're allowed. Just confirming that's true?

2. Re: determining whether we're allowed to remove the runtime events: the most efficient way to work that out will be to identify the code that implements the check, git blame, and find the tickets, and review who the decider was at the time/factors that went into it. If you can point me to the code in question, I can chase the paper trail.

I went through your comment and added the ticket links for the work described, to make sure we're clear on the tradeoffs / if-thens. Take a look and make sure I connected the dots correctly?

I do think the meeting to review would be helpful.

[dsasser]

... and findings sound like we would go ahead with both if we're allowed. Just confirming that's true?

Correct, the recommendation is to go ahead and remove both the API and HEAD fetch calls, if allowed.

...whether we're allowed to remove the runtime events: the most efficient way to work that out will be to identify the code that implements the check, git blame, and find the tickets

This commit introduced the PDF Download Guidance logic for the Form detail pages which includes both API and HEAD calls on download click. And here is the related PR.

I went through your comment and added the ticket links for the work described, to make sure we're clear on the tradeoffs / if-thens. Take a look and make sure I connected the dots correctly

The links look correct to me, thanks for doing that.

[jilladams]

From discussion with Dave/Wes today:

• improving the site to remove API calls that are only problematic when vets-api fails is not the right motivation, so that work is not a priority for us right now (in Q4). Rather: need to apply pressure to Platform team to stabilize vets-api.
• Consolidating the modals may be something we can do but: if it requires design, it's not a top design priority for Q4 given the recent design staffing changes, and Dave would rather the decision be driven by data that proves one version of the modal is more effective than the other.
• re: permission to remove fetching HEAD: Pre-dates Dave but he suspects that it had something to do with detecting digital signatures. (Need to clarify if there's a next step here.)