From: Timo Tijhof <krinklemail@gmail.com>
Date: Wed, 30 Apr 2014 18:33:15 +0000 (+0200)
Subject: mediawiki.util: Clean up mw.util.$content
X-Git-Tag: 1.31.0-rc.0~15869^2
X-Git-Url: http://git.cyclocoop.org/url?a=commitdiff_plain;h=dbc16057d91d73428bf161f57565f67173eda473;p=lhc%2Fweb%2Fwiklou.git

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 5185517eb0..7cca5ef702 100644
--- 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 c75e59fb9c..4aae606977 100644
--- 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 5fc737185e..221ac745f6 100644
--- 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,