X-Git-Url: https://git.heureux-cyclage.org/?a=blobdiff_plain;f=docs%2Fhooks.txt;h=0886c0c37a6134995582f75a2e30995aea23ec78;hb=a0aff8aa1114887fafa2f281a8c53c854dd203c3;hp=f6f3cb9240812ebc1e6d09d35bca2a8ee970412e;hpb=1d24cd2354b5e4733ca6da2ab7f54bed7c703021;p=lhc%2Fweb%2Fwiklou.git diff --git a/docs/hooks.txt b/docs/hooks.txt index f6f3cb9240..0886c0c37a 100644 --- a/docs/hooks.txt +++ b/docs/hooks.txt @@ -35,20 +35,20 @@ order of a title before displaying the article; the other converts the title to all uppercase letters. Currently, in MediaWiki code, we would handle this as follows (note: not real code, here): - function showAnArticle($article) { - global $wgReverseTitle, $wgCapitalizeTitle; - - if ($wgReverseTitle) { - wfReverseTitle($article); - } - - if ($wgCapitalizeTitle) { - wfCapitalizeTitle($article); - } - - # code to actually show the article goes here - } - + function showAnArticle($article) { + global $wgReverseTitle, $wgCapitalizeTitle; + + if ($wgReverseTitle) { + wfReverseTitle($article); + } + + if ($wgCapitalizeTitle) { + wfCapitalizeTitle($article); + } + + # code to actually show the article goes here + } + An extension writer, or a local admin, will often add custom code to the function -- with or without a global variable. For example, someone wanting email notification when an article is shown may add: @@ -75,15 +75,15 @@ Using a hook-running strategy, we can avoid having all this option-specific stuff in our mainline code. Using hooks, the function becomes: - function showAnArticle($article) { + function showAnArticle($article) { - if (wfRunHooks('ArticleShow', array(&$article))) { - - # code to actually show the article goes here - - wfRunHooks('ArticleShowComplete', array(&$article)); + if (wfRunHooks('ArticleShow', array(&$article))) { + + # code to actually show the article goes here + + wfRunHooks('ArticleShowComplete', array(&$article)); + } } - } We've cleaned up the code here by removing clumps of weird, infrequently used code and moving them off somewhere else. It's much @@ -96,24 +96,24 @@ having little title-reversing if-blocks spread all over the codebase in showAnArticle, deleteAnArticle, exportArticle, etc., we can concentrate it all in an extension file: - function reverseArticleTitle($article) { - # ... - } + function reverseArticleTitle($article) { + # ... + } - function reverseForExport($article) { - # ... - } + function reverseForExport($article) { + # ... + } The setup function for the extension just has to add its hook functions to the appropriate events: - setupTitleReversingExtension() { - global $wgHooks; - - $wgHooks['ArticleShow'][] = 'reverseArticleTitle'; - $wgHooks['ArticleDelete'][] = 'reverseArticleTitle'; - $wgHooks['ArticleExport'][] = 'reverseForExport'; - } + setupTitleReversingExtension() { + global $wgHooks; + + $wgHooks['ArticleShow'][] = 'reverseArticleTitle'; + $wgHooks['ArticleDelete'][] = 'reverseArticleTitle'; + $wgHooks['ArticleExport'][] = 'reverseForExport'; + } Having all this code related to the title-reversion option in one place means that it's easier to read and understand; you don't have to @@ -124,8 +124,8 @@ used -- making for some slight savings in memory and load-up performance at runtime. Admins who want to have all the reversed titles can add: - require_once('extensions/ReverseTitle.php'); - + require_once('extensions/ReverseTitle.php'); + ...to their LocalSettings.php file; those of us who don't want or need it can just leave it out. @@ -143,31 +143,31 @@ A hook is a chunk of code run at some particular event. It consists of: Hooks are registered by adding them to the global $wgHooks array for a given event. All the following are valid ways to define hooks: - $wgHooks['EventName'][] = 'someFunction'; # function, no data - $wgHooks['EventName'][] = array('someFunction', $someData); - $wgHooks['EventName'][] = array('someFunction'); # weird, but OK - - $wgHooks['EventName'][] = $object; # object only - $wgHooks['EventName'][] = array($object, 'someMethod'); - $wgHooks['EventName'][] = array($object, 'someMethod', $someData); - $wgHooks['EventName'][] = array($object); # weird but OK + $wgHooks['EventName'][] = 'someFunction'; # function, no data + $wgHooks['EventName'][] = array('someFunction', $someData); + $wgHooks['EventName'][] = array('someFunction'); # weird, but OK + + $wgHooks['EventName'][] = $object; # object only + $wgHooks['EventName'][] = array($object, 'someMethod'); + $wgHooks['EventName'][] = array($object, 'someMethod', $someData); + $wgHooks['EventName'][] = array($object); # weird but OK When an event occurs, the function (or object method) will be called with the optional data provided as well as event-specific parameters. The above examples would result in the following code being executed when 'EventName' happened: - # function, no data - someFunction($param1, $param2) - # function with data - someFunction($someData, $param1, $param2) - - # object only - $object->onEventName($param1, $param2) - # object with method - $object->someMethod($param1, $param2) - # object with method and data - $object->someMethod($someData, $param1, $param2) + # function, no data + someFunction($param1, $param2) + # function with data + someFunction($someData, $param1, $param2) + + # object only + $object->onEventName($param1, $param2) + # object with method + $object->someMethod($param1, $param2) + # object with method and data + $object->someMethod($someData, $param1, $param2) Note that when an object is the hook, and there's no specified method, the default method called is 'onEventName'. For different events this @@ -176,8 +176,8 @@ would be different: 'onArticleSave', 'onUserLogin', etc. The extra data is useful if we want to use the same function or object for different purposes. For example: - $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'TimStarling'); - $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'brion'); + $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'TimStarling'); + $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'brion'); This code would result in ircNotify being run twice when an article is saved: once for 'TimStarling', and once for 'brion'. @@ -195,12 +195,12 @@ the main functionality. For example, if you wanted to authenticate users to a custom system (LDAP, another PHP program, whatever), you could do: - $wgHooks['UserLogin'][] = array('ldapLogin', $ldapServer); - - function ldapLogin($username, $password) { - # log user into LDAP - return false; - } + $wgHooks['UserLogin'][] = array('ldapLogin', $ldapServer); + + function ldapLogin($username, $password) { + # log user into LDAP + return false; + } Returning false makes less sense for events where the action is complete, and will normally be ignored. @@ -210,14 +210,15 @@ complete, and will normally be ignored. A calling function or method uses the wfRunHooks() function to run the hooks related to a particular event, like so: - class Article { - # ... - function protect() { - global $wgUser; - if (wfRunHooks('ArticleProtect', array(&$this, &$wgUser))) { - # protect the article - wfRunHooks('ArticleProtectComplete', array(&$this, &$wgUser)); - } + class Article { + # ... + function protect() { + global $wgUser; + if (wfRunHooks('ArticleProtect', array(&$this, &$wgUser))) { + # protect the article + wfRunHooks('ArticleProtectComplete', array(&$this, &$wgUser)); + } + } } wfRunHooks() returns true if the calling function should continue @@ -237,12 +238,24 @@ protocol came about after MediaWiki 1.4rc1. This is a list of known events and parameters; please add to it if you're going to add events to the MediaWiki code. +'AbortLogin': Return false to cancel account login. +$user: the User object being authenticated against +$password: the password being submitted, not yet checked for validity +&$retval: a LoginForm class constant to return from authenticateUserData(); + default is LoginForm::ABORTED. Note that the client may be using + a machine API rather than the HTML user interface. + 'AbortNewAccount': Return false to cancel account creation. $user: the User object about to be created (read-only, incomplete) $message: out parameter: error message to display on abort 'AddNewAccount': after a user account is created -null: This hook passes null as an argument +$user: the User object that was created. (Parameter added in 1.7) + +'AlternateEdit': before checking if an user can edit a page and +before showing the edit form ( EditPage::edit() ). This is triggered +on &action=edit. +$EditPage : the EditPage object 'ArticleDelete': before an article is deleted $article: the article (object) being deleted @@ -286,9 +299,50 @@ $isminor: minor flag $iswatch: watch flag $section: section # +'ArticleUndeleted': 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 +(i.e. it didn't exist before) + +'ArticleViewHeader': Before the parser cache is about to be tried for article viewing. +&$pcache: whether to try the parser cache or not +&$outputDone: whether the output for this page finished or not + +'AuthPluginSetup': update or replace authentication plugin object ($wgAuth) +Gives a chance for an extension to set it programattically to a variable class. +&$auth: the $wgAuth object, probably a stub + 'AutoAuthenticate': called to authenticate users on external/environmental means $user: writes user object to this parameter +'BadImage': When checking against the bad image list +$name: Image name being checked +&$bad: Whether or not the image is "bad" + +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. + +'BeforeGalleryFindFile': before an image is fetched for a gallery +&$gallery,: the gallery object +&$nt: the image title +&$time: image timestamp + +'BeforeParserFetchTemplateAndtitle': before a template is fetched by Parser +&$parser: Parser object +&$title: title of the template +&$skip: skip this template and link it? +&$id: the id of the revision being parsed + +'BeforeParserMakeImageLinkObj': before an image is rendered by Parser +&$parser: Parser object +&$nt: the image title +&$skip: skip this image and link it? +&$time: the image timestamp + +'BeforeParserrenderImageGallery': before an image gallery is rendered by Parser +&$parser: Parser object +&$ig: ImageGallery object + 'BlockIp': before an IP address or user is blocked $block: the Block object about to be saved $user: the user _doing_ the block (not the one being blocked) @@ -297,6 +351,68 @@ $user: the user _doing_ the block (not the one being blocked) $block: the Block object that was saved $user: the user who did the block (not the one being blocked) +'BookInformation': Before information output on Special:Booksources +$isbn: ISBN to show information for +$output: OutputPage object in use + +'CustomEditor': When invoking the page editor +$article: Article being edited +$user: User performing the edit + +Return true to allow the normal editor to be used, or false +if implementing a custom editor, e.g. for a special namespace, +etc. + +'DiffViewHeader': called before diff display +$diff: DifferenceEngine object that's calling +$oldRev: Revision object of the "old" revision (may be null/invalid) +$newRev: Revision object of the "new" revision + +'EditPage::attemptSave': called before an article is +saved, that is before insertNewArticle() is called +&$editpage_Obj: the current EditPage object + +'EditFormPreloadText': Allows population of the edit form when creating new pages +&$text: Text to preload with +&$title: Title object representing the page being created + +'EditPage::showEditForm:fields': allows injection of form field into edit form +&$editor: the EditPage instance for reference +&$out: an OutputPage instance to write to +return value is ignored (should always return true) + +'EditFilter': Perform checks on an edit +$editor: Edit form (see includes/EditPage.php) +$text: Contents of the edit box +$section: Section being edited +&$error: Error message to return + +Return false to halt editing; you'll need to handle error messages, etc. yourself. +Alternatively, modifying $error and returning true will cause the contents of $error +to be echoed at the top of the edit form as wikitext. Return true without altering +$error to allow the edit to proceed. + +'EditSectionLink': Override the return value of Linker::editSectionLink() +$skin: Skin rendering the UI +$title: Title being linked to +$section: Section to link to +$link: Default link +$result: Result (alter this to override the generated links) + +'EditSectionLinkForOther': Override the return value of Linker::editSectionLinkForOther() +$skin: Skin rendering the UI +$title: Title being linked to +$section: Section to link to +$hint: Anchor title/tooltip attributes +$link: Default link +$result: Result (alter this to override the generated links) + +'EmailConfirmed': When checking that the user's email address is "confirmed" +$user: User being checked +$confirmed: Whether or not the email address is confirmed +This runs before the other checks, such as anonymity and the real check; return +true to allow those checks to occur, and false if checking is done. + 'EmailUser': before sending email from one user to another $to: address of receiving user $from: address of sending user @@ -309,6 +425,15 @@ $from: address of sending user $subject: subject of the mail $text: text of the mail +'FetchChangesList': When fetching the ChangesList derivative for a particular user +&$user: User the list is being fetched for +&$skin: Skin object to be used with the list +&$list: List object (defaults to NULL, change it to an object instance and return +false override the list derivative used) + +'FileUpload': When a file upload occurs +$file : Image object representing the file that was uploaded + 'GetInternalURL': modify fully-qualified URLs used for squid cache purging $title: Title object of page $url: string value as output (out parameter, can modify) @@ -324,14 +449,33 @@ $title: Title object of page $url: string value as output (out parameter, can modify) $query: query options passed to Title::getFullURL() -'LogPageValidTypes': action being logged. -$type: array of strings +'ImageOpenShowImageInlineBefore': Call potential extension just before showing the image on an image page +$imagePage: ImagePage object ($this) +$output: $wgOut + +'InternalParseBeforeLinks': during Parser's internalParse method before links but +after noinclude/includeonly/onlyinclude and other processing. +&$this: Parser object +&$text: string containing partially parsed text +&$this->mStripState: Parser's internal StripState object + +'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 value (SUCCESS, WRONG_PASS, etc) + +'LogPageValidTypes': action being logged. DEPRECATED: Use $wgLogTypes +&$type: array of strings -'LogPageLogName': name of the logging page(s). -$typeText: array of strings +'LogPageLogName': name of the logging page(s). DEPRECATED: Use $wgLogNames +&$typeText: array of strings -'LogPageLogHeader': strings used by wfMsg as a header. -$headerText: array of strings +'LogPageLogHeader': strings used by wfMsg as a header. DEPRECATED: Use $wgLogHeaders +&$headerText: array of strings + +'LogPageActionText': strings used by wfMsg as a header. DEPRECATED: Use $wgLogActions +&$actionText: array of strings 'MarkPatrolled': before an edit is marked patrolled $rcid: ID of the revision to be marked patrolled @@ -345,16 +489,76 @@ $user: user (object) who marked the edit patrolled $wcOnlySysopsCanPatrol: config setting indicating whether the user must be a sysop to patrol the edit +'MathAfterTexvc': after texvc is executed when rendering mathematics +$mathRenderer: instance of MathRenderer +$errmsg: error message, in HTML (string). Nonempty indicates failure + of rendering the formula + 'OutputPageBeforeHTML': a page has been processed by the parser and the resulting HTML is about to be displayed. $parserOutput: the parserOutput (object) that corresponds to the page $text: the text that will be displayed, in HTML (string) +'PageHistoryBeforeList': When a history page list is about to be constructed. +$article: the article that the history is loading for + +'PageHistoryLineEnding' : right before the end
  • is added to a history line +$row: the revision row for this line +$s: the string representing this parsed line + 'PageRenderingHash': alter the parser cache option hash key A parser extension which depends on user options should install this hook and append its values to the key. $hash: reference to a hash key string which can be modified +'ParserTestTables': alter the list of tables to duplicate when parser tests +are run. Use when page save hooks require the presence of custom tables +to ensure that tests continue to run properly. +&$tables: array of table names + +'PersonalUrls': Alter the user-specific navigation links (e.g. "my page, +my talk page, my contributions" etc). + +&$personal_urls: Array of link specifiers (see SkinTemplate.php) +&$title: Title object representing the current page + +'PingLimiter': Allows extensions to override the results of User::pingLimiter() +&$user : User performing the action +$action : Action being performed +&$result : Whether or not the action should be prevented +Change $result and return false to give a definitive answer, otherwise +the built-in rate limiting checks are used, if enabled. + +'PreferencesUserInformationPanel': Add HTML bits to user information list in preferences form +$form : PreferencesForm object +&$html : HTML to append to + +'RawPageViewBeforeOutput': Right before the text is blown out in action=raw +&$obj: RawPage object +&$text: The text that's going to be the output + +'SearchUpdate': Prior to search update completion +$id : Page id +$namespace : Page namespace +$title : Page title +$text : Current text being indexed + +'SiteNoticeBefore': Before the sitenotice/anonnotice is composed +&$siteNotice: HTML returned as the sitenotice +Return true to allow the normal method of notice selection/rendering to work, +or change the value of $siteNotice and return false to alter it. + +'SiteNoticeAfter': After the sitenotice/anonnotice is composed +&$siteNotice: HTML sitenotice +Alter the contents of $siteNotice to add to/alter the sitenotice/anonnotice. + +'SkinTemplateOutputPageBeforeExec': Before SkinTemplate::outputPage() starts page output +&$sktemplate: SkinTemplate object +&$tpl: Template engine object + +'TitleLinkUpdatesAfterCompletion': after Linker->doUpdate() is called +&$title: title of the updated page + 'TitleMoveComplete': after moving an article (title) $old: old title $nt: new title @@ -375,16 +579,31 @@ $article: article object to be removed $user: user that was watching $article: article object removed +'UploadForm:initial': before the upload form is generated +$form: UploadForm object +You might set the member-variables $uploadFormTextTop and +$uploadFormTextAfterSummary to inject text (HTML) either before +or after the editform. + +'UploadForm:BeforeProcessing': at the beginning of processUpload() +$form: UploadForm object +Lets you poke at member variables like $mUploadDescription before the +file is saved. + 'UploadVerification': additional chances to reject an uploaded file string $saveName: destination file name string $tempName: filesystem path to the temporary file for checks string &$error: output: HTML error to show if upload canceled by returning false -'UserCan': To interrupt the "user can do X to Y article" check +'UploadComplete': Upon completion of a file upload +$image: Image object representing the file that was uploaded + +'UserCan': To interrupt/advise the "user can do X to Y article" check $title: Title object being checked against $user : Current user object $action: Action being checked -$result: Pointer to result returned if hook returns false +$result: Pointer to result returned if hook returns false. If null is returned, + UserCan checks are continued by internal code 'UserCreateForm': change to manipulate the login form $template: SimpleTemplate instance for the form @@ -400,6 +619,11 @@ $user: the user object that is about to be logged out 'UserLogoutComplete': after a user has logged out $user: the user object _after_ logout (won't have name, ID, etc.) + +'UserRights': After a user's group memberships are changed +$user : User object that was changed +$add : Array of strings corresponding to groups added +$remove: Array of strings corresponding to groups removed 'WatchArticle': before a watch is added to an article $user: user that will watch @@ -409,14 +633,28 @@ $article: article object to be watched $user: user that watched $article: article object watched +'UnwatchArticleComplete': after a watch is removed from an article +$user: user that watched +$article: article object that was watched + 'CategoryPageView': before viewing a categorypage in CategoryPage::view $catpage: CategoryPage instance 'SkinTemplateContentActions': after building the $content_action array right - before returning it, see content_action.php in - the extension module for a demonstration of how - to use this hook. + before returning it, see Content_action.php in + the extensions/examples/ directory + ( http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/examples/ ) + for a demonstration of how to use this hook. $content_actions: The array of content actions +'BeforePageDisplay': Called just before outputting a page (all kinds of, + articles, special, history, preview, diff, edit, ...) + Can be used to set custom CSS/JS +$out: OutputPage object + +'AjaxAddScript': Called in output page just before the initialisation +of the javascript ajax engine. The hook is only called when ajax +is enabled ( $wgUseAjax = true; ). -More hooks might be available but undocumented. +More hooks might be available but undocumented, you can execute +./maintenance/findhooks.php to find hidden one.