merged from master
[lhc/web/wiklou.git] / docs / hooks.txt
index 303382a..79ba13a 100644 (file)
@@ -290,7 +290,7 @@ $pageInfo: associative array of page information
 of the javascript ajax engine. The hook is only called when ajax
 is enabled ( $wgUseAjax = true; ).
 
-'AlternateEdit': before checking if an user can edit a page and
+'AlternateEdit': before checking if a user can edit a page and
 before showing the edit form ( EditPage::edit() ). This is triggered
 on &action=edit.
 $EditPage: the EditPage object
@@ -395,10 +395,20 @@ In this data array, the key-value-pair identified by the apiLink key is
 required.
 &$apis: array of services
 
+'ApiTokensGetTokenTypes': use this hook to extend action=tokens with new
+token types.
+&$tokenTypes: supported token types in format 'type' => callback function
+used to retrieve this type of tokens.
+
 'ArticleAfterFetchContent': after fetching content of an article from
+the database. DEPRECATED, use ArticleAfterFetchContentObject instead.
+$article: the article (object) being loaded from the database
+&$content: the content (string) of the article
+
+'ArticleAfterFetchContentObject': after fetching content of an article from
 the database
 $article: the article (object) being loaded from the database
-$content: the content (string) of the article
+&$content: the content of the article, as a Content object
 
 'ArticleConfirmDelete': before writing the confirmation form for article
        deletion
@@ -444,7 +454,7 @@ Wiki::articleFromTitle()
 $title: title (object) used to create the article object
 $article: article (object) that will be returned
 
-'ArticleInsertComplete': After a new article is created
+'ArticleInsertComplete': After a new article is created. DEPRECATED, use ArticleContentInsertComplete
 $article: WikiPage created
 $user: User creating the article
 $text: New content
@@ -455,6 +465,17 @@ $section: (No longer used)
 $flags: Flags passed to Article::doEdit()
 $revision: New Revision of the article
 
+'ArticleContentInsertComplete': After a new article is created
+$article: WikiPage created
+$user: User creating the article
+$content: New content as a Content object
+$summary: Edit summary/comment
+$isMinor: Whether or not the edit was marked as minor
+$isWatch: (No longer used)
+$section: (No longer used)
+$flags: Flags passed to Article::doEdit()
+$revision: New Revision of the article
+
 'ArticleMergeComplete': after merging to article using Special:Mergehistory
 $targetTitle: target title (object)
 $destTitle: destination title (object)
@@ -503,7 +524,7 @@ $user: the user who did the rollback
 $revision: the revision the page was reverted back to
 $current: the reverted revision
 
-'ArticleSave': before an article is saved
+'ArticleSave': before an article is saved. DEPRECATED, use ArticleContentSave instead
 $article: the WikiPage (object) being saved
 $user: the user (object) saving the article
 $text: the new article text
@@ -512,7 +533,16 @@ $isminor: minor flag
 $iswatch: watch flag
 $section: section #
 
-'ArticleSaveComplete': After an article has been updated
+'ArticleContentSave': before an article is saved.
+$article: the WikiPage (object) being saved
+$user: the user (object) saving the article
+$content: the new article content, as a Content object
+$summary: the article summary (comment)
+$isminor: minor flag
+$iswatch: watch flag
+$section: section #
+
+'ArticleSaveComplete': After an article has been updated. DEPRECATED, use ArticleContentSaveComplete instead.
 $article: WikiPage modified
 $user: User performing the modification
 $text: New content
@@ -525,6 +555,19 @@ $revision: New Revision of the article
 $status: Status object about to be returned by doEdit()
 $baseRevId: the rev ID (or false) this edit was based on
 
+'ArticleContentSaveComplete': After an article has been updated
+$article: WikiPage modified
+$user: User performing the modification
+$content: New content, as a Content object
+$summary: Edit summary/comment
+$isMinor: Whether or not the edit was marked as minor
+$isWatch: (No longer used)
+$section: (No longer used)
+$flags: Flags passed to Article::doEdit()
+$revision: New Revision of the article
+$status: Status object about to be returned by doEdit()
+$baseRevId: the rev ID (or false) this edit was based on
+
 'ArticleUndelete': When one or more revisions of an article are restored
 $title: Title corresponding to the article restored
 $create: Whether or not the restoration caused the page to be created
@@ -551,11 +594,19 @@ object to both indicate that the output is done and what parser output was used.
 follwed an redirect
 $article: target article (object)
 
