!!THIS TICKET IN PROGRESS. DO NOT READ YET. !!
When users Update date or Download reports, an intricate dance takes place among various back-end processes and interface elements. This ticket describes that dance and the elements and processes involved.
=Background: understanding 'Updating', 'Fetching', and timestamps
This section describes the Grant Metrics system that already exists, more or less. I'm taking time to codify and document it here so that, as we make it more complex with more reports produced, we can all use the same terms and ensure that the UX is consistent and understandable.
- **'Updating' defined:** for our purposes, Updating is the process of finding new page IDs and calculating/looking up only the top-line figures presented in the Event Summary report. Updating, in other words, does not cause all metrics in all reports to be newly assembled or calculated. Updating is triggered when the user clicks the Update button or requests a report (unless an update occurred during the caching period—see below). Updating causes the system to display a new timestamp.
- **'Fetching' defined:** Fetching is the more limited process of calculating or retrieving metrics without gathering calculating the Event Summary figures or, crucially, retrieving ew page IDs. Data is Fetched using page IDs from the last Update. For this reason, Fetching does not cause the timestamp to change; the timestamp remains that of the last Update.
- **Triggering Update vs. Triggering Fetch: ** Fetching and Updating often occur together, as when a user requests Download of a report that has not been Updated in a while. But there are two cases when Fetching occurs without Updating: when 1) a report is requested during the Caching period (see below), or 2) when the user visits the Edit List page (see below). In these cases, the data is fetched based on the existing page IDs.
- **Making sure Fetched data matches the timestamp:** Because the page IDs in a Fetch come from the last Update, Fetching on its own does not cause the timestamp to update. This creates the potential for the metrics to be out of synch with the timestamp. The Edit List, for example, would track only those //pages// that existed as of the last timestamp, but it could show //edits// that occurred after the timestamp. To prevent this mismatch, metrics in Fetched reports will be cut off at the timestamp (either not looked up or not presented, whichever is easiest). This change to the Grant Metrics update process is described in !!ADD TICKET NUMBER HERE!!.
- **The Caching Period: **As a general rule, Updates are triggered by 1) clicking the Update button or 2) Downloading a report. Not all download requests trigger an update, however. There is a Caching Period of approximately 10 minutes during which data is deemed to be still Fresh. During that period, requesting a report will trigger a Fetch only, and the timestamp will not be updated.
- **Visiting the Edit List page:** The edits that make up the contents of the Edit List page are not stored, so must be Fetched when the user visits. Visiting the Edit List page in itself, however, will not trigger an Update. This behavior is defined in T213498.
- !!If the user __clicks the Update button__ during the approx 10-minute interval after a previous update, during which all data is deemed to be still "fresh," a) the system goes into the "Updating" state (see below) and b) the dateline is refreshed for all data. !!
=The Updating and Downloading sequences
There are three possible states of the updating and download system: Available, Updating, and Fetching. It's important that the UI keep the user informed of the system's current state, especially as some processes might last for a considerable period. We will do this by managing the appearance and behavior of the following 5 elements: the Update button, the Working indicator, the Download Button/Menu (all defined in T206576), as well as the On-Page Message and the View Edit List button.
|**Screen shot of the Update Button with Working Indicator showing, the Download Button and the On-Page Message** |
|{F27855938 width=400}|
The sections below specify how each of these elements will behave and appear in each of the three Update States. See designs below.
==='Available' state
In this state, Update and Download are available. This is the default state.
- **Update button ** is blue and turns a darker shade of blue on hover; clicking will initiate update.
- **The working indicator** is not visible; no work is progressing.
- **On-page message:** "Last updated 2018-10-29 18:49 (Africa/Accra)" [The date, time/ timezone of the last update. Note: this is the existing message]
- **Download menu:** is available.
- **View Edit List button** is clickable; it shows its normal color and turns a darker shade of gray on hover.
==='Updating' state
When the user initiates update by clicking the button or downloading a report, the Update state commences.
- **The 'Working" indicator** shows, as specified in T206576
- **Update button: **the button is grayed out and unavailable
- **On-page message:** Please wait, currently crunching the numbers.... [Note: this is the existing message]
- **Download button/menu:** is grayed out and unavailable
- **View Edit List button** is grayed out and unavailable
- **If the user leaves the page during update** the user may navigate to another page or Web site—or close the browser entirely. The Update process will continue. When the user comes back to either the Edit Summary or Edit List pages, the process will either still be running (and the appropriate messaging displayed) or Update will be complete and the new timestamp shown.
- **If the user had requested download of a report, ** she will have to request the report again. I.e., it will not begin automatically downloading. !!@MusikAnimal, what will happen to any Fetch process that was initiated? Will it run its course or terminate?!!
==='Fetching' state
Fetching is always caused by a Download request.
- **During Fetch—no UX difference** During Fetch, most front-end, UX elements appear and behave exactly as they do during Updating. (The differences are on the back end: the Event Summary figures are not calculated and new page IDs are not gathered).
- **After Fetch—the timestamp (possibly)** The only visible UX difference between a Fetch and an Update occurs after the Fetch completes: strictly speaking, Fetch does not cause the timestamp to refresh. HOWEVER, the Fetch state is often combined with an Update, making this difference moot in such cases. See below, under **When Fetch Completes**, for the possible variations.
=After Update/Fetch completes
The sequence of events that occurs after Updating and/or Fetching varies slightly depending on what initiated the processes. There are three possibilities.
# **Update with NO Fetch.**
# **Update WITH Fetch.**
#** Fetch with no update.** Happens when the user downloads a report after a recent Update, when page ID data is fresh and in the cache.
===#1 Update with NO Fetch
Caused by clicking the Update button on the Event Summary page. When the Update completes, the following things happen:
- **The page refreshes **and onscreen metrics update to show new values.
- **The On-Page Message** shows __a new timestamp__ corresponding to the completion time of the Update.
- **The Update button, Download button/menu and View Edit List button ** return to their available states.
===#2 Update WITH Fetch
Caused by requesting Download of most reports—unless the data is fresh and still in the cache—or by clicking Update on the Edit List page. When the Update/Fetch process completes, the following things happen:
- **Everything is the same as #1** All UX elements behave and display as above, plus
- **The requested data is provided** the system either shows the Popup Selector (as in T206576), so the user can select a format for the report, or the Edit List page displays a new Edit List.
===#3 Fetch with no update
Happens when the user downloads a report after a recent Update, when page ID data is fresh and in the cache. When the Fetch process completes, the following things happen:
- **The page dos not refresh** on-page data remains as it was
- **On-page message** returns to the timestamp, which remains that of the __last update__ (i.e., the timestamp does not update).
- **The Update button, Download button/menu and View Edit List button ** return to their available states.
- **The requested data is provided** the system shows the Popup Selector (as in T206576), so the user can select a format for the report.
=Getting the files
When the user makes her selection, behavior is the same as for the existing Grant Metrics reports. Which is to say
- **Get Wikitext:** pops open a new tab that presents the wikitext of the table (e.g., T205502, T210898, T206692)
- **Download CSV** commences download of the comma-delimited file (e.g., T206058, T205561, T210775)