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)

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

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

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

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

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

Story: as a reader, I want the ability to view previews on articles that contain mathematical expressions
Description: display previews with math
Acceptance criteria:

https://phabricator.wikimedia.org/T151055 - Spike
https://phabricator.wikimedia.org/T141766 - Fix

Allow users to choose whether they want hovercards or not - hovercards onboarding

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

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

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

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

Summary of the article:

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:

Generic hovercards

Example of a generic hovercard for pages with no previews

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:

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:

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

If an article summary contains a link to a different page, the link will be rendered in plain text

Articles with a noinclude section

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:

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)

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

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

Visual

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

The transition time will be 0.2s

More info here: https://phabricator.wikimedia.org/T150814

Settings

Logged-out users

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:

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

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:

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

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

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 :):

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

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

↑ The scoring algorithm is implemented in LinksUpdateHookHandler.php. This page has a human-readable overview of the scoring algorithm as it existed in 2018.

[1] The scoring algorithm is implemented in LinksUpdateHookHandler.php. This page has a human-readable overview of the scoring algorithm as it existed in 2018.

[1]