-'ArticleViewCustom': allows to output the text of the article in a different format than wikitext
+'ArticleViewCustom': allows to output the text of the article in a different format than wikitext.
+DEPRECATED, use ArticleContentViewCustom instead.
+Note that it is preferrable to implement proper handing for a custom data type using the ContentHandler facility.
 $text: text of the page
 $title: title of the page
 $output: reference to $wgOut
 
+'ArticleContentViewCustom': allows to output the text of the article in a different format than wikitext.
+Note that it is preferrable to implement proper handing for a custom data type using the ContentHandler facility.
+$content: content of the page, as a Content object
+$title: title of the page
+$output: reference to $wgOut
+
 'AuthPluginAutoCreate': Called when creating a local account for an user logged
 in from an external authentication method
 $user: User object created locally
@@ -587,9 +638,14 @@ $name: Image name being checked
 Change $bad and return false to override. If an image is "bad", it is not
 rendered inline in wiki pages or galleries in category pages.
 
-'BeforeInitialize': before anything is initialized in performRequestForTitle()
+'BeforeDisplayNoArticleText': before displaying noarticletext or noarticletext-nopermission
+at Article::showMissingArticle()
+
+$article: article object
+
+'BeforeInitialize': before anything is initialized in MediaWiki::performRequest()
 &$title: Title being used for request
-&$article: The associated Article object
+$unused: null
 &$output: OutputPage object
 &$user: User
 $request: WebRequest object
@@ -599,6 +655,13 @@ $mediaWiki: Mediawiki object
 &$out: OutputPage object
 &$skin: Skin object
 
+'BeforePageRedirect': Prior to sending an HTTP redirect. Gives a chance to
+override how the redirect is output by modifying, or by returning false and
+taking over the output.
+$out: OutputPage object
+&$redirect: URL, modifiable
+&$code: HTTP code (eg '301' or '302'), modifiable
+
 'BeforeParserFetchFileAndTitle': before an image is rendered by Parser
 $parser: Parser object
 $nt: the image title
@@ -671,6 +734,16 @@ the collation given in $collationName.
 'ConfirmEmailComplete': Called after a user's email has been confirmed successfully
 $user: user (object) whose email is being confirmed
 
+'ContentHandlerDefaultModelFor': Called when the default content model is determiend
+for a given title. May be used to assign a different model for that title.
+$title: the Title in question
+&$model: the model name. Use with CONTENT_MODEL_XXX constants.
+
+'ContentHandlerForModelName': Called when a ContentHandler is requested for a given
+cointent model name, but no entry for that model exists in $wgContentHandlers.
+$modeName: the requested content model name
+&$handler: set this to a ContentHandler object, if desired.
+
 'ContribsPager::getQueryInfo': Before the contributions query is about to run
 &$pager: Pager object for contributions
 &$queryInfo: The query for the contribs Pager
@@ -736,12 +809,19 @@ $section: Section being edited
 &$error: Error message to return
 $summary: Edit summary for page
 
-'EditFilterMerged': Post-section-merge edit filter
+'EditFilterMerged': Post-section-merge edit filter.
+DEPRECATED, use EditFilterMergedContent instead.
 $editor: EditPage instance (object)
 $text: content of the edit box
 &$error: error message to return
 $summary: Edit summary for page
 
+'EditFilterMergedContent': Post-section-merge edit filter
+$editor: EditPage instance (object)
+$content: content of the edit box, as a Content object
+&$error: error message to return
+$summary: Edit summary for page
+
 'EditFormPreloadText': Allows population of the edit form when creating
 new pages
 &$text: Text to preload with
@@ -762,12 +842,13 @@ $request: Webrequest
 return value is ignored (should always return true)
 
 'EditPage::showEditForm:fields': allows injection of form field into edit form
-&$editor: the EditPage instance for reference
-&$out: an OutputPage instance to write to
+$editor: the EditPage instance for reference
+$out: an OutputPage instance to write to
 return value is ignored (should always return true)
 
 'EditPage::showEditForm:initial': before showing the edit form
 $editor: EditPage instance (object)
+$out: an OutputPage instance to write to
 
 Return false to halt editing; you'll need to handle error messages, etc.
 yourself. Alternatively, modifying $error and returning true will cause the
@@ -803,14 +884,28 @@ $title: title of page being edited
 &$msg: localization message name, overridable. Default is either 'copyrightwarning' or 'copyrightwarning2'
 
 'EditPageGetDiffText': Allow modifying the wikitext that will be used in
