mediawiki.util: Clean up mw.util.$content

* Document how to use it (including the tricky bit with it needing
 a dependency on mediawiki.page.startup).

* Refer to mw.hook and #mw-content-text as recommended method of
  getting just the wikipage content.

* Remove the deprecated backwards-compatibility selectors.
  The core skins (Vector, Monobook, Modern, CologneBlue) all
  have mw-body now. Third-party skins should adopt those if they
  haven't already.

Change-Id: I30bdd893e0a0a340076efa7ce32fbd4b775bc3db

diff --git a/RELEASE-NOTES-1.24 b/RELEASE-NOTES-1.24
index 5185517..7cca5ef 100644 (file)
--- a/RELEASE-NOTES-1.24
+++ b/RELEASE-NOTES-1.24
@@ -44,6 +44,9 @@ changes to languages because of Bugzilla reports.
 * The deprecated function mw.util.toggleToc was removed.
 * The Special:Search hooks SpecialSearchGo and SpecialSearchResultsAppend
   were removed as they were unused.
+* mediawiki.util.$content no longer supports old versions of the Vector,
+  Monobook, Modern and CologneBlue skins that don't yet implement the "mw-body"
+  and/or "mw-body-primary" class name in their html.
 
 ==== Renamed classes ====
 * CLDRPluralRuleConverter_Expression to CLDRPluralRuleConverterExpression

diff --git a/resources/src/mediawiki.page/mediawiki.page.startup.js b/resources/src/mediawiki.page/mediawiki.page.startup.js
index c75e59f..4aae606 100644 (file)
--- a/resources/src/mediawiki.page/mediawiki.page.startup.js
+++ b/resources/src/mediawiki.page/mediawiki.page.startup.js
@@ -9,10 +9,6 @@
                .removeClass( 'client-nojs' );
 
        $( function () {
-               // Initialize utilities as soon as the document is ready (mw.util.$content).
-               // In the domready here instead of in mediawiki.page.ready to ensure that it gets enqueued
-               // before other modules hook into domready, so that mw.util.$content (defined by
-               // mw.util.init), is defined for them.
                mw.util.init();
 
                /**

diff --git a/resources/src/mediawiki/mediawiki.util.js b/resources/src/mediawiki/mediawiki.util.js
index 5fc7371..221ac74 100644 (file)
--- a/resources/src/mediawiki/mediawiki.util.js
+++ b/resources/src/mediawiki/mediawiki.util.js
@@ -13,49 +13,33 @@
                 * (don't call before document ready)
                 */
                init: function () {
-                       /* Fill $content var */
                        util.$content = ( function () {
-                               var i, l, $content, selectors;
+                               var i, l, $node, selectors;
+
                                selectors = [
-                                       // The preferred standard for setting $content (class="mw-body")
-                                       // You may also use (class="mw-body mw-body-primary") if you use
-                                       // mw-body in multiple locations.
-                                       // Or class="mw-body-primary" if you want $content to be deeper
-                                       // in the dom than mw-body
+                                       // The preferred standard is class "mw-body".
+                                       // You may also use class "mw-body mw-body-primary" if you use
+                                       // mw-body in multiple locations. Or class "mw-body-primary" if
+                                       // you use mw-body deeper in the DOM.
                                        '.mw-body-primary',
                                        '.mw-body',
 
-                                       /* Legacy fallbacks for setting the content */
-                                       // Vector, Monobook, Chick, etc... based skins
-                                       '#bodyContent',
-
-                                       // Modern based skins
-                                       '#mw_contentholder',
-
-                                       // Standard, CologneBlue
-                                       '#article',
-
-                                       // #content is present on almost all if not all skins. Most skins (the above cases)
-                                       // have #content too, but as an outer wrapper instead of the article text container.
-                                       // The skins that don't have an outer wrapper do have #content for everything
-                                       // so it's a good fallback
-                                       '#content',
-
-                                       // If nothing better is found fall back to our bodytext div that is guaranteed to be here
+                                       // If the skin has no such class, fall back to the parser output
                                        '#mw-content-text',
 
-                                       // Should never happen... well, it could if someone is not finished writing a skin and has
-                                       // not inserted bodytext yet. But in any case <body> should always exist
+                                       // Should never happen... well, it could if someone is not finished writing a
+                                       // skin and has not yet inserted bodytext yet.
                                        'body'
                                ];
+
                                for ( i = 0, l = selectors.length; i < l; i++ ) {
-                                       $content = $( selectors[i] ).first();
-                                       if ( $content.length ) {
-                                               return $content;
+                                       $node = $( selectors[i] );
+                                       if ( $node.length ) {
+                                               return $node.first();
                                        }
                                }
 
-                               // Make sure we don't unset util.$content if it was preset and we don't find anything
+                               // Preserve existing customized value in case it was preset
                                return util.$content;
                        }() );
                },
@@ -202,10 +186,24 @@
                        $nodes.updateTooltipAccessKeys();
                },
 
-               /*
+               /**
+                * The content wrapper of the skin (e.g. `.mw-body`).
+                *
+                * Populated on document ready by #init. To use this property,
+                * wait for `$.ready` and be sure to have a module depedendency on
+                * `mediawiki.util` and `mediawiki.page.startup` which will ensure
+                * your document ready handler fires after #init.
+                *
+                * Because of the lazy-initialised nature of this property,
+                * you're discouraged from using it.
+                *
+                * If you need just the wikipage content (not any of the
+                * extra elements output by the skin), use `$( '#mw-content-text' )`
+                * instead. Or listen to mw.hook#wikipage_content which will
+                * allow your code to re-run when the page changes (e.g. live preview
+                * or re-render after ajax save).
+                *
                 * @property {jQuery}
-                * A jQuery object that refers to the content area element.
-                * Populated by #init.
                 */
                $content: null,