Linker::doEditSectionLink() and Linker::doEditSectionLinkForOther() and their respect...

Make Linker::doEditSectionLink() public, and change its interface to be like that of editSectionLink().  Use that in Parser (which is the only place that uses the old functions that I can find), and mark the old two functions deprecated.  Add a hook 'DoEditSectionLink' with a new, clean interface, which is run immediately before the return so it can override the whole function.  Advise people in hooks.txt to use the new hook, not the old ones.

diff --git a/RELEASE-NOTES b/RELEASE-NOTES
index 133c53c..b96fbaf 100644 (file)
--- a/RELEASE-NOTES
+++ b/RELEASE-NOTES
@@ -29,6 +29,8 @@ it from source control: http://www.mediawiki.org/wiki/Download_from_SVN
 * (bug 8068) New __INDEX__ and __NOINDEX__ magic words allow user control of
   search engine indexing on a per-article basis.
 * Handheld stylesheet options
+* Added 'DoEditSectionLink' hook as a cleaner unified version of the old
+  'EditSectionLink' and 'EditSectionLinkForOther' hooks
 
 === Bug fixes in 1.14 ===
 

diff --git a/docs/hooks.txt b/docs/hooks.txt
index 2ef8cc9..3177ebf 100644 (file)
--- a/docs/hooks.txt
+++ b/docs/hooks.txt
@@ -533,6 +533,17 @@ $newRev: Revision object of the "new" revision
 $article: article (object) being viewed
 $oldid: oldid (int) being viewed
 
+'DoEditSectionLink': Override the HTML generated for section edit links
+$skin: Skin object rendering the UI
+$title: Title object for the title being linked to (may not be the same as
+  $wgTitle, if the section is included from a template)
+$section: The designation of the section being pointed to, to be included in
+  the link, like "&section=$section"
+$tooltip: The default tooltip.  Escape with htmlspecialchars() before using.
+  By default, this is wrapped in the 'editsectionhint' message.
+$result: The HTML to return, prefilled with the default plus whatever other
+  changes earlier hooks have made
+
 'EditFilter': Perform checks on an edit
 $editor: Edit form (see includes/EditPage.php)
 $text: Contents of the edit box
@@ -579,14 +590,14 @@ sections.
 &$editpage: The current EditPage object
 &$buttons: Array of edit buttons "Save", "Preview", "Live", and "Diff"
 
-'EditSectionLink': Override the return value of Linker::editSectionLink()
+'EditSectionLink': Do not use, use DoEditSectionLink instead.
 $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()
+'EditSectionLinkForOther': Do not use, use DoEditSectionLink instead.
 $skin: Skin rendering the UI
 $title: Title being linked to
 $section: Section to link to