-"Show changes"
+"Show changes". DEPRECATED. Use EditPageGetDiffContent instead.
+Note that it is preferrable to implement diff handling for different data types using the ContentHandler facility.
 $editPage: EditPage object
 &$newtext: wikitext that will be used as "your version"
 
-'EditPageGetPreviewText': Allow modifying the wikitext that will be previewed
+'EditPageGetDiffContent': Allow modifying the wikitext that will be used in
+"Show changes".
+Note that it is preferrable to implement diff handling for different data types using the ContentHandler facility.
+$editPage: EditPage object
+&$newtext: wikitext that will be used as "your version"
+
+'EditPageGetPreviewText': Allow modifying the wikitext that will be previewed.
+DEPRECATED. Use EditPageGetPreviewContent instead.
+Note that it is preferrable to implement previews for different data types using the COntentHandler facility.
 $editPage: EditPage object
 &$toparse: wikitext that will be parsed
 
+'EditPageGetPreviewContent': Allow modifying the wikitext that will be previewed.
+Note that it is preferrable to implement previews for different data types using the COntentHandler facility.
+$editPage: EditPage object
+&$content: Content object to be previewed (may be replaced by hook function)
+
 'EditPageNoSuchSection': When a section edit request is given for an non-existent section
 &$editpage: The current EditPage object
 &$res: the HTML of the error text
@@ -886,6 +981,12 @@ $article: in case all revisions of the file are deleted a reference to the
 $user: user who performed the deletion
 $reason: reason
 
+'FileTransformed': When a file is transformed and moved into storage
+$file: reference to the File object
+$thumb: the MediaTransformOutput object
+$tmpThumbPath: The temporary file system path of the transformed file
+$thumbPath: The permanent storage path of the transformed file
+
 'FileUpload': When a file upload occurs
 $file : Image object representing the file that was uploaded
 $reupload : Boolean indicating if there was a previously another image there or not (since 1.17)
@@ -914,7 +1015,6 @@ $out: OutputPage object
 $title: Title object of page
 $url: string value as output (out parameter, can modify)
 $query: query options passed to Title::getCanonicalURL()
-$variant: variant passed to Title::getCanonicalURL()
 
 'GetDefaultSortkey': Override the default sortkey for a page.
 $title: Title object that we need to get a sortkey for
@@ -924,13 +1024,11 @@ $title: Title object that we need to get a sortkey for
 $title: Title object of page
 $url: string value as output (out parameter, can modify)
 $query: query options passed to Title::getFullURL()
-$variant: variant passed to Title::getFullURL()
 
 'GetInternalURL': modify fully-qualified URLs used for squid cache purging
 $title: Title object of page
 $url: string value as output (out parameter, can modify)
 $query: query options passed to Title::getInternalURL()
-$variant: variant passed to Title::getFullURL()
 
 'GetIP': modify the ip of the current user (called only once)
 &$ip: string holding the ip as determined so far
@@ -949,13 +1047,11 @@ $linkcolour_ids: array of prefixed DB keys of the pages linked to,
 $title: Title object of page
 &$url: string value as output (out parameter, can modify)
 $query: query options passed to Title::getLocalURL()
-$variant: variant passed to Title::getLocalURL()
 
 'GetLocalURL::Internal': modify local URLs to internal pages.
 $title: Title object of page
 &$url: string value as output (out parameter, can modify)
 $query: query options passed to Title::getLocalURL()
-$variant: variant passed to Title::getLocalURL()
 
 'GetLocalURL::Article': modify local URLs specifically pointing to article paths
        without any fancy queries or variants.
@@ -989,6 +1085,11 @@ $result: User permissions error to add. If none, return true.
 'getUserPermissionsErrorsExpensive': Absolutely the same, but is called only
        if expensive checks are enabled.
 
+'GitViewers': called when generating the list of git viewers for Special:Version, use
+       this to change the list.
+&$extTypes: associative array of repo URLS to viewer URLs.
+
+
 'ImageBeforeProduceHTML': Called before producing the HTML created by a wiki
        image insertion.  You can skip the default logic entirely by returning
        false, or just modify a few things using call-by-reference.
@@ -1052,7 +1153,8 @@ Return false to stop further processing of the tag
 
 'ImportHandleRevisionXMLTag': When parsing a XML tag in a page revision
 $reader: XMLReader object
-$revInfo: Array of information
+$pageInfo: Array of page information
+$revisionInfo: Array of revision information
 Return false to stop further processing of the tag
 
 'ImportHandleToplevelXMLTag': When parsing a top level XML tag
