Global

Methods

canSaveToUserPreferences(user) → {boolean}

Can the current user save to user preferences?

Parameters:
Name Type Description
user User
Source:
Returns:
Type
boolean

formatPlainTextExtract(plainTextExtract, title) → {Array}

Improves the plain text extracts

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

initReferencePreviewsInstrumentation()

Run once the preview is initialized.

Source:

isObject(obj) → {boolean}

Parameters:
Name Type Description
obj *
Source:
Returns:
Type
boolean

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

Creates an instance of the footer link change listener.

The change listener covers the following behaviour:

  • The "Edit preview settings" link (the "link") is appended to the footer menu (see createFooterLink above).
  • When at least one popup type is 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:isPagePreviewsEnabled(user, userSettings, config) → {boolean|null}

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:

Null when there is no way the popup type can be enabled at run-time.

Type
boolean | null

module:isReferencePreviewsEnabled(user, userSettings, config) → {boolean|null}

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

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:

Null when there is no way the popup type can be enabled at run-time.

Type
boolean | null

module:MediaWiki-Popups Integration(store, registerModel, registerPreviewUI, registerGatewayForPreviewType) → {Object}

This function provides a mw.popups object which can be used by 3rd party to interact with Popups.

Parameters:
Name Type Description
store Redux.Store

Popups store
registerModel function

allows extensions to register custom preview handlers.
registerPreviewUI function

allows extensions to register custom preview renderers.
registerGatewayForPreviewType function

allows extensions to register gateways for preview types.
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/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 | undefined
action Object
Source:
Returns:

The state resulting from reducing the action with the current state

Type
Object

module:settingsDialogRenderer(referencePreviewsAvaliable) → {function}

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

Parameters:
Name Type Description
referencePreviewsAvaliable boolean
Source:
Returns:

render function

Type
function

module:setUserConfigFlags(config)

Decodes the bitmask that represents preferences to the related config options.

Parameters:
Name Type Description
config mw.Map
Source:

module:userSettings(storage) → {UserSettings}

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

Parameters:
Name Type Description
storage mw.storage

The mw.storage singleton instance
Source:
Returns:
Type
UserSettings

module:wait(delay) → {Promise}

Sugar around window.setTimeout.

Parameters:
Name Type Description
delay number

The number of milliseconds to wait
Source:
Returns:
Type
Promise
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:

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: