From 49ed9dfdd05023cbd5d06881df3d6d57520810e9 Mon Sep 17 00:00:00 2001 From: daniel Date: Thu, 26 Apr 2012 15:12:40 +0200 Subject: [PATCH] documented new hooks, deprecated old hooks --- docs/hooks.txt | 96 +++++++++++++++++++++++++++++++++---- includes/Article.php | 12 ++--- includes/ContentHandler.php | 3 +- includes/EditPage.php | 6 +-- includes/WikiPage.php | 27 ++++++----- 5 files changed, 111 insertions(+), 33 deletions(-) diff --git a/docs/hooks.txt b/docs/hooks.txt index 1a9f41dc88..49e0801a2f 100644 --- a/docs/hooks.txt +++ b/docs/hooks.txt @@ -401,9 +401,14 @@ token types. 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 @@ -449,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 @@ -460,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) @@ -508,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 @@ -517,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 @@ -530,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 @@ -556,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 @@ -688,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 @@ -753,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 @@ -821,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 @@ -1641,7 +1718,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 diff --git a/includes/Article.php b/includes/Article.php index 76f063ea0b..c766afa740 100644 --- a/includes/Article.php +++ b/includes/Article.php @@ -342,8 +342,8 @@ class Article extends Page { $content = $this->fetchContentObject(); - $this->mContent = ContentHandler::getContentText( $content ); #FIXME: get rid of mContent everywhere! - wfRunHooks( 'ArticleAfterFetchContent', array( &$this, &$this->mContent ) ); #BC cruft! + $this->mContent = ContentHandler::getContentText( $content ); #@todo: get rid of mContent everywhere! + wfRunHooks( 'ArticleAfterFetchContent', array( &$this, &$this->mContent ) ); #BC cruft! #XXX: can we deprecate that hook? wfProfileOut( __METHOD__ ); @@ -409,7 +409,7 @@ class Article extends Page { $this->mContentObject = $this->mRevision->getContent( Revision::FOR_THIS_USER ); // Loads if user is allowed $this->mRevIdFetched = $this->mRevision->getId(); - wfRunHooks( 'ArticleAfterFetchContentObject', array( &$this, &$this->mContentObject ) ); #FIXME: register new hook + wfRunHooks( 'ArticleAfterFetchContentObject', array( &$this, &$this->mContentObject ) ); wfProfileOut( __METHOD__ ); @@ -629,10 +629,10 @@ class Article extends Page { wfDebug( __METHOD__ . ": showing CSS/JS source\n" ); $this->showCssOrJsPage(); $outputDone = true; - } elseif( !wfRunHooks( 'ArticleContentViewCustom', array( $this->fetchContentObject(), $this->getTitle(), $wgOut ) ) ) { #FIXME: document new hook! + } elseif( !wfRunHooks( 'ArticleContentViewCustom', array( $this->fetchContentObject(), $this->getTitle(), $wgOut ) ) ) { # Allow extensions do their own custom view for certain pages $outputDone = true; - } elseif( Hooks::isRegistered( 'ArticleViewCustom' ) && !wfRunHooks( 'ArticleViewCustom', array( $this->fetchContent(), $this->getTitle(), $wgOut ) ) ) { #FIXME: fetchContent() is deprecated! #FIXME: deprecate hook! + } elseif( Hooks::isRegistered( 'ArticleViewCustom' ) && !wfRunHooks( 'ArticleViewCustom', array( $this->fetchContent(), $this->getTitle(), $wgOut ) ) ) { #FIXME: fetchContent() is deprecated! # Allow extensions do their own custom view for certain pages $outputDone = true; } else { @@ -781,7 +781,7 @@ class Article extends Page { } // Give hooks a chance to customise the output - if ( !Hooks::isRegistered('ShowRawCssJs') || wfRunHooks( 'ShowRawCssJs', array( $this->fetchContent(), $this->getTitle(), $wgOut ) ) ) { #FIXME: fetchContent() is deprecated #FIXME: hook is deprecated + if ( !Hooks::isRegistered('ShowRawCssJs') || wfRunHooks( 'ShowRawCssJs', array( $this->fetchContent(), $this->getTitle(), $wgOut ) ) ) { #FIXME: fetchContent() is deprecated $po = $this->mContentObject->getParserOutput( $this->getContext() ); $wgOut->addHTML( $po->getText() ); } diff --git a/includes/ContentHandler.php b/includes/ContentHandler.php index 1652909257..7e11cdd77f 100644 --- a/includes/ContentHandler.php +++ b/includes/ContentHandler.php @@ -131,7 +131,7 @@ abstract class ContentHandler { } // hook can determin default model - if ( !wfRunHooks( 'DefaultModelFor', array( $title, &$model ) ) ) { #FIXME: document new hook! + if ( !wfRunHooks( 'ContentHandlerDefaultModelFor', array( $title, &$model ) ) ) { if ( !is_null( $model ) ) { return $model; } @@ -224,7 +224,6 @@ abstract class ContentHandler { if ( empty( $wgContentHandlers[$modelName] ) ) { $handler = null; - // FIXME: document new hook wfRunHooks( 'ContentHandlerForModelName', array( $modelName, &$handler ) ); if ( $handler ) { // NOTE: may be a string or an object, either is fine! diff --git a/includes/EditPage.php b/includes/EditPage.php index ce55568dd0..1cceee0420 100644 --- a/includes/EditPage.php +++ b/includes/EditPage.php @@ -1443,7 +1443,7 @@ class EditPage { // Run post-section-merge edit filter if ( !wfRunHooks( 'EditFilterMerged', array( $this, $content->serialize( $this->content_format ), &$this->hookError, $this->summary ) ) - || !wfRunHooks( 'EditFilterMergedContent', array( $this, $content, &$this->hookError, $this->summary ) ) ) { #FIXME: document new hook + || !wfRunHooks( 'EditFilterMergedContent', array( $this, $content, &$this->hookError, $this->summary ) ) ) { # Error messages etc. could be handled within the hook... $status->fatal( 'hookaborted' ); $status->value = self::AS_HOOK_ERROR; @@ -2526,7 +2526,7 @@ HTML $newContent = ContentHandler::makeContent( $newtext, $this->getTitle(), $newContent->getModelName() ); #XXX: handle parse errors ? } - wfRunHooks( 'EditPageGetDiffContent', array( $this, &$newContent ) ); #FIXME: document new hook + wfRunHooks( 'EditPageGetDiffContent', array( $this, &$newContent ) ); $popts = ParserOptions::newFromUserAndLang( $wgUser, $wgContLang ); $newContent = $newContent->preSaveTransform( $this->mTitle, $wgUser, $popts ); @@ -2826,7 +2826,7 @@ HTML $content = ContentHandler::makeContent( $toparse, $this->getTitle(), $this->content_model, $this->content_format ); } - wfRunHooks( 'EditPageGetPreviewContent', array( $this, &$content ) ); # FIXME: document new hook + wfRunHooks( 'EditPageGetPreviewContent', array( $this, &$content ) ); $parserOptions->enableLimitReport(); diff --git a/includes/WikiPage.php b/includes/WikiPage.php index 635c44a11e..99b5d96e9e 100644 --- a/includes/WikiPage.php +++ b/includes/WikiPage.php @@ -1162,7 +1162,7 @@ class WikiPage extends Page { * @return mixed string on success, false on failure * @deprecated since 1.WD: use ContentHandler::getUndoContent() instead. */ - public function getUndoText( Revision $undo, Revision $undoafter = null ) { #FIXME: replace usages. + public function getUndoText( Revision $undo, Revision $undoafter = null ) { wfDeprecated( __METHOD__, '1.WD' ); $this->loadLastEdit(); @@ -1194,7 +1194,7 @@ class WikiPage extends Page { * * @deprecated since 1.WD, use replaceSectionContent() instead */ - public function replaceSection( $section, $text, $sectionTitle = '', $edittime = null ) { #FIXME: use replaceSectionContent() instead! + public function replaceSection( $section, $text, $sectionTitle = '', $edittime = null ) { wfDeprecated( __METHOD__, '1.WD' ); $sectionContent = ContentHandler::makeContent( $text, $this->getTitle() ); #XXX: could make section title, but that's not required. @@ -1315,7 +1315,7 @@ class WikiPage extends Page { * * @deprecated since 1.WD: use doEditContent() instead. */ - public function doEdit( $text, $summary, $flags = 0, $baseRevId = false, $user = null ) { #FIXME: use doEditContent() instead + public function doEdit( $text, $summary, $flags = 0, $baseRevId = false, $user = null ) { #@todo: use doEditContent() instead wfDeprecated( __METHOD__, '1.WD' ); $content = ContentHandler::makeContent( $text, $this->getTitle() ); @@ -1371,7 +1371,7 @@ class WikiPage extends Page { * @since 1.WD */ public function doEditContent( Content $content, $summary, $flags = 0, $baseRevId = false, - User $user = null, $serialisation_format = null ) { #FIXME: use this + User $user = null, $serialisation_format = null ) { global $wgUser, $wgDBtransactions, $wgUseAutomaticEditSummaries; # Low-level sanity check @@ -1390,14 +1390,14 @@ class WikiPage extends Page { $flags = $this->checkFlags( $flags ); # call legacy hook - $hook_ok = wfRunHooks( 'ArticleContentSave', array( &$this, &$user, &$content, &$summary, #FIXME: document new hook! + $hook_ok = wfRunHooks( 'ArticleContentSave', array( &$this, &$user, &$content, &$summary, $flags & EDIT_MINOR, null, null, &$flags, &$status ) ); if ( $hook_ok && !empty( $wgHooks['ArticleSave'] ) ) { # avoid serialization overhead if the hook isn't present $content_text = $content->serialize(); $txt = $content_text; # clone - $hook_ok = wfRunHooks( 'ArticleSave', array( &$this, &$user, &$txt, &$summary, #FIXME: deprecate legacy hook! + $hook_ok = wfRunHooks( 'ArticleSave', array( &$this, &$user, &$txt, &$summary, $flags & EDIT_MINOR, null, null, &$flags, &$status ) ); if ( $txt !== $content_text ) { @@ -1612,10 +1612,10 @@ class WikiPage extends Page { # Update links, etc. $this->doEditUpdates( $revision, $user, array( 'created' => true ) ); - wfRunHooks( 'ArticleInsertComplete', array( &$this, &$user, $serialized, $summary, #FIXME: deprecate legacy hook + wfRunHooks( 'ArticleInsertComplete', array( &$this, &$user, $serialized, $summary, $flags & EDIT_MINOR, null, null, &$flags, $revision ) ); - wfRunHooks( 'ArticleContentInsertComplete', array( &$this, &$user, $content, $summary, #FIXME: document new hook + wfRunHooks( 'ArticleContentInsertComplete', array( &$this, &$user, $content, $summary, $flags & EDIT_MINOR, null, null, &$flags, $revision ) ); } @@ -1627,10 +1627,10 @@ class WikiPage extends Page { // Return the new revision (or null) to the caller $status->value['revision'] = $revision; - wfRunHooks( 'ArticleSaveComplete', array( &$this, &$user, $serialized, $summary, #FIXME: deprecate legacy hook + wfRunHooks( 'ArticleSaveComplete', array( &$this, &$user, $serialized, $summary, $flags & EDIT_MINOR, null, null, &$flags, $revision, &$status, $baseRevId ) ); - wfRunHooks( 'ArticleContentSaveComplete', array( &$this, &$user, $content, $summary, #FIXME: document new hook + wfRunHooks( 'ArticleContentSaveComplete', array( &$this, &$user, $content, $summary, $flags & EDIT_MINOR, null, null, &$flags, $revision, &$status, $baseRevId ) ); # Promote user to any groups they meet the criteria for @@ -1663,8 +1663,9 @@ class WikiPage extends Page { * * @deprecated in 1.WD: use prepareContentForEdit instead. */ - public function prepareTextForEdit( $text, $revid = null, User $user = null ) { #FIXME: use prepareContentForEdit() instead #XXX: who uses this?! - #TODO: log use of deprecated function + public function prepareTextForEdit( $text, $revid = null, User $user = null ) { + wfDeprecated( __METHOD__, '1.WD' ); + $content = ContentHandler::makeContent( $text, $this->getTitle() ); return $this->prepareContentForEdit( $content, $revid , $user ); } @@ -1682,7 +1683,7 @@ class WikiPage extends Page { * * @since 1.WD */ - public function prepareContentForEdit( Content $content, $revid = null, User $user = null, $serialization_format = null ) { #FIXME: use this #XXX: really public?! + public function prepareContentForEdit( Content $content, $revid = null, User $user = null, $serialization_format = null ) { global $wgParser, $wgContLang, $wgUser; $user = is_null( $user ) ? $wgUser : $user; // @TODO fixme: check $user->getId() here??? -- 2.20.1