Global

Methods

formatPlainTextExtract(plainTextExtract, title) → {Array}

Improves the plain text extracts

Parameters:
Name Type Description
plainTextExtract string
title string
Source:
Returns:
Type
Array

makeTitleInExtractBold(extract, title) → {Array}

Converts the extract into a list of elements, which correspond to fragments of the extract. Fragments that match the title verbatim are wrapped in a <b> element.

Using the bolded elements of the extract of the page directly is covered by T141651.

Extracted from mw.popups.renderer.article.getProcessedElements.

Parameters:
Name Type Description
extract string
title string
Source:
Returns:

A set of HTML Elements

Type
Array

module:bracketedPixelRatio(dpropt) → {number}

Normalizes a user's device pixel ratio to either 1, 1.5, or 2.

This is important when the server resizes images on the fly in order to reduce the work it has to do for device pixel ratios that deviate from a set of common ratios.

Adapted from mediawiki/core /resources/src/jquery/jquery.hidpi.js

Parameters:
Name Type Attributes Default Description
dpr number <optional>
window.devicePixelRatio
Source:
Returns:

The bracketed device pixel ratio

Type
number

module:changeListener(store, callback) → {void}

Registers a change listener, which is bound to the store.

A change listener is a function that is only invoked when the state in the store changes. N.B. that there may not be a 1:1 correspondence with actions being dispatched to the store and the state in the store changing.

See Store#subscribe for more information about what change listeners may and may not do.

Parameters:
Name Type Description
store Redux.Store
callback ext.popups.ChangeListener
Source:
Returns:
Type
void

module:changeListeners/eventLogging(boundActions, eventLoggingTracker, getCurrentTimestamp) → {ext.popups.ChangeListener}

Creates an instance of the event logging change listener.

When an event is enqueued it'll be logged using the schema. Since it's the responsibility of Event Logging (and the UA) to deliver logged events, EVENT_LOGGED is immediately dispatched rather than waiting for some indicator of completion.

Parameters:
Name Type Description
boundActions Object
eventLoggingTracker EventTracker
getCurrentTimestamp function
Source:
Returns:
Type
ext.popups.ChangeListener

Creates an instance of the footer link change listener.

The change listener covers the following behaviour:

  • The "Enable previews" link (the "link") is appended to the footer menu (see createFooterLink above).
  • When Page Previews are disabled, then the link is shown; otherwise, the link is hidden.
  • When the user clicks the link, then the showSettings bound action creator is called.
Parameters:
Name Type Description
boundActions Object
Source:
Returns:
Type
ext.popups.ChangeListener

module:changeListeners/pageviews(boundActions, pageviewTracker) → {ext.popups.ChangeListener}

Creates an instance of the pageviews change listener.

When a pageview enqueued it'll be logged using the VirtualPageView schema. Note, it's the responsibility of Event Logging (and the UA) to deliver logged events.

Parameters:
Name Type Description
boundActions Object
pageviewTracker EventTracker
Source:
Returns:
Type
ext.popups.ChangeListener

module:changeListeners/syncUserSettings(userSettings) → {ext.popups.ChangeListener}

Creates an instance of the user settings sync change listener.

This change listener syncs certain parts of the state tree to user settings when they change.

