Page Previews/Functionality

=Hovercards Expected Functionality=

Introduction
We're building hovercards. We're refactoring hovercards. There were bugs. There will no longer be bugs. Below is the expected functionality for the feature.

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

Basic Functionality
^example of a hovercard

Each page preview will contain the following:

Summary of the article:
Article summary will contain the first 525 characters from the lead paragraph of each article After the first 525 characters, a horizontal gradient will be displayed to indicate continuation (as in related pages). More info here: https://phabricator.wikimedia.org/T67845 The first instance of bolded text within the article will appear bolded within a hovercard. Any other instance of bolded text will not appear bolded More info here: https://phabricator.wikimedia.org/T141651 If an article has no lead paragraph, a generic hovercard will be used (more info below)

Generic hovercards
these 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 acticle” 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 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

Math: All math 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 section If an article has a 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 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) If an article contains multiple images within the first paragraph and the article has an infobox, display first image that appears in infobox If an article contains multiple images within the first paragraph and the article does not have an infobox, display first image that appears in the lead paragraph Hovercards may display free and non-free images.

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 an off Selecting the settings cog will open the user settings modal

Design Criteria
Layout Retain Orientations Vertical / horizontal With image / without image North, west, east and south position of hovercards, based on the empty area on the screen. Keep hovercard always visible. Retain typography and spacings Retain image sizes Improve the visual appearance to match Wikimedia guideline Smoother corners to cards. 2px. Deeper shadow for better focus on content Update border color to new grey Snappier transition - cutting down on time it takes for card to appear after the intentional loading delay. From 0.3 to 0.15

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: The user settings modal will contain the following sections: Title: 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

Use Case - disabling page previews: Initial state: page previews are ON User hovers over a link System opens page preview for selected page (if available): User selects settings System navigates to page preview settings User selects disable and Save System closes page preview settings System sets hovercards as OFF System displays Enable Preview Modal User selects “X” or “Done” System closes Enable Preview Modal

Use Case - enabling page previews Initial state: page previews are OFF User selects “Enable Previews” System navigates to page preview settings User selects enable and Save System closes page preview settings System sets page previews as ON

Design Criteria

Complete Workflow

(See below)

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 3. Questions: What happens when user logs out - can we default back to their browser preference (it’s fine if not)

4. Navigational Popups behavior: If users enable hovercards from the user preferences page AND navigational popups are on: Do not display hovercards

5. Design Criteria 6. Workflow:

Workflows
If a user selects a page preview, the system navigates to the page of the preview, the hovercard closes Note: If the user navigates back from the next article, hovercard must appear closed Complete workflow (see below)

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)

Event Logging
Current schema + https://phabricator.wikimedia.org/T147314 (“Add reading depth to hovercards schema (defined as time spent on page)”)

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