diff options
Diffstat (limited to 'docs/hooks.txt')
| -rw-r--r-- | docs/hooks.txt | 332 |
1 files changed, 238 insertions, 94 deletions
diff --git a/docs/hooks.txt b/docs/hooks.txt index 9f5d289f..9614bead 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,6 +238,13 @@ 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 @@ -244,6 +252,15 @@ $message: out parameter: error message to display on abort 'AddNewAccount': after a user account is created $user: the User object that was created. (Parameter added in 1.7) +'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; ). + +'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 $user: the user (object) deleting the article @@ -254,6 +271,17 @@ $article: the article that was deleted $user: the user that deleted the article $reason: the reason the article was deleted +'ArticleInsertComplete': After an article is created +$article: Article created +$user: User creating the article +$text: New content +$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 + 'ArticleProtect': before an article is protected $article: the article being protected $user: the user doing the protection @@ -277,6 +305,17 @@ $isminor: minor flag $iswatch: watch flag $section: section # +'ArticleSaveComplete': After an article has been updated +$article: Article modified +$user: User performing the modification +$text: New content +$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 + 'ArticleSaveComplete': after an article is saved $article: the article (object) saved $user: the user (object) who saved the article @@ -286,11 +325,22 @@ $isminor: minor flag $iswatch: watch flag $section: section # +wfRunHooks( 'ArticleSaveComplete', array( &$this, &$wgUser, $text, $summary, $flags & EDIT_MINOR, null, null, &$flags, $revision ) ); + '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 + +'ArticleUpdateBeforeRedirect': After a page is updated (usually on save), before the user is redirected back to the page +&$article: the article +&$sectionanchor: The section anchor link (e.g. "#overview" ) +&$extraq: Extra query parameters which can be added via hooked functions + '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 @@ -305,6 +355,30 @@ $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. +'BeforeGalleryFindFile': before an image is fetched for a gallery +&$gallery,: the gallery object +&$nt: the image title +&$time: image timestamp + +'BeforePageDisplay': Prior to outputting a page +$out: OutputPage object + +'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) @@ -317,6 +391,14 @@ $user: the user who did the block (not the one being blocked) $isbn: ISBN to show information for $output: OutputPage object in use +'CategoryPageView': before viewing a categorypage in CategoryPage::view +$catpage: CategoryPage instance + +'ContributionsToolLinks': Change tool links above Special:Contributions +$id: User identifier +$title: User page title +&$tools: Array of tool links + 'CustomEditor': When invoking the page editor $article: Article being edited $user: User performing the edit @@ -354,6 +436,21 @@ Alternatively, modifying $error and returning true will cause the contents of $e 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 @@ -396,12 +493,34 @@ $title: Title object of page $url: string value as output (out parameter, can modify) $query: query options passed to Title::getFullURL() +'ImageOpenShowImageInlineBefore': Call potential extension just before showing the image on an image page +$imagePage: ImagePage object ($this) +$output: $wgOut + +'InitPreferencesForm': called at the end of PreferencesForm's constructor +$form: the PreferencesForm +$request: the web request to initialized from + '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 +'isValidPassword': Override the result of User::isValidPassword() +$password: Desired password +&$result: Set this and return false to override the internal checks +$user: User the password is being validated for + +'LinksUpdateConstructed': At the end of LinksUpdate() is contruction. +&$linksUpdate: the LinkUpdate 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 @@ -474,12 +593,31 @@ $form : PreferencesForm object &$obj: RawPage object &$text: The text that's going to be the output +'RenderPreferencesForm': called at the end of PreferencesForm::mainPrefsForm +$form: the PreferencesForm +$out: output page to render to, probably $wgOut + +'ResetPreferences': called at the end of PreferencesForm::resetPrefs +$form: the PreferencesForm +$user: the User object to load preferences from + +'SavePreferences': called at the end of PreferencesForm::savePreferences; + returning false prevents the preferences from being saved. +$form: the PreferencesForm +$user: the User object to save preferences to +$message: change this to set an error message (ignored if the hook does notreturn fals) + 'SearchUpdate': Prior to search update completion $id : Page id $namespace : Page namespace $title : Page title $text : Current text being indexed +'ShowRawCssJs': Customise the output of raw CSS and JavaScript in page views +$text: Text being shown +$title: Title of the custom script/stylesheet page +$output: Current OutputPage object + '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, @@ -489,10 +627,23 @@ or change the value of $siteNotice and return false to alter it. &$siteNotice: HTML sitenotice Alter the contents of $siteNotice to add to/alter the sitenotice/anonnotice. +'SkinAfterBottomScripts': At the end of Skin::bottomScripts() +$skin: Skin object +&$text: bottomScripts Text +Append to $text to add additional text/scripts after the stock bottom scripts. + +'SkinTemplateContentActions': Alter the "content action" links in SkinTemplates +&$content_actions: Content actions +[See http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/examples/Content_action.php +for an example] + 'SkinTemplateOutputPageBeforeExec': Before SkinTemplate::outputPage() starts page output &$sktemplate: SkinTemplate object &$tpl: Template engine object +'SpecialContributionsBeforeMainOutput': Before the form on Special:Contributions +$id: User identifier + 'TitleMoveComplete': after moving an article (title) $old: old title $nt: new title @@ -513,6 +664,10 @@ $article: article object to be removed $user: user that was watching $article: article object removed +'UnwatchArticleComplete': after a watch is removed from an article +$user: user that watched +$article: article object that was watched + 'UploadForm:initial': before the upload form is generated $form: UploadForm object You might set the member-variables $uploadFormTextTop and @@ -559,6 +714,17 @@ $user : User object that was changed $add : Array of strings corresponding to groups added $remove: Array of strings corresponding to groups removed +'UserGetImplicitGroups': Called in User::getImplicitGroups() +&$groups: List of implicit (automatically-assigned) groups + +'UserGetRights': Called in User::getRights() +$user: User to get rights for +&$rights: Current rights + +'UserEffectiveGroups': Called in User::getEffectiveGroups() +$user: User to get groups for +&$groups: Current effective groups + 'WatchArticle': before a watch is added to an article $user: user that will watch $article: article object to be watched @@ -567,28 +733,6 @@ $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 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, you can execute -./maintenance/findhooks.php to find hidden one. +./maintenance/findhooks.php to find hidden one.
\ No newline at end of file |