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 Acceptance criteria:https://phabricator.wikimedia.org/T150814
 * 1) depth of shadow
 * 2) no border
 * 3) transition time

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

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

Generic hovercards
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.

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.

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

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: Note: when hovercards are disabled for logged-in users, the “Enable Previews” link will NOT appear
 * 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



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 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, 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