documented new hooks, deprecated old hooks

diff --git a/docs/hooks.txt b/docs/hooks.txt
index 1a9f41d..49e0801 100644 (file)
--- 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 76f063e..c766afa 100644 (file)
--- 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 1652909..7e11cdd 100644 (file)
--- 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 ce55568..1cceee0 100644 (file)
--- 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 635c44a..99b5d96 100644 (file)
--- 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???