Page Previews/Functionality
The following page describes the functionality expected from the hovercards feature upon release. To ensure completion of the feature, we have accounted for a number of the current bugs, as well as the refactoring of the feature and its basic functionality.
Story Breakdown (Tentative)
[edit]These are the current stories for hovercards in Phabricator. Upon completion of the following stories, the feature will be considered ready for move out of beta.
Allow users to view hovercards
[edit]Story: as a user, I want the ability to view page previews so that I can gain context on a topic
Description: build hovercards
Acceptance criteria: https://phabricator.wikimedia.org/T149801
Improve Page Preview visual design
[edit]Story: as a user, I want page previews to have unified design
Description: Page previews need visual design improvement in three areas
- depth of shadow
- no border
- transition time
Acceptance criteria:https://phabricator.wikimedia.org/T150814
Allow generic hovercards to appear in special cases
[edit]Story: as user, I want the ability to know when a preview is not available for the page I am viewing
Description: build generic hovercard
Acceptance criteria: https://phabricator.wikimedia.org/T151054
Allow logged in users to turn hovercards on/off
[edit]Story: as a user, I want the ability to turn hovercards on/off, so that I can structure my reading experience based on my needs
Description: build logged-in settings
Acceptance criteria: https://phabricator.wikimedia.org/T146889
Allow mathematical expressions to appear within hovercards
[edit]Story: as a reader, I want the ability to view previews on articles that contain mathematical expressions
Description: display previews with math
Acceptance criteria:
Allow users to choose whether they want hovercards or not - hovercards onboarding
[edit]Story: as a user, I want the ability to be introduced to the hovercards feature before I decide whether I want it or not
Description: build onboarding
Acceptance criteria: everything in section for onboarding
Allow proper bolding
[edit]Story: As a reader, I want to see the most important part of a page preview in bold so that I know what the article is about
Description: When users highlight a hovercard, display the first instance of bolded text appearing within the article.
Acceptance Criteria: https://phabricator.wikimedia.org/T141651
Allow navigational popups to be default previews
[edit]Story: as an editor, I want the ability to view navigational popups rather than hovercards, as they are more helpful to me
Description: make navpopups appear instead of hovercards even when hovercards are on
Acceptance criteria: https://phabricator.wikimedia.org/T149801
General
[edit]For their first iteration, hovercards will appear everywhere but:
- Pages that are non-main namespace pages
- Links to non-main namespace page
- in edit previews (when action = edit)
- https://phabricator.wikimedia.org/T144545
- For disambiguation pages (but will appear ON disambiguation pages)
- On any special pages
- For links to any special pages
- Wiktionary
- Wikispecies
- Wikibooks
- Wikisource
When hovercards are on, link titles will not appear For more info: https://phabricator.wikimedia.org/T14272
Basic Functionality
[edit]
Summary of the article:
[edit]The article summary is generated per the specification. The first non-empty paragraph is used and where long will be clipped by a horizontal gradient to indicate continuation (as in related pages).
Special cases:
[edit]Generic hovercards
[edit]
Generic hovercards will be used when we cannot display hovercards for certain pages. They will contain the following:
- Icon: Sad face icon
- Text: Looks like there isnât a page preview for this topic
- Link: Read article
- Selecting âRead articleâ will navigate users to the article
- Generic hovercards will not contain a settings cog
- All other functionality will be as in other previews
- Note: the mockup provided displays a âwrite page previewâ link. This link will NOT be available
Generic hovercards will appear in the following cases:
- Articles with no lead paragraph
Mathematical Expressions:
[edit]All mathematical expressions must be rendered as they appear within the article including:
- Subscripts
- Formulae
- (see https://phabricator.wikimedia.org/T99793 and https://phabricator.wikimedia.org/T112137)
Parentheticals:
[edit]If a summary contains a parenthetical, it must be excluded from the hovercard Note: there are some special cases where itâs useful, but we can ignore them for now. For more info, see: https://phabricator.wikimedia.org/T91344
Links to other pages
[edit]If an article summary contains a link to a different page, the link will be rendered in plain text
Articles with a noinclude section
[edit]If an article has a noinclude section at the top, the summary will skip this section and display content from the first paragraph Note: based on https://phabricator.wikimedia.org/T109869
Article image:
[edit]The PageImages image for an article will be displayed according to the new architecture of PageImages:
- The image may only be displayed if an image is within the lead section of an article OR within the first paragraph
- If there is no image within the lead section or first paragraph, no images will be displayed for the hovercard (the hovercard will only display the text summary of the article)
- Hovercards may display free and non-free images (the configuration on which images to display will be based on community consensus for each project)
Candidate images are scored by an algorithm that takes into account features such as order of appearance (earlier is better), size, and aspect ratio. The image with the highest score will be displayed, unless all scores are negative, in which case no image is shown.[1]
Last edited date (tentative)
[edit]The last edited date for the article will appear at the bottom of the hovercard. Allow t = last edited date rounded to the nearest hour
- If t < 24 hours ago, display: Edited X hours ago
- If 24 < t < one week, display: Edited X days ago
- If one week < t < 4 weeks, display: Edited X weeks ago
- Else, display: Edited on X (where X = date of edit)
Settings cog
[edit]The settings cog will appear at the bottom of the hovercard. It will be a button used to allow users to turn hovercards on and off Selecting the settings cog will open the user settings modal.
Design Criteria
[edit]Visual
[edit]The following visual constraints will be applied:
.mwe-popups {
box-shadow: 0 45px 70px -20px rgba(0,0,0,0.3), 0px 0px 1px rgba(0,0,0,0.5);
border:none;
}
Transition Time
[edit]The transition time will be 0.2s
More info here: https://phabricator.wikimedia.org/T150814
Settings
[edit]Logged-out users
[edit]Logged out users will be able to turn hovercards off via the settings link at the bottom of each page preview. Users will be able to turn hovercards on via the âEnable Previewsâ link at the bottom of each page. These settings will be saved per browser session.
Basic functionality:
[edit]
Page Preview Settings
- Button: X
- Selecting X will close the settings modal AND the hovercard from which it was triggered
- No settings will be changed if user selects X
- Button: Save
- Selecting âSaveâ will save the user settings and close the user settings modal (note: if user decides to disable previews, the enable modal will appear)
- If no change in settings was selected, no change will be made in user settings
- If a change was selected, the appropriate change will be saved
- Radio button: Enable (DEFAULT)
- Subtitle: Get quick previews of a topic while reading an article
- If this radio button is selected, hovercards will be ON when user selects âSaveâ
- Radio button: Disable
- Subtitle: You can always re-enable them later
- If this radio button is selected, hovercards will be OFF when user selects save
- Upon selecting Save, the enable previews modal will appear. This modal will contain the following:
- Title: Page Preview Settings
- Text: You can turn page previews back on using the âEnable Previewsâ link in the footer of the page.
- Illustration: (as seen below)
- Button: X - selecting X will close the modal (page previews will be OFF)
- Button: Done - selecting Done will close the modal (page previews will be OFF)
Enable previews link
- When page previews are off, the enable previews link will appear at the footer of each page
- Selecting the enable previews link will open the user settings modal
- The default of the user settings modal will be ENABLED
- When page previews are OFF, the enable previews link will not appear
Logged-in users
[edit]Logged-in users will be able to control their settings from two places - the settings cog and the user preferences page. User Preferences:
Users will be able to specify whether they want hovercards on or off via a section within the user preferences page. This will contain the following:
- Section title: Reading Preferences
- Item title: Page Previews
- Subtitle: Get quick previews of a topic while reading an article
- Radio button: Enable
- Selecting Enable and Save will turn page previews ON
- Selecting Enable and not saving will do nothing
- Radio button: Disable
- Selecting Disable and Save will turn page previews OFF
- Selecting Disable without saving will do nothing
Note: when hovercards are disabled for logged-in users, the âEnable Previewsâ link will NOT appear
Settings cog For logged in users, the settings cog at the bottom of the article will navigate users to the user preferences page
Navigational Popups behavior:
[edit]- If users enable hovercards from the user preferences page AND navigational popups are on:
- Hovercards will not be turned on. The user will be given a message that, in order to turn hovercards on, navigational popups must be turned off.
Onboarding
[edit]Logged-out users Hovercards will be ON by default upon release. Users will go through the following workflow User views hovercard n times On nth card, system displays modal asking if user would like to disable feature More info here: https://phabricator.wikimedia.org/T133230
Logged-in users
Hovercards will be OFF by default upon release (as reflected by the radio button in user preferences)
EventLogging
[edit]Current schema, with the following changes:
- https://phabricator.wikimedia.org/T147314 (âAdd reading depth to hovercards schema (defined as time spent on page)â)
Remove the "version" field(keep it per what we since learned about caching times at phab:T144490)- Remove the "api" field
- Remove the "error" event
- Merge the "opened in new tab", "opened in new window" and "opened in same tab" events into a new "opened" event
- For events that involve a card (having been / being) shown, add a "cardType" field indicating whether the card is generic (no preview available, phab:T151054) or regular
Should work like this (Tilman made this :):
.svg)
Bugs not accounted for:
- https://phabricator.wikimedia.org/T105924 (âHovercards can show JavaScript output by Graph extensionâ)
- https://phabricator.wikimedia.org/T147237 (âNotifications Popup is underlying Hovercards, should be on topâ)
Tentative Improvements
[edit]- Mobile ability
- Adding page titles
- Navigational popups functionality
- https://phabricator.wikimedia.org/T148778 (âAdd article quality to Hovercardsâ)
- https://phabricator.wikimedia.org/T146097 (âCannot copy and paste popup textâ)
- https://phabricator.wikimedia.org/T145541 (âMake Hovercards work with Special:MyLanguage linksâ)
- https://phabricator.wikimedia.org/T145249 (âOption for users to see maintenance templates on previewed pageâ)
- https://phabricator.wikimedia.org/T136480 (âHelp pages and hovercardsâ)
- https://phabricator.wikimedia.org/T85718 (âTeach hovercard to show on categorytree links (including the root)â)
- https://phabricator.wikimedia.org/T69232 (âHovercards: Redirect titles should be bolded in the extractâ)
- https://phabricator.wikimedia.org/T67117 (âDisplay popups across wikisâ)
- https://phabricator.wikimedia.org/T67114 (âShow cards for referencesâ) â Reference Previews feature
Footnotes
[edit]- â The scoring algorithm is implemented in LinksUpdateHookHandler.php. This page has a human-readable overview of the scoring algorithm as it existed in 2018.