Expand all

ve.init.mw.ArticleTarget

Extends

Constructor

new ve.init.mw.ArticleTarget([config]) #

Parameters:

Name Type Attributes Description
config Object optional

Configuration options

Properties:
Name Type Attributes Default Description
toolbarConfig Object optional
register boolean optional
true
Source:
Initialization MediaWiki article target.

Properties

trackingNamestatic #

Tracking name of target class. Used by ArticleTargetEvents to identify which target we are tracking.

Properties:

Type Description
string
Source:
Tracking name of target class.

Methods

afterSurfaceReady() #

Runs after the surface has been made ready and visible

Implementing sub-classes must call this method.

Source:

Runs after the surface has been made ready and visible

Implementing sub-classes must call this method.

bindSaveDialogClearDiff() #

Clear the save dialog's diff cache when the document changes

Source:
Clear the save dialog's diff cache when the document changes

clearDiff() #

Clear all state associated with the diff

Source:
Clear all state associated with the diff

clearDocState() #

Clear any stored document state

Inherited from:
Source:
Clear any stored document state

clearDocToSave() #

Clear the document to save from the cache

Source:
Clear the document to save from the cache

clearPreparedCacheKey() #

Clear the promise for the prepared wikitext cache key, and abort it if it's still in progress.

Source:
Clear the promise for the prepared wikitext cache key, and abort it if it's still in progress.

clearState() #

Clear the state of this target, preparing it to be reactivated later.

Source:
Clear the state of this target, preparing it to be reactivated later.

createDocToSave() → {Object} #

Create a document to save

Source:

Returns:

Document to save

Type
Object
Create a document to save

disableAccessKey(key) #

Disable an access key by removing the attribute from any element containing it

Parameters:

Name Type Description
key string

Access key

Source:
Disable an access key by removing the attribute from any element containing it

documentReady(doc) #

Handle both DOM and modules being loaded and ready.

Parameters:

Name Type Description
doc HTMLDocument | string

HTML document or source text

Overrides:
Source:
Handle both DOM and modules being loaded and ready.

editConflict() #

Handle an edit conflict

Source:
Handle an edit conflict

editSource() #

Switch to edit source mode

Opens a confirmation dialog if the document is modified or VE wikitext mode is not available.

Source:

Switch to edit source mode

Opens a confirmation dialog if the document is modified or VE wikitext mode is not available.

extractErrorMessages(data) → {jQuery} #

Extract the error messages from an erroneous API response

Parameters:

Name Type Description
data Object

API response data

Source:

Returns:

Type
jQuery
Extract the error messages from an erroneous API response

getContentApi([doc], [options]) → {mw.Api} #

Get an API object associated with the wiki where the document content is hosted.

This would be overridden if editing content on another wiki.

Parameters:

Name Type Attributes Description
doc ve.dm.Document optional

API for a specific document, should default to document of current surface.

options Object optional

API options

Properties:
Name Type Attributes Description
parameters Object optional

Default query parameters for all API requests. Defaults include action=query, format=json, and formatversion=2 if not specified otherwise.

Inherited from:
Source:

Returns:

Type
mw.Api

Get an API object associated with the wiki where the document content is hosted.

getDocToSave() → {Object} #

Get a document to save, cached until the surface is modified

The default implementation returns an HTMLDocument, but other targets may use a different document model (e.g. plain text for source mode).

Source:

Returns:

Document to save

Type
Object

Get a document to save, cached until the surface is modified