Used for:

  • Enabled state: If the previews are enabled or disabled.
  • Preview count: When the user dwells on a link for long enough that a preview is shown, then their preview count will be incremented (see reducers/eventLogging.js, and is persisted to local storage.
Parameters:
Name Type Description
userSettings ext.popups.UserSettings
Source:
Returns:
Type
ext.popups.ChangeListener

module:container() → {Container}

Creates an empty service container.

Source:
Returns:
Type
Container

module:experiments(mwExperiments) → {Experiments}

Creates a helper wrapper for the MediaWiki-provided mw.experiments#getBucket bucketing function.

Parameters:
Name Type Description
mwExperiments mw.experiments

The mw.experiments singleton instance

Source:
Returns:
Type
Experiments

module:gateway/mediawiki(api, config) → {MediaWikiGateway}

Creates an instance of the MediaWiki API gateway.

Parameters:
Name Type Description
api mw.Api
config Object

Configuration that affects the major behavior of the gateway.

Properties
Name Type Description
THUMBNAIL_SIZE number

The length of the major dimension of the thumbnail.

EXTRACT_LENGTH number

The maximum length, in characters, of the extract.

acceptLanguage string

The accepted language sent in the header

Source:
Returns:
Type
MediaWikiGateway

module:gateway/page(config) → {Gateway}

Creates a page preview gateway with sensible values for the dependencies.

Parameters:
Name Type Description
config mw.Map
Source:
Returns:
Type
Gateway

module:gateway/reference() → {Gateway}

Source:
Returns:
Type
Gateway

module:gateway/rest(ajax, config, extractParser) → {Gateway}

Creates an instance of the RESTBase gateway.

This gateway differs from the MediaWiki gateway in that it fetches page data from the RESTBase page summary endpoint.

Parameters:
Name Type Description
ajax Ajax

A function with the same signature as jQuery.ajax

config Object

Configuration that affects the major behavior of the gateway.

extractParser function

A function that takes response and returns parsed extract

Source:
Returns:
Type
Gateway

module:isEnabled(user, userSettings, config) → {boolean}

Given the global state of the application, creates a function that gets whether or not the user should have Page Previews enabled.

Page Previews is disabled when the Navigation Popups gadget is enabled.

If Page Previews is configured as a user preference, then the user must either be logged in and have enabled the preference or be logged out and have not disabled previews via the settings modal.

Parameters:
Name Type Description
user mw.user

The mw.user singleton instance

userSettings Object

An object returned by userSettings.js

config mw.Map
Source:
Returns:
Type
boolean

module:MediaWiki-Popups Integration(store) → {Object}

This function provides a mw.popups object which can be used by 3rd party to interact with Popups. Currently it allows only to read isEnabled flag.

Parameters:
Name Type Description
store Redux.Store

Popups store

Source:
Returns:

external Popups interface

Type
Object

module:previewBehaviour(user, actions) → {ext.popups.PreviewBehavior}

Creates an instance of ext.popups.PreviewBehavior.

If the user is logged out, then clicking the cog should show the settings modal.

If the user is logged in, then clicking the cog should send them to the the "Appearance" tab otherwise.

Parameters:
Name Type Description
user mw.User
actions Object

The action creators bound to the Redux store

Source:
Returns:
Type
ext.popups.PreviewBehavior

module:reducers/eventLogging(state, action) → {Object}

Reducer for actions that may result in an event being logged with the Popups schema via EventLogging.

The complexity of this reducer reflects the complexity of the schema, which is compounded by the introduction of two delays introduced by the system to provide reasonable performance and a consistent UX.

The reducer must:

  • Accumulate the state required to log events. This state is referred to as "the interaction state" or "the interaction";
  • Enforce the invariant that one event is logged per interaction;
  • Defend against delayed actions being dispatched; and, as a direct consequence
  • Handle transitioning from one interaction to another at the same time.

Furthermore, we distinguish between "finalizing" and "closing" the current interaction state. Since only one event should be logged per link interaction, we say that the interaction state is finalized when an event has been logged and is closed when a new interaction should be created. In practice, the interaction state is only finalized when the user clicks a link or a preview.

Parameters:
Name Type Description
state Object
action Object
Source:
Returns:

The state resulting from reducing the action with the current state

Type
Object

module:reducers/pageviews(state, action) → {Object}

Reducer for actions that queues and clears events for being logged as virtual pageviews 0

Parameters:
Name Type Description
state Object
action Object
Source:
Returns:

The state resulting from reducing the action with the current state

Type
Object

module:settingsDialogRenderer() → {function}

Creates a render function that will create the settings dialog and return a set of methods to operate on it

Source:
Returns:

render function

Type
function

module:userSettings(storage) → {UserSettings}

Creates an object whose methods encapsulate all interactions with the UA's storage.

Parameters:
Name Type Description
storage Object

The mw.storage singleton instance

Source:
Returns:
Type
UserSettings

module:wait(delay) → {AbortPromise.<void>}

Sugar around window.setTimeout.

Parameters:
Name Type Description
delay number

The number of milliseconds to wait

Source:
Returns:
Type
AbortPromise.<void>
Example
import wait from './wait';

wait( 150 )
  .then( () => {
    // Continue processing...
  } );

parseHTMLResponse(page) → {Array}

Prepare extract

Parameters:
Name Type Description
page Object

Rest response

Source:
Returns:

An array of DOM Elements

Type
Array

parsePlainTextResponse(page) → {Array}

Prepare extract

Parameters:
Name Type Description
page Object

Rest response

Source:
Returns:

An array of DOM Elements

Type
Array

Type Definitions

EventTracker(topic, data)

An analytics event tracker, i.e. mw.track.

Parameters:
Name Type Description
topic string
data Object
Source:

MwCodeLoader

Loads code from the server to the client on demand.

Type:
  • Object
Source:

PagePreviewModel

Type:
  • Object
Properties:
Name Type Description
title string
extract Array | undefined

undefined if the extract isn't viable, e.g. if it's empty after having ellipsis and parentheticals removed; this can be used to present default or error states

languageCode string
languageDirection string

Either "ltr" or "rtl", or an empty string if undefined.

thumbnail Object | undefined
pageId number

Currently not used by any known popup type.

Source:

PreviewModel

Preview Model

Type:
  • Object
Properties:
Name Type Description
url string

The canonical URL of the page being previewed

type string

One of the previewTypes.TYPE_… constants.

Source:

ReferencePreviewModel

Type:
  • Object
Properties:
Name Type Description
extract string

An HTML snippet, not necessarily with a single top-level node

referenceType string

A type identifier, e.g. "web"

sourceElementId string

ID of the parent element that triggered the preview

Source:

SettingsChoiceModel

Type:
  • Object
Properties:
Name Type Attributes Description
id string

Portion of the elements' IDs and value of the input.

name string
description string <optional>
isChecked boolean <optional>

Whether the setting is checked.

Source:

SettingsModel

Type:
  • Object
Properties:
Name Type Attributes Description
heading string
closeLabel string
saveLabel string
helpText string
okLabel string
choices Array.<SettingsChoiceModel> <optional>
Source: