Now that Event Metrics has Category filtering without Participants, the rules for event filtering have grown more complex. The UI /UX described here is designed to help users understand those rules and to know whether their event is fully configured or not.
This ticket describes the new filtering UI only. A separate ticket, T218445, describes overall design changes to the Event Summary page, in which this filtering UI sits.
=New elements of the UX
This ticket adds a number of new elements to the filtering UX. They are labeled in the illustration below.
{F28388513 width = 500}
=Filtering rules
To understand the workings of the UI, it may be useful to keep in mind the basic rules of our filtering system:
- Users must select Participant or Category filtering; these two can also be combined.
- Participant filtering applies to all wikis and therefor covers the minimum requirements.
- Category filters are specific to individual wikis. If users employ Categories without Participants, they must supply categories for every wiki for which they want results.
- Partial results are allowed; if users supply categories for some but not all wikis, the system will give them results for the covered wikis.
- There are no categories on Wikidata, so users who specify Wikidata as a wiki will get Wikidata metrics only if they supply Participants.
These are the rules this UI is designed to help users navigate.
=States of the UX
For purposes of describing the UX, it's convenient to think of it as having 3 main states, with a couple of variations for Wikidata. (Actual implementation may well require a different scheme.) The sections below tell how the elements of the UI behave and what messaging is shown in each of the states.
=Unfiltered state
**Definition:** The initial setup state. No filters have yet been supplied.
**[[ https://prtksxna.github.io/wmf-prototype-gm/event-filter-required.html | Mockup ]]:** get code for proper styling here. (See the illustration below)
{F28388612}.
====Behavior of elements
- **Filter panels** are open
- **Error box** is shown.
- **Status messages/icons** are shown
- **Update button/Download menu** are NOT shown (only the Settings button appears—this is existing behavior)
- **Error box help link:** URL should be !!to come, will be filtering section of Help doc!!
====Messaging for Unfiltered
//[Error title & subtitle]//
**Filters required**
Event setup isn’t complete yet. Please use one or both of the filters below to more narrowly focus your metrics.
//[Error messages]//
* You can filter by Participants or Categories—or combine the two.
* You must provide filtering for every wiki for which you want metrics.
* Participants filtering applies to all wikis and satisfies all filtering requirements.
* Category filters are specific to individual wikis.
* If you combine Categories and Participants, the system will provide metrics for contributions that satisfy both filters (i.e., Category AND Participants).
//[Status messages & icons]//
- Participants: No participants supplied [icon="glyphicon-asterisk"]
- Categories: No categories supplied [icon="glyphicon-asterisk"]
=Partial state
**Definition: **No Participants are supplied and Categories are supplied for some but not all wikis. Wikidata is not a specified wiki.
**[[ https://prtksxna.github.io/wmf-prototype-gm/event-filter-incomplete.html | Mockup ]]:** get code for proper styling here. (See the illustration below)
{F28388579}
- **Filter panels** are open
- **Error box** is shown.
- **Status messages/icons** are shown
- **Update button/Download menu** are enabled.
- **Error box help link:** URL should be !!To come, will be filtering section of Help doc!!
====Messaging for Partial
//[Error title & subtitle]//
**Event partially configured**
You will get metrics for some but not all of the wikis specified for the event. narrowly focus your metrics.
//[Error messages]//
* The following wikis require filtering: **Wikiname1, Wikiname2** !![Insert names of unfiltered wikis]!!
* You must provide filtering for every wiki for which you want metrics.
* Participants filtering applies to all wikis and satisfies all filtering requirements.
* Category filters are specific to individual wikis.
* If you combine Categories and Participants, the system will provide metrics for contributions that satisfy both filters (i.e., Category AND Participants).
//[Status messages & icons]//
- Participants: No participants supplied [icon="glyphicon-warning-sign"]
- Categories: Categories not supplied for some wikis [icon="glyphicon-warning-sign"]
=Valid state
**Definition: ** The filter settings meet the requirements and Setup is complete.
**[[ https://prtksxna.github.io/wmf-prototype-gm/event-filter-complete.html | Mockup ]]:** get code for proper styling here. (See the illustration below)
{F28393506}
- **Filter panels** are closed
- **Error box** is not shown
- **Status messages/icons** are shown //only// for the filters that are configured.
- **Update button/Download menu** are enabled.
- **A green banner ** is displayed with the following legend and link:
- Settings successfully completed or updated. Click "__Update data__" to calculate metrics.
- The __Update data__ link does the same thing as the Update data button. [This is existing functionality]
====Status messages & icons
For the Valid state, show messages/icons ONLY in the filter panels for which valid filters have been set. E.g., if no participants were supplied, show no message or icon for Participants. If valid filters were set, then show message/icon in the following format:
- Participants: X participants [icon=glyphyicon-ok]
- Categories: X categories [icon=glyphyicon-ok]
=Variations with Wikidata
Wikidata requires special messaging, since Category filtering doesn't work with Wikidata. Please see the cases below, where I've noted only the differences between the Wikidata and standard versions of these states.
===Unfiltered state with Wikidata
**Definition: ** The initial setup state, no filters have yet been supplied, and __only one wiki is specified__ for the event: Wikidata. (See the illustration below)
**[[ https://prtksxna.github.io/wmf-prototype-gm/event-filter-required-wikidata.html | Mockup ]]:** get code for proper styling here. (See the illustration below)
{F28389634}
====Everything is the same as Unfiltered, above, except the following:
//[Behavior of elements]//
**Filter panels:** Participants is open but __Categories is closed__
//[Error title & subtitle]//
**Filters required**
Event setup isn’t complete yet. Please use the Participants filter below to more narrowly focus your metrics.
//[Error messages—use only these two bulleted messages]//
* You have specified only one wiki for this event: **Wikidata**. !![Please observe boldfacing]!!
* To get metrics about Wikidata, you must supply Participants.
//[Status messages & icons]//
- Participants: Required for Wikidata [icon="glyphicon-asterisk"]
- Categories: Does not work with Wikidata [icon="glyphicon-info-sign"]
===Partial state with Wikidata
**Definition: **No Participants are supplied and Categories are supplied for some but not all wikis. Wikidata is one of the wikis specified. See the illustration below)
**[[ https://prtksxna.github.io/wmf-prototype-gm/event-filter-incomplete-wikidata.html | Mockup ]]:** get code for proper styling here. (See the illustration below)
{F28388699}
====Everything is the same as Partial, above, except the following:
//[Error messages—Insert the following as the THIRD bulleted message//
* To get metrics about **Wikidata**, you must supply Participants. (Categories don’t exist on Wikidata.) !![Please observe boldfacing.]!!
//[Status messages & icons]//
- Participants: Required for Wikidata [icon="glyphicon-asterisk"]
=What to do after Updating Data
The descriptions above all accurately describe the behavior will elements display immediately after the user has Saved Settings. Behavior will vary slightly, however, after the user Updates Data (by clicking the button or an Update Data link). (Update Data options are available only in the Valid and Partial states.)
- **Valid and Partial states both, filter panels closed: ** In both Valid and Partial states, after the user clicks Updat Data, the filter boxes will display as closed (so the user can see her data). They will remain closed every time the user visits the page, until the user Saves Settings again.
- **Partial state only, display error box:** In any Partial states, after the user clicks Update Data, the filter boxes will be closed but the Error Box messages will continue to display. Again, this behavior will continue until the user changes the Settings, in which case the cycle starts over.
=Changes to instruction text and labels of filter panels
Small changes to the filter-panel labels and to the instruction text within the panels will clarify functionality for users.
===Participants filter text changes
- **Change filter name:** from "Participants" to "Participants filter"
- **Change instruction text** as follows (see mockups for layout/styling):
- **Add wiki usernames below, one per line, to limit metrics to specific participants.** [? help icon]
- You can copy/paste directly from an on-wiki list.
- **New URL for help link: ** !!URL to come -- will link directly to Participants filtering help!!
===Categories filter text changes
- **Change filter name:** from "Categories" to "Categories filter"
- **Change instruction text** as follows (see mockups for layout/styling):
- **Enter categories (with wiki names) to limit metrics to pages in those categories. [? help icon] **
- On Commons only, use this tool to filter files (images, videos, etc.), instead of pages.
- **New URL for help link: ** !!URL to come -- will link directly to Categories filtering help!!