The default implementation returns an HTMLDocument, but other targets may use a different document model (e.g.

getEditNotices() → {Array} #

Get list of edit notices.

Source:

Returns:

List of edit notices

Type
Array
Get list of edit notices.

getEditableContent() → {jQuery} #

Get the editable part of the page

Source:

Returns:

Editable DOM selection

Type
jQuery
Get the editable part of the page

getHtml(newDoc, [oldDoc]) → {string} #

Parameters:

Name Type Attributes Description
newDoc HTMLDocument
oldDoc HTMLDocument optional
Inherited from:
Deprecated:
  • Moved to mw.libs.ve.targetSaver.getHtml
Source:

Returns:

Type
string

getLocalApi([options]) → {mw.Api} #

Get an API object associated with the local wiki.

For example you would always use getLocalApi for actions associated with the current user.

Parameters:

Name Type Attributes Description
options Object optional

API options

Inherited from:
Source:

Returns:

Type
mw.Api
Get an API object associated with the local wiki.

getPageName([doc]) → {string} #

Get the page name associated with a specific document

Parameters:

Name Type Attributes Description
doc ve.dm.Document optional

Document, defaults to current surface's

Inherited from:
Source:

Returns:

Page name

Type
string
Get the page name associated with a specific document

getPreparedCacheKey(doc) → {jQuery.Promise} #

Get the prepared wikitext, if any. Same as prepareWikitext() but does not initiate a request if one isn't already pending or finished. Instead, it returns a rejected promise in that case.

Parameters:

Name Type Description
doc HTMLDocument

Document to serialize

Source:

Returns:

Abortable promise, resolved with a plain object containing cacheKey, and html for retries.

Type
jQuery.Promise
Get the prepared wikitext, if any.

getSaveButtonLabel([startProcess], [forceShort]) → {function|string} #

Getting the message for the toolbar / save dialog save / publish button

Parameters:

Name Type Attributes Description
startProcess boolean optional

Use version of the label for starting that process, i.e. with an ellipsis after it

forceShort boolean optional

Force the short version of the label, always used on mobile

Source:

Returns:

An i18n message or resolveable function

Type
function | string
Getting the message for the toolbar / save dialog save / publish button

getSaveDialogOpeningData() → {Object} #

Get opening data to pass to the save dialog

Source:

Returns:

Opening data

Type
Object
Get opening data to pass to the save dialog

getSaveFields() → {Object} #

Get save form fields from the save dialog form.

Source:

Returns:

Form data for submission to the MediaWiki action=edit UI

Type
Object
Get save form fields from the save dialog form.

getSaveOptions() → {Object} #

Get edit API options from the save dialog form.

Source:

Returns:

Save options for submission to the MediaWiki API

Type
Object
Get edit API options from the save dialog form.

getSectionHashFromPage() → {string} #

Get the URL hash for the current section's ID using the page's HTML.

TODO: Do this in a less skin-dependent way

Source:

Returns:

URL hash with leading '#', or empty string if not found

Type
string
Get the URL hash for the current section's ID using the page's HTML.

getSurfaceClasses() → {Array.<string>} #

Get a list of CSS classes to be added to surfaces, and target widget surfaces

Overrides:
Source:

Returns:

CSS classes

Type
Array.<string>
Get a list of CSS classes to be added to surfaces, and target widget surfaces

getVisualDiffGeneratorPromise() → {jQuery.Promise} #

Get a visual diff object for the current document state

Source:

Returns:

Promise resolving with a generator for a ve.dm.VisualDiff visual diff

Type
jQuery.Promise
Get a visual diff object for the current document state

getWikitextDataPromiseForDoc(modified) → {jQuery.Promise} #

Get a data promise for wikitext editing based on the current doc state

Parameters:

Name Type Description
modified boolean

Whether there were any changes

Source:

Returns:

Data promise

Type
jQuery.Promise
Get a data promise for wikitext editing based on the current doc state

getWikitextDiffPromise(doc) → {jQuery.Promise} #

Post DOM data to the Parsoid API to retrieve wikitext diff.

Parameters:

Name Type Description
doc HTMLDocument

Document to compare against (via wikitext)

Source:

Returns:

Promise which resolves with the wikitext diff, or rejects with an error

Type
jQuery.Promise

Fires:

Post DOM data to the Parsoid API to retrieve wikitext diff.

getWikitextFragment(doc, [useRevision]) → {jQuery.Promise} #

Get a wikitext fragment from a document

Parameters:

Name Type Attributes Default Description
doc ve.dm.Document
useRevision boolean optional
true

Whether to use the revision ID + ETag

Inherited from:
Source:

Returns:

Abortable promise which resolves with a wikitext string

Type
jQuery.Promise
Get a wikitext fragment from a document

goToHeading(headingNode) #

Move the cursor to a given heading and scroll to it.

Parameters:

Name Type Description
headingNode ve.ce.HeadingNode

Heading node to scroll to

Source:
Move the cursor to a given heading and scroll to it.

initAutosave([config]) #

Intialise autosave, recovering changes if applicable

Parameters:

Name Type Attributes Description
config Object optional

Configuration options

Properties:
Name Type Attributes Default Description
suppressNotification boolean optional
false

Don't notify the user if changes are recovered

docId string optional

Document ID for storage grouping

storage ve.init.SafeStorage optional

Storage interface

storageExpiry number optional

Storage expiry time in seconds (optional)

Inherited from:
Source:
Intialise autosave, recovering changes if applicable

isSaveable() → {boolean} #

Re-evaluate whether the article can be saved

Source:

Returns:

The article can be saved

Type
boolean
Re-evaluate whether the article can be saved

load([dataPromise]) → {jQuery.Promise} #

Load the editor.

This method initiates an API request for the page data unless dataPromise is passed in, in which case it waits for that promise instead.

Parameters:

Name Type Attributes Description
dataPromise jQuery.Promise optional

Promise for pending request, if any

Source:

Returns:

Data promise

Type
jQuery.Promise
Load the editor.

loadFail(code, errorDetails) #

Handle an unsuccessful load request.

This method is called within the context of a target instance.

Parameters:

Name Type Description
code string

Error code from mw.Api

errorDetails Object

API response

Source:

Fires:

Handle an unsuccessful load request.

loadSuccess(response, status) #

Handle response to a successful load request.

This method is called within the context of a target instance. If successful the DOM from the server will be parsed, stored in {this.doc} and then {this.documentReady} will be called.

Parameters:

Name Type Description
response Object

API response data

status string

Text status message

Source:
Handle response to a successful load request.

onSaveDialogPreview() #

Handle clicks on the show preview button in the save dialog.

Source:

Fires:

Handle clicks on the show preview button in the save dialog.

onSaveDialogResolveConflict() #

Handle clicks on the resolve conflict button in the conflict dialog.

Source:
Handle clicks on the resolve conflict button in the conflict dialog.

onSaveDialogRetry() #

Handle dialog retry events So we can handle trying to save again after page deletion warnings

Source:

Handle dialog retry events So we can handle trying to save again after page deletion warnings

onSaveDialogReview() #

Handle clicks on the review button in the save dialog.

Source:

Fires:

Handle clicks on the review button in the save dialog.

onSaveDialogReviewComplete(wikitext) #

Handle completed serialize request for diff views for new page creations.

Parameters:

Name Type Description
wikitext string
Source:
Handle completed serialize request for diff views for new page creations.

onSaveDialogSave(saveDeferred) #

Handle the save dialog's save event

Validates the inputs then starts the save process

Parameters:

Name Type Description
saveDeferred jQuery.Deferred

Deferred object to resolve/reject when the save succeeds/fails.

Source:

Fires:

Handle the save dialog's save event

Validates the inputs then starts the save process

onSurfaceCancel() #

Handle surface cancel events

Source:
Handle surface cancel events

parseMetadata(response) → {boolean} #

Parse document metadata from the API response

Parameters:

Name Type Description
response Object

API response data

Source:

Returns:

Whether metadata was loaded successfully. If true, you should call loadSuccess(). If false, either that loadFail() has been called or we're retrying via load().

Type
boolean
Parse document metadata from the API response

parseWikitextFragment(wikitext, pst, [doc]) → {jQuery.Promise} #

Parse a fragment of wikitext into HTML

Parameters:

Name Type Attributes Description
wikitext string
pst boolean

Perform pre-save transform

doc ve.dm.Document optional

Parse for a specific document, defaults to current surface's

Inherited from:
Source:

Returns:

Abortable promise

Type
jQuery.Promise
Parse a fragment of wikitext into HTML

prepareCacheKey(doc) #

Serialize the current document and store the result in the serialization cache on the server.

This function returns a promise that is resolved once serialization is complete, with the cache key passed as the first parameter.

If there's already a request pending for the same (reference-identical) HTMLDocument, this function will not initiate a new request but will return the promise for the pending request. If a request for the same document has already been completed, this function will keep returning the same promise (which will already have been resolved) until clearPreparedCacheKey() is called.

Parameters:

Name Type Description
doc HTMLDocument

Document to serialize

Source:
Serialize the current document and store the result in the serialization cache on the server.

refreshUser([doc]) → {jQuery.Promise} #

Refresh our knowledge about the logged-in user.

This should be called in response to a user assertion error, to look up the new user name, and update the current user variables in mw.config.

Parameters:

Name Type Attributes Description
doc ve.dm.Document optional

Document to associate with the API request

Inherited from:
Source:

Returns:

Promise resolved with new username, or null if anonymous

Type
jQuery.Promise
Refresh our knowledge about the logged-in user.

reloadSurface(newMode, [dataPromise]) #

Reload the target surface in the new editor mode

Parameters:

Name Type Attributes Description
newMode string

New mode

dataPromise jQuery.Promise optional

Data promise, if any

Source:
Reload the target surface in the new editor mode

renderCategories(categoryItems) → {jQuery.Promise} #

Render a list of categories

Duplicate items are not shown.

Parameters:

Name Type Description
categoryItems Array.<ve.dm.MetaItem>

Array of category metaitems to display

Source:

Returns:

A promise which will be resolved with the rendered categories

Type
jQuery.Promise

Render a list of categories

Duplicate items are not shown.

replacePageContent(html, categoriesHtml, displayTitle, lastModified, contentSub, sections) #

Replace the page content with new HTML.

Parameters:

Name Type Description
html string

Rendered HTML from server

categoriesHtml string

Rendered categories HTML from server

displayTitle string

HTML to show as the page title

lastModified Object

Object containing user-formatted date and time strings, or undefined if we made no change.

contentSub string

HTML to show as the content subtitle

sections Array

Section data to display in the TOC

Source:
Replace the page content with new HTML.

restoreAccessKeys() #

Re-enable all access keys

Source:
Re-enable all access keys

restoreEditSection() #

Move the cursor in the editor to section specified by this.section. Do nothing if this.section is undefined.

Source:
Move the cursor in the editor to section specified by this.section.

save(doc, options) → {jQuery.Promise} #

Post DOM data to the Parsoid API.

This method performs an asynchronous action and uses a callback function to handle the result.

this.save( dom, { summary: 'test', minor: true, watch: false } );

Parameters:

Name Type Description
doc HTMLDocument

Document to save

options Object

Saving options. All keys are passed through, including unrecognized ones.

  • {string} summary Edit summary
  • {boolean} minor Edit is a minor edit
  • {boolean} watch Watch the page
Source:

Returns:

Save promise, see mw.libs.ve.targetSaver.postHtml

Type
jQuery.Promise
Post DOM data to the Parsoid API.

saveComplete(data) #

Handle successful DOM save event.

Parameters:

Name Type Description
data Object

Save data from the API

Properties:
Name Type Description
nocontent boolean

Indicates that page HTML and related properties were omitted

content string

Rendered page HTML from server

categorieshtml string

Rendered categories HTML from server

newrevid number

New revision id, undefined if unchanged

isRedirect boolean

Whether this page is a redirect or not

displayTitleHtml string

What HTML to show as the page title

lastModified Object

Object containing user-formatted date and time strings, or undefined if we made no change.

contentSub string

HTML to show as the content subtitle

modules Array

The modules to be loaded on the page

jsconfigvars Object

The mw.config values needed on the page

sections Array

Section data to display in the TOC

tempusercreated boolean

True if we just became logged in as a temporary user

tempusercreatedredirect string

URL to visit to finish creating temp account

Source:

Fires:

Handle successful DOM save event.

saveErrorEmpty() #

Handle general save error

Source:
Handle general save error

saveErrorHookAborted(data) #

Handle hook abort save error

Parameters:

Name Type Description
data Object

API response data

Source:
Handle hook abort save error

saveErrorNewUser(username) #

Handle assert error indicating another user is logged in.

Parameters:

Name Type Description
username string | null

Name of newly logged-in user, or a temporary account name, or null if logged-out and temporary accounts are disabled

Source:
Handle assert error indicating another user is logged in.

saveErrorPageDeleted() #

Handle page deleted error

Source:
Handle page deleted error

saveErrorReadOnly(data) #

Handle read only error

Parameters:

Name Type Description
data Object

API response data

Source:
Handle read only error

saveErrorUnknown(data) #

Handle unknown save error

Parameters:

Name Type Description
data Object | null

API response data

Source:
Handle unknown save error

saveFail(doc, saveData, code, data) #

Handle an unsuccessful save request.

Parameters:

Name Type Description
doc HTMLDocument

HTML document we tried to save

saveData Object

Options that were used

code string

Error code

data Object | null

Full API response data, or XHR error details

Source:

Fires:

Handle an unsuccessful save request.

scrollToHeading(headingNode, [headingOffset]) #

Scroll to a given heading in the document.

Parameters:

Name Type Attributes Default Description
headingNode ve.ce.HeadingNode

Heading node to scroll to

headingOffset number optional
0

Set the top offset of the heading to a specific amount, relative to the surface viewport.

Source:
Scroll to a given heading in the document.

serialize(doc, [callback]) → {jQuery.Promise} #

Get Wikitext data from the Parsoid API.

This method performs an asynchronous action and uses a callback function to handle the result.

this.serialize( doc ).then( ( data ) => {
    // Do something with data.content (wikitext)
} );

Parameters:

Name Type Attributes Description
doc HTMLDocument

Document to serialize

callback function optional

Optional callback to run after. Deprecated in favor of using the returned promise.

Source:

Returns:

Serialize promise, see mw.libs.ve.targetSaver.postHtml

Type
jQuery.Promise
Get Wikitext data from the Parsoid API.

setFakeRedirectInterface(title) #

Set temporary redirect interface to match the current state of redirection in the editor.

Parameters:

Name Type Description
title string | null

Current redirect target, or null if none

Source:
Set temporary redirect interface to match the current state of redirection in the editor.

setRealRedirectInterface() #

Set the redirect interface to match the page's redirect state.

Source:
Set the redirect interface to match the page's redirect state.

setupSurface(doc) #

Switch to editing mode.

Parameters:

Name Type Description
doc HTMLDocument | string

HTML document or source text

Inherited from:
Source:
Switch to editing mode.

setupToolbarSaveButton()abstract #

Setup the toolbarSaveButton property to point to the save tool

Source:
Setup the toolbarSaveButton property to point to the save tool

showChanges(doc) #

Show changes in the save dialog

Parameters:

Name Type Description
doc Object

Document

Source:
Show changes in the save dialog

showSaveDialog([action], [checkboxName]) #

Show a save dialog

Parameters:

Name Type Attributes Description
action string optional

Window action to trigger after opening

checkboxName string optional

Checkbox to toggle after opening

Source:

Fires:

Show a save dialog

showSaveError(msg, [warning]) #

Show an save process error message

Parameters:

Name Type Attributes Default Description
msg string | jQuery | Array.<Node>

Message content (string of HTML, jQuery object or array of Node objects)

warning boolean optional
false

Whether or not this is a warning.

Source:
Show an save process error message

startSave(saveOptions) #

Start the save process

Parameters:

Name Type Description
saveOptions Object

Save options

Source:
Start the save process

storeDocState([html]) #

Store a snapshot of the current document state.

Parameters:

Name Type Attributes Description
html string optional

Document HTML, will generate from current state if not provided

Overrides:
Source:
Store a snapshot of the current document state.

submit(wikitext, fields) → {boolean} #

Post wikitext to MediaWiki.

This method performs a synchronous action and will take the user to a new page when complete.

this.submit( wikitext, { wpSummary: 'test', wpMinorEdit: 1, wpSave: 1 } );

Parameters:

Name Type Description
wikitext string

Wikitext to submit

fields Object

Other form fields to add (e.g. wpSummary, wpWatchthis, etc.). To actually save the wikitext, add { wpSave: 1 }. To go to the diff view, add { wpDiff: 1 }.

Source:

Returns:

Submitting has been started

Type
boolean
Post wikitext to MediaWiki.

submitWithSaveFields(fields, wikitext) → {boolean} #

Invoke #submit with the data from #getSaveFields

Parameters:

Name Type Description
fields Object

Fields to add in addition to those from #getSaveFields

wikitext string

Wikitext to submit

Source:

Returns:

Whether submission was started

Type
boolean
Invoke #submit with the data from #getSaveFields

surfaceReady() #

Once surface is ready, initialize the UI

Overrides:
Source:

Fires:

Once surface is ready, initialize the UI

switchToFallbackWikitextEditor([modified]) → {jQuery.Promise} #

Switches to the fallback wikitext editor, either keeping (default) or discarding changes.

Parameters:

Name Type Attributes Default Description
modified boolean optional
false

Whether there were any changes at all.

Source:

Returns:

Promise which rejects if the switch fails

Type
jQuery.Promise
Switches to the fallback wikitext editor, either keeping (default) or discarding changes.

switchToVisualEditor() #

Switch to the visual editor.

Source:
Switch to the visual editor.

switchToWikitextEditor([modified]) #

Switches to the wikitext editor, either keeping (default) or discarding changes.

Parameters:

Name Type Attributes Default Description
modified boolean optional
false

Whether there were any changes at all.

Source:
Switches to the wikitext editor, either keeping (default) or discarding changes.

switchToWikitextSection(section, [noPrompt]) #

Switch to a different wikitext section

Parameters:

Name Type Attributes Default Description
section string | null

Section to switch to: a number, 'T-'-prefixed number, 'new' or null (whole document)

noPrompt boolean optional
false

Switch without prompting (changes will be lost either way)

Source:
Switch to a different wikitext section

track(name) #

Track an event

Parameters:

Name Type Description
name string

Event name

Overrides:
Source:
Track an event

tryTeardown([noPrompt], [trackMechanism]) → {jQuery.Promise} #

Try to tear down the target, but leave ready for re-activation later

Will first prompt the user if required, then call #teardown.

Parameters:

Name Type Attributes Description
noPrompt boolean optional

Do not display a prompt to the user

trackMechanism string optional

Abort mechanism; used for event tracking if present

Source:

Returns:

Promise which resolves when the target has been torn down, rejects if the target won't be torn down

Type
jQuery.Promise

Try to tear down the target, but leave ready for re-activation later

Will first prompt the user if required, then call #teardown.

tryWithPreparedCacheKey(doc, extraData, [eventName]) → {jQuery.Promise} #

Try submitting an API request with a cache key for prepared wikitext, falling back to submitting HTML directly if there is no cache key present or pending, or if the request for the cache key fails, or if using the cache key fails with a badcachekey error.

This function will use mw.Api#postWithToken to retry automatically when encountering a 'badtoken' error.

Parameters:

Name Type Attributes Description
doc HTMLDocument | string

Document to submit or string in source mode

extraData Object

POST parameters to send. Do not include 'html', 'cachekey' or 'format'.

eventName string optional

If set, log an event when the request completes successfully. The full event name used will be 'performance.system.{eventName}.withCacheKey' or .withoutCacheKey depending on whether or not a cache key was used.

Source:

Returns:

Promise which resolves/rejects when saving is complete/fails

Type
jQuery.Promise

Try submitting an API request with a cache key for prepared wikitext, falling back to submitting HTML directly if there is no cache key present or pending, or if the request for the cache key fails, or if using the cache key fails with a badcachekey error.

updateRedirectInterface($sub, $msg) #

Display the given redirect subtitle and redirect page content header on the page.

Parameters:

Name Type Description
$sub jQuery

Redirect subtitle, see #buildRedirectSub

$msg jQuery

Redirect page content header, see #buildRedirectMsg

Source:
Display the given redirect subtitle and redirect page content header on the page.

updateTabs() #

Update state of editing tabs from this target

Source:
Update state of editing tabs from this target

updateToolbarSaveButtonState() #

Update the toolbar save button to reflect if the article can be saved

Source:
Update the toolbar save button to reflect if the article can be saved

buildRedirectMsg(title) → {jQuery}static #

Build DOM for the redirect page content header (.redirectMsg).

Parameters:

Name Type Description
title string

Redirect target

Source:

Returns:

Type
jQuery
Build DOM for the redirect page content header (.redirectMsg).

buildRedirectSub() → {jQuery}static #

Build DOM for the redirect page subtitle (#redirectsub).

Source:

Returns:

Type
jQuery
Build DOM for the redirect page subtitle (#redirectsub).

Events

save(data) #

Parameters:

Name Type Description
data Object

Save data from the API, see ve.init.mw.ArticleTarget#saveComplete Fired immediately after a save is successfully completed

Source:

saveError(code) #

Parameters:

Name Type Description
code string

Error code

Source:

serializeComplete() #

Fired when serialization is complete

Source:
Fired when serialization is complete