!!THIS TICKET IN PROGRESSWhen users Update and/or Download metrics, an intricate sequence of events transpires among various back-end processes and interface elements. This ticket describes the functionality and behavior of the interface elements that control and reflect the status of the back-end processes.
NOTE: In order to describe the UX under discussion, I've had to abstract the back-end processes of Event Metrics and invent terms for them. The overview of that abstract "system"—which mostly matches Grant Metrics' current behavior except where noted—is defined in T213136. DO NOT READ YET.Because the present ticket makes liberal use of the terms and concepts described in T213136, !!
When users Update date or Download reportsimplementing this ticket will, alas, an intricate dance takes place among various back-end processes and interface elementsrequire you to read and refer to T213136. This ticket describes that dance andI'm sorry, but it was the elements and processes involved.best I could do!
=Background: understanding '==The elements of the Updating', 'Fetching', and timestampse/Download UX
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.ticket defines the management of five simple UI elements, Updating is triggered when the user clicks the Update button or requests a report (unless an update occurred during the caching period—see below).all located at the upper-right of the Edit Summary and Edit List pages: 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.the Download Reports Button/Menu (defined in T206576)
- **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 Animated 'Working' Indicator (also T206576)
- **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. the Update button
- **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.
the On-Page Message/Timestamp
- !!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 sequencesthe View Edit List button (Edit Summary page only)
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 showingAlso defined here are some page behaviors relating to the Update/Download process (such as when the on-page metrics do or don't update.)
|**The Animated 'Working' Indicator, 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= The three states of the Update/Download UX
For the purpose of describing this system, it's useful to think of it as having three possible states: Available, Updating, and Fetching. See designs below.
(These states are abstractions that may or may not match actual implementation strategy.) The sections below specify how each of the five elements named above behave and appear in each of the three States.
===='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;available; 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 shows the timestamp in the following format "Last update, time/ timezone of the last update. Note: d 2018-10-29 18:49 (Africa/Accra)" [this is the existing messageformat]
- **Download menu:** is available.
- **View Edit List button** is clickavailable; it shows its normal color and turns a darker shade of gray on hover.
/clickable
===='Updating' state
When the user initiates update by clicking the button or downloading a report (when there no update has occurred within the Caching Period), the Update state commences.
- **The 'Working" indicator** showsappears and animates, as specified in(as per T206576)
- **Update button: **the button is grayed out and unavailable is unavailable (it's actually replaced by the indicator)
- **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?!!unavailable
===='Fetching' state
Fetching is always caused by a Download requestthe process of gathering data without gathering new page IDs (the IDs come from a prior update).
- **During Fetch—no UX differencUX is as above** During Fetch, most front-end, UX elements appear and behave exactly as they do during Updating.all front-end, (The differences are on the back end: the Event Summary figures are not calculated and new page IDs are not gathered)UX elements appear and behave exactly as they do during Updating.
- **After Fetch—the timestamp (possibly)**depending...)** 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.Fetch often occurs in combination with an Update, See below,rendering this difference invisible to users in such cases. under **When Fetch Completes**The below section, for the possible variations"After Update/Fetch completes" defines when the timestamp does and doesn't update.
=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 noNO 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 does 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)