!!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.
- **Fetching, the timestamp, and not showing new data** 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 !!ADD TICKET NUMBER HERE!!.
- !!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 sequence
There are essentially two possible states for the Update button and download menu: "Available" and "Updating."
==='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.
- **On-page message:** "Last updated 2018-10-29 18:49 (Africa/Accra)" [The time and date of the last update. Note: this is the existing message]
- **Download menu:** is available.
- **View Edit List button** is its normal color and turns a darker shade of gray on hover. It is available for noavigation
==='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 T207776
- **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
- **Leaving the page:** During Update the user can navigate to the Setup Page or to another Web site—or close the browser entirely. When he comes back to the Edit Summary page, the process will either still be running (and the appropriate messaging displayed) or Update will be complete and the new timestamp shown.
===When Update completes...
When the Update completes, the following things happen:
- **The "Working" indicator** (T207776) disappears
- **The page refreshes **and onscreen metrics update to show new values.
- **The on-page message** refreshes to display the timestamp as of update completion.
- **The Update button** returns to its available state.
- **Download button/menu** returns to its available state.
- **View Edit List button** returns to its 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