@@ -1108,6 +1210,10 @@ $password: The password entered by the user
 &$result: Set this and return false to override the internal checks
 $user: User the password is being validated for
 
+'Language::getMessagesFileName':
+$code: The language code or the language we're looking for a messages file for
+&$file: The messages file path, you can override this to change the location.
+
 'LanguageGetNamespaces': Provide custom ordering for namespaces or
 remove namespaces. Do not use this hook to add namespaces. Use
 CanonicalNamespaces for that.
@@ -1215,7 +1321,7 @@ $param: Associative Array with the following additional options:
  - lim Integer Limit of items to show, default is 50
  - conds Array Extra conditions for the query (e.g. "log_action != 'revision'")
  - showIfEmpty boolean Set to false if you don't want any output in case the loglist is empty if set to true (default), "No matching items in log" is displayed if loglist is empty
- - msgKey Array If you want a nice box with a message, set this to the key of the message. First element is the message key, additional optional elements are parameters for the key that are processed with wgMsgExt and option 'parse'
+ - msgKey Array If you want a nice box with a message, set this to the key of the message. First element is the message key, additional optional elements are parameters for the key that are processed with wfMsgExt and option 'parse'
  - offset Set to overwrite offset parameter in $wgRequest set to '' to unset offset
  - wrap String Wrap the message in html (usually something like "<div ...>$1</div>").
  - flags Integer display flags (NO_ACTION_LINK,NO_EXTRA_USER_LINKS)
@@ -1231,10 +1337,8 @@ $data: Associative array of data for handlers to record. It must include values
  - 'comment'   Wikitext string in the same format as an edit summary
  - 'timestamp' Timestamp when the action occured
 
-'LoginAuthenticateAudit': a login attempt either succeeded or
-failed. This may be called before the User object is populated, so a
-user object equivalent to an anonymous user. No return data is
-accepted; this hook is for auditing only.
+'LoginAuthenticateAudit': a login attempt for a valid user account either
+succeeded or failed. No return data is accepted; this hook is for auditing only.
 $user: the User object being authenticated against
 $password: the password being submitted and found wanting
 $retval: a LoginForm class constant with authenticateUserData() return
@@ -1257,11 +1361,6 @@ $time: timestamp of the log entry (added in 1.12)
 'MaintenanceRefreshLinksInit': before executing the refreshLinks.php maintenance script
 $refreshLinks: RefreshLinks object
 
-'MagicWordMagicWords': When defining new magic word.
-DEPRECATED: use $magicWords in a file listed in
-$wgExtensionMessagesFiles instead.
-$magicWords: array of strings
-
 'MagicWordwgVariableIDs': When definig new magic words IDs.
 $variableIDs: array of strings
 
@@ -1472,6 +1571,7 @@ to modify the parameters of the image.
 $title: title object representing the file
 $file: file object that will be used to create the image
 &$params: 2-D array of parameters