diff --git a/includes/Linker.php b/includes/Linker.php
index 03e7a9e..2656b0d 100644 (file)
--- a/includes/Linker.php
+++ b/includes/Linker.php
@@ -1276,6 +1276,7 @@ class Linker {
         * @param $section Integer: section number.
         */
        public function editSectionLinkForOther( $title, $section ) {
+               wfDeprecated( __METHOD__ );
                $title = Title::newFromText( $title );
                return $this->doEditSectionLink( $title, $section, '', 'EditSectionLinkForOther' );
        }
@@ -1286,48 +1287,61 @@ class Linker {
         * @param $hint Link String: title, or default if omitted or empty
         */
        public function editSectionLink( Title $nt, $section, $hint='' ) {
-               if( $hint != '' ) {
-                       $hint = wfMsgHtml( 'editsectionhint', htmlspecialchars( $hint ) );
-                       $hint = " title=\"$hint\"";
-               }
+               wfDeprecated( __METHOD__ );
                return $this->doEditSectionLink( $nt, $section, $hint, 'EditSectionLink' );
        }
 
        /**
-        * Implement editSectionLink and editSectionLinkForOther.
+        * Create a section edit link.  This supersedes editSectionLink() and
+        * editSectionLinkForOther().
         *
-        * @param $nt      Title object
-        * @param $section Integer, section number
-        * @param $hint    String, for HTML title attribute
-        * @param $hook    String, name of hook to run
-        * @return         String, HTML to use for edit link
+        * @param $nt      Title  The title being linked to (may not be the same as
+        *   $wgTitle, if the section is included from a template)
+        * @param $section string The designation of the section being pointed to,
+        *   to be included in the link, like "&section=$section"
+        * @param $tooltip string The tooltip to use for the link: will be escaped
+        *   and wrapped in the 'editsectionhint' message
+        * @return         string HTML to use for edit link
         */
-       protected function doEditSectionLink( Title $nt, $section, $hint, $hook ) {
-               global $wgContLang;
-               $editurl = '&section='.$section;
+       public function doEditSectionLink( Title $nt, $section, $tooltip='' ) {
+               global $wgTitle;
+               $attribs = '';
+               if( $tooltip ) {
+                       $attribs = wfMsgHtml( 'editsectionhint', htmlspecialchars( $tooltip ) );
+                       $attribs = " title=\"$attribs\"";
+               }
+
                $url = $this->makeKnownLinkObj(
                        $nt,
                        htmlspecialchars(wfMsg('editsection')),
-                       'action=edit'.$editurl,
-                       '', '', '',  $hint
+                       "action=edit&section=$section",
+                       '', '', '',  $attribs
                );
-               $result = null;
 
-               // The two hooks have slightly different interfaces . . .
-               if( $hook == 'EditSectionLink' ) {
-                       wfRunHooks( 'EditSectionLink', array( &$this, $nt, $section, $hint, $url, &$result ) );
-               } elseif( $hook == 'EditSectionLinkForOther' ) {
+               # Run the old hooks
+               $result = null;
+               if( $nt->equals( $wgTitle ) ) {
+                       wfRunHooks( 'EditSectionLink', array( &$this, $nt, $section, $attribs, $url, &$result ) );
+               } else {
                        wfRunHooks( 'EditSectionLinkForOther', array( &$this, $nt, $section, $url, &$result ) );
                }
 
-               // For reverse compatibility, add the brackets *after* the hook is run,
-               // and even add them to hook-provided text.
-               if( is_null( $result ) ) {
+               if( !is_null( $result ) ) {
+                       # For reverse compatibility, add the brackets *after* the hook is
+                       # run, and even add them to hook-provided text.  These hooks have
+                       # inconsistent and redundant interfaces, which is why they should
+                       # no longer be used.  Use DoEditSectionLink instead.
                        $result = wfMsgHtml( 'editsection-brackets', $url );
-               } else {
-                       $result = wfMsgHtml( 'editsection-brackets', $result );
+                       return "<span class=\"editsection\">$result</span>";
                }
-               return "<span class=\"editsection\">$result</span>";
+
+               # Add the brackets and the span, and *then* run the nice new hook, with
+               # consistent and non-redundant arguments.
+               $result = wfMsgHtml( 'editsection-brackets', $url );
+               $result = "<span class=\"editsection\">$result</span>";
+
+               wfRunHooks( 'DoEditSectionLink', array( $this, $nt, $section, $tooltip, &$result ) );
+               return $result;
        }
 
        /**

diff --git a/includes/parser/Parser.php b/includes/parser/Parser.php
index 7f00824..c074717 100644 (file)
--- a/includes/parser/Parser.php
+++ b/includes/parser/Parser.php
@@ -3609,9 +3609,9 @@ class Parser
                                if( $isTemplate ) {
                                        # Put a T flag in the section identifier, to indicate to extractSections()
                                        # that sections inside <includeonly> should be counted.
-                                       $editlink = $sk->editSectionLinkForOther($titleText, "T-$sectionIndex");
+                                       $editlink = $sk->doEditSectionLink(Title::newFromText( $titleText ), "T-$sectionIndex");
                                } else {
-                                       $editlink = $sk->editSectionLink($this->mTitle, $sectionIndex, $headlineHint);
+                                       $editlink = $sk->doEditSectionLink($this->mTitle, $sectionIndex, $headlineHint);
                                }
                        } else {
                                $editlink = '';