Extends
Constructor
new ve.init.mw.ArticleTarget([config])
#
Properties
documentCommandsstatic
#
integrationTypestatic
#
namestatic
#
platformTypestatic
#
trackingNamestatic
#
Tracking name of target class. Used by ArticleTargetEvents to identify which target we are tracking.
Properties:
Type | Description |
---|---|
string |
Methods
addSurface()
#
- Inherited from:
- Source:
afterSurfaceReady()
#
Runs after the surface has been made ready and visible
Implementing sub-classes must call this method.
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
clearDiff()
#
Clear all state associated with the diff
clearDocState()
#
Clear any stored document state
- Inherited from:
- Source:
clearDocToSave()
#
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.
clearState()
#
Clear the state of this target, preparing it to be reactivated later.
createSurface()
#
- Overrides:
- Source:
createTargetWidget()
#
- Inherited from:
- Source:
disableAccessKey(key)
#
Disable an access key by removing the attribute from any element containing it
Parameters:
Name | Type | Description |
---|---|---|
key |
string | Access key |
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:
editConflict()
#
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.
Switch to edit source mode
Opens a confirmation dialog if the document is modified or VE wikitext mode is not available.
extractErrorMessages(data) → {jQuery}
#
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:
|
- 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).
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.
getEditableContent() → {jQuery}
#
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}
#
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
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 |
Returns:
Abortable promise, resolved with a plain object containing cacheKey
,
and html
for retries.
- Type
- jQuery.Promise
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 |
Returns:
An i18n message or resolveable function
- Type
- function | string
getSaveDialogOpeningData() → {Object}
#
getSaveFields() → {Object}
#
Get save form fields from the save dialog form.
Returns:
Form data for submission to the MediaWiki action=edit UI
- Type
- Object
getSaveOptions() → {Object}
#
Get edit API options from the save dialog form.
Returns:
Save options for submission to the MediaWiki API
- Type
- Object
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
Returns:
URL hash with leading '#', or empty string if not found
- Type
- string
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>
getSurfaceConfig()
#
- Overrides:
- Source:
getVisualDiffGeneratorPromise() → {jQuery.Promise}
#
Get a visual diff object for the current document state
Returns:
Promise resolving with a generator for a ve.dm
.VisualDiff visual diff
- Type
- jQuery.Promise
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 |
Returns:
Data promise
- Type
- jQuery.Promise
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) |
Returns:
Promise which resolves with the wikitext diff, or rejects with an error
- Type
- jQuery.Promise
Fires:
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
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 |
initAutosave([config])
#
Intialise autosave, recovering changes if applicable
Parameters:
Name | Type | Attributes | Description | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
config |
Object |
optional |
Configuration options Properties:
|
- Inherited from:
- Source:
isSaveable() → {boolean}
#
Re-evaluate whether the article can be saved
Returns:
The article can be saved
- Type
- boolean
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 |
Returns:
Data promise
- Type
- jQuery.Promise
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 |
Fires:
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 |
onSaveDialogPreview()
#
Handle clicks on the show preview button in the save dialog.
Fires:
onSaveDialogResolveConflict()
#
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
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.
Fires:
onSaveDialogReviewComplete(wikitext)
#
Handle completed serialize request for diff views for new page creations.
Parameters:
Name | Type | Description |
---|---|---|
wikitext |
string |
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. |
Fires:
Handle the save dialog's save event
Validates the inputs then starts the save process
onSurfaceCancel()
#
Handle surface cancel events
parseMetadata(response) → {boolean}
#
Parse document metadata from the API response
Parameters:
Name | Type | Description |
---|---|---|
response |
Object | API response data |
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
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
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 |
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
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 |
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 |
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 |
restoreAccessKeys()
#
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.
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.
|
Returns:
Save promise, see mw.libs.ve
.targetSaver.postHtml
- Type
- jQuery.Promise
saveComplete(data)
#
Handle successful DOM save event.
Parameters:
Name | Type | Description | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
data |
Object | Save data from the API Properties:
|
Fires:
saveErrorEmpty()
#
Handle general save error
saveErrorHookAborted(data)
#
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 |
saveErrorPageDeleted()
#
Handle page deleted error
saveErrorReadOnly(data)
#
saveErrorUnknown(data)
#
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 |
Fires:
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. |
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. |
Returns:
Serialize promise, see mw.libs.ve
.targetSaver.postHtml
- Type
- jQuery.Promise
setDefaultMode()
#
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 |
setRealRedirectInterface()
#
Set the redirect interface to match the page's redirect state.
setSurface()
#
- Inherited from:
- Source:
setupSurface(doc)
#
Switch to editing mode.
Parameters:
Name | Type | Description |
---|---|---|
doc |
HTMLDocument | string | HTML document or source text |
- Inherited from:
- Source:
setupToolbar()
#
setupToolbarSaveButton()abstract
#
Setup the toolbarSaveButton property to point to the save tool
showChanges(doc)
#
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 |
Fires:
showSaveError(msg, [warning])
#
startSave(saveOptions)
#
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:
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 }. |
Returns:
Submitting has been started
- Type
- boolean
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 |
Returns:
Whether submission was started
- Type
- boolean
surfaceReady()
#
Once surface is ready, initialize the UI
- Overrides:
- Source:
Fires:
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. |
Returns:
Promise which rejects if the switch fails
- Type
- jQuery.Promise
switchToVisualEditor()
#
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. |
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) |
teardown()
#
- Overrides:
- Source:
track(name)
#
Track an event
Parameters:
Name | Type | Description |
---|---|---|
name |
string | Event name |
- Overrides:
- Source:
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 |
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. |
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)
#
updateTabs()
#
Update state of editing tabs from this target
updateToolbarSaveButtonState()
#
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 |
Returns:
- Type
- jQuery
buildRedirectSub() → {jQuery}static
#
parseDocument()static
#
Events
loadError()
#
noChanges()
#
save(data)
#
Parameters:
Name | Type | Description |
---|---|---|
data |
Object | Save data from the API, see |
saveError(code)
#
Parameters:
Name | Type | Description |
---|---|---|
code |
string | Error code |
saveInitiated()
#
savePreview()
#
saveReview()
#
saveWorkflowBegin()
#
serializeComplete()
#
Fired when serialization is complete