+$parser: Parser object that called the hook
 
 'ParserSectionCreate': Called each time the parser creates a document section
 from wikitext.  Use this to apply per-section modifications to HTML (like
@@ -1553,6 +1653,11 @@ $out: OutputPage object
 'RecentChange_save': called at the end of RecentChange::save()
 $recentChange: RecentChange object
 
+'RequestContextCreateSkin': Called when RequestContext::getSkin creates a skin instance.
+Can be used by an extension override what skin is used in certain contexts.
+IContextSource $context: The RequestContext the skin is being created for.
+&$skin: A variable reference you may set a Skin instance or string key on to override the skin that will be used for the context.
+
 'ResourceLoaderGetConfigVars': called at the end of
 ResourceLoaderStartUpModule::getConfig(). Use this to export static
 configuration variables to JavaScript. Things that depend on the current
@@ -1568,6 +1673,16 @@ scripts.
 loader request or generating HTML output.
 &$resourceLoader: ResourceLoader object
 
+'ResourceLoaderTestModules': let you add new JavaScript testing modules. This is called after the addition of 'qunit' and MediaWiki testing resources.
+&testModules: array of JavaScript testing modules. The 'qunit' framework, included in core, is fed using tests/qunit/QUnitTestResources.php.
+&ResourceLoader object
+To add a new qunit module named 'myext.tests':
+testModules['qunit']['myext.tests'] = array(
+       'script' => 'extension/myext/tests.js',
+       'dependencies' => <any module dependency you might have>
+);
+For qunit framework, the mediawiki.tests.qunit.testrunner dependency will be added to any module.
+
 'RevisionInsertComplete': called after a revision is inserted into the DB
 &$revision: the Revision
 $data: the data stored in old_text.  The meaning depends on $flags: if external
@@ -1609,7 +1724,8 @@ $query : Original query.
 'ShowMissingArticle': Called when generating the output for a non-existent page
 $article: The article object corresponding to the page
 
-'ShowRawCssJs': Customise the output of raw CSS and JavaScript in page views
+'ShowRawCssJs': Customise the output of raw CSS and JavaScript in page views.
+DEPRECATED, use the ContentHandler facility to handle CSS and JavaScript!
 $text: Text being shown
 $title: Title of the custom script/stylesheet page
 $output: Current OutputPage object
@@ -1888,6 +2004,12 @@ $title: The title in question.
 $title: Title object that is being checked
 $result: Boolean; whether MediaWiki currently thinks this is a CSS/JS page. Hooks may change this value to override the return value of Title::isCssOrJsPage()
 
+'TitleIsAlwaysKnown': Called when determining if a page exists.
+Allows overriding default behaviour for determining if a page exists.
+If $isKnown is kept as null, regular checks happen. If it's a boolean, this value is returned by the isKnown method.
+$title: Title object that is being checked
+$result: Boolean|null; whether MediaWiki currently thinks this page is known
+
 'TitleIsMovable': Called when determining if it is possible to move a page.
 Note that this hook is not called for interwiki pages or pages in immovable namespaces: for these, isMovable() always returns false.
 $title: Title object that is being checked
@@ -1905,6 +2027,13 @@ $user: user who did the move
 $pageid: database ID of the page that's been moved
 $redirid: database ID of the created redirect
 
+'TitleReadWhitelist': called at the end of read permissions checks, just before
+       adding the default error message if nothing allows the user to read the page.
+       If a handler wants a title to *not* be whitelisted, it should also return false.
+$title: Title object being checked against
+$user: Current user object
+&$whitelisted: Boolean value of whether this title is whitelisted
+
 'UndeleteForm::showHistory': called in UndeleteForm::showHistory, after a
 PageArchive object has been created but before any further processing is done.
 &$archive: PageArchive object
@@ -1936,15 +2065,11 @@ $article: article "acted on"
 
 'UnwatchArticle': before a watch is removed from an article
 $user: user watching
-$article: article object to be removed
-
-'UnwatchArticle': after a watch is removed from an article
-$user: user that was watching
-$article: article object removed
+$page: WikiPage object to be removed
 
 'UnwatchArticleComplete': after a watch is removed from an article
 $user: user that watched
-$article: article object that was watched
+$page: WikiPage object that was watched
 
 'UploadForm:initial': before the upload form is generated
 $form: UploadForm object
@@ -2050,10 +2175,6 @@ your own hashing method
        hashing method
 &$hash: If the hook returns false, this String will be used as the hash
 
-'UserDisplayName': Called in User::getDisplayName()
-$user: The user object to fetch the display name for
-&$displayName: The display name. Will be null. Set to a name to override default name.
-
 'UserEffectiveGroups': Called in User::getEffectiveGroups()
 $user: User to get groups for
 &$groups: Current effective groups
@@ -2091,7 +2212,6 @@ $user: User object
 'UserGetRights': Called in User::getRights()
 $user: User to get rights for
 &$rights: Current rights
-$namespace: Namespace to get permissions for; if null all namespaces
 
 'UserIsBlockedFrom': Check if a user is blocked from a specific page (for specific block
        exemptions).
@@ -2193,11 +2313,11 @@ used to alter the SQL query which gets the list of wanted pages
 
 'WatchArticle': before a watch is added to an article
 $user: user that will watch
-$article: article object to be watched
+$page: WikiPage object to be watched
 
 'WatchArticleComplete': after a watch is added to an article
 $user: user that watched
-$article: article object watched
+$page: WikiPage object watched
 
 'WatchlistEditorBuildRemoveLine': when building remove lines in
        Special:Watchlist/edit
@@ -2216,9 +2336,9 @@ One, and only one hook should set this, and return false.
 &$opts: Options to use for the query
 &$join: Join conditions
 
-'wfShellMaintenanceCmd': Called when generating a shell-escaped command line
-       string to run a maintenance script.
-&$script: MediaWiki maintenance script path
+'wfShellWikiCmd': Called when generating a shell-escaped command line
+       string to run a MediaWiki cli script.
+&$script: MediaWiki cli script path
 &$parameters: Array of arguments and options to the script
 &$options: Associative array of options, may contain the 'php' and 'wrapper'
        keys