!!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?!!
=====When Update completes...
When the Update completes, the following things happen:
- **The On-Page Message** shows a new timestamp corresponding to the completion time of the Update.
- **The page refreshes **and onscreen metrics update to show new values.
- **The Update button, Download button/menu, View Edit List button ** return to their available state.
=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--defined in T205502
- **Download CSV** commences download of the comma-delimited file, as defined in T205363 and T206058