Add Related Articles section to Minerva

If the page has related articles, is in mainspace, isn't the main page,
and the output is being rendered with the MinervaBeta skin then a
"Related Articles" section is added to the page just before the footer.

Separate loading the information necessary to render the pages, choosing
the renderer, and rendering the data so that multiple skins - currently
Minerva and Vector per the mocks - not just multiple resolutions can all
be handled the same way:

* The bootstrap script (ext.relatedArticles.readMore.bootstrap/index.js)
  for fetches the page image and Wikidata description; loading the
  renderer module; and, finally, notifying the renderer module that it
  should render the data, which it does by emitting
  "ext.relatedArticles.readMore.init" event using mw#track
* The Minerva renderer subscribes to the event and, when it's fired,
  renders the data by passing it to the WatchstarPageList view

Bug: T113635
Change-Id: I651342bdf9796938fa7051828dd13bc6fe774783

.jshintrc

@@ -15,6 +15,7 @@
 
 	"globals": {
 		"mw": false,
-		"$": false
+		"$": false,
+		"jQuery": true
 	}
 }

extension.json

@@ -4,14 +4,16 @@
 	"author": [
 		"Roland Unger",
 		"Hans Musil",
-		"Matthias Mullie"
+		"Matthias Mullie",
+		"Sam Smith"
 	],
 	"url": "https://www.mediawiki.org/wiki/Extension:RelatedArticles",
 	"descriptionmsg": "relatedarticles-desc",
 	"license-name": "GPL-2.0",
-	"type": "parserhook",
+	"type": "other",
 	"AutoloadClasses": {
-		"RelatedArticles\\Hooks": "includes/Hooks.php"
+		"RelatedArticles\\Hooks": "includes/Hooks.php",
+		"RelatedArticles\\ReadMoreHooks": "includes/ReadMoreHooks.php"
 	},
 	"ExtensionMessagesFiles": {
 		"RelatedArticlesMagic": "RelatedArticles.i18n.magic.php"
@@ -34,6 +36,12 @@
 		],
 		"UnitTestsList": [
 			"RelatedArticles\\Hooks::onUnitTestsList"
+		],
+		"MakeGlobalVariablesScript": [
+			"RelatedArticles\\ReadMoreHooks::onMakeGlobalVariablesScript"
+		],
+		"BeforePageDisplay": [
+			"RelatedArticles\\ReadMoreHooks::onBeforePageDisplay"
 		]
 	},
 	"MessagesDirs": {
@@ -41,5 +49,37 @@
 			"i18n"
 		]
 	},
-	"manifest_version": 1
+	"manifest_version": 1,
+	"ResourceModules": {
+		"ext.relatedArticles.readMore.bootstrap": {
+			"scripts": [
+				"resources/ext.relatedArticles.readMore.bootstrap/index.js"
+			],
+			"dependencies": [
+				"mediawiki.api"
+			],
+			"targets": [
+				"mobile",
+				"desktop"
+			]
+		},
+		"ext.relatedArticles.readMore.minerva": {
+			"scripts": [
+				"resources/ext.relatedArticles.readMore.minerva/index.js"
+			],
+			"styles": [
+				"resources/ext.relatedArticles.readMore.minerva/readMore.less"
+			],
+			"messages": [
+				"relatedarticles-read-more-heading"
+			],
+			"targets": [
+				"mobile"
+			]
+		}
+	},
+	"ResourceFileModulePaths": {
+		"localBasePath": "",
+		"remoteExtPath": "RelatedArticles"
+	}
 }

i18n/en.json

@@ -3,5 +3,6 @@
 		"authors": []
 	},
 	"relatedarticles-title": "Related pages",
-	"relatedarticles-desc": "Adds a link to related pages on the sidebar"
-}
+	"relatedarticles-desc": "Adds a link to related pages on the sidebar",
+	"relatedarticles-read-more-heading": "Related Articles"
+}

i18n/qqq.json

@@ -7,5 +7,6 @@
 		]
 	},
 	"relatedarticles-title": "Title shown on the sidebar",
-	"relatedarticles-desc": "{{desc|name=Related Articles|url=https://www.mediawiki.org/wiki/Extension:RelatedArticles}}"
+	"relatedarticles-desc": "{{desc|name=Related Articles|url=https://www.mediawiki.org/wiki/Extension:RelatedArticles}}",
+	"relatedarticles-read-more-heading": "The heading of section, added at the end of the page, that lists the related pages"
 }

includes/ReadMoreHooks.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace RelatedArticles;
+
+use OutputPage;
+use Skin;
+
+class ReadMoreHooks {
+
+	/**
+	 * Handler for the <code>MakeGlobalVariablesScript</code> hook.
+	 *
+	 * Sets the value of the <code>wgRelatedArticles</code> global variable
+	 * to the list of related articles in the cached parser output.
+	 *
+	 * @param array $vars
+	 * @param OutputPage $out
+	 * @return boolean Always <code>true</code>
+	 */
+	public static function onMakeGlobalVariablesScript( &$vars, OutputPage $out ) {
+		$vars['wgRelatedArticles'] = $out->getProperty( 'RelatedArticles' );
+
+		return true;
+	}
+
+	/**
+	 * Handler for the <code>BeforePageDisplay</code> hook.
+	 *
+	 * Adds the <code>ext.relatedArticles.readMore.bootstrap</code> module
+	 * to the output when:
+	 *
+	 * <ol>
+	 *   <li>
+	 *     The output is being rendered with the
+	 *     <code>SkinMinervaBeta<code> skin, i.e. the user is currently
+	 *     viewing the page on the mobile set in beta mode
+	 *   </li>
+	 *   <li>The page is in mainspace</li>
+	 * </ol>
+	 *
+	 * @param OutputPage $out
+	 * @param Skin $skin
+	 * @return boolean Always <code>true</code>
+	 */
+	public static function onBeforePageDisplay( OutputPage $out, Skin $skin ) {
+		$title = $out->getContext()->getTitle();
+
+		if (
+			get_class( $skin ) === 'SkinMinervaBeta' &&
+			$title->inNamespace( NS_MAIN ) &&
+			!$title->isMainPage()
+		) {
+
+			$out->addModules( array( 'ext.relatedArticles.readMore.bootstrap' ) );
+		}
+
+		return true;
+	}
+}

resources/ext.relatedArticles.readMore.bootstrap/index.js

@@ -0,0 +1,78 @@
+( function ( $ ) {
+
+	var relatedArticles = mw.config.get( 'wgRelatedArticles', [] ).slice( 0, 4 ),
+		config = mw.config.get( [ 'skin', 'wgNamespaceNumber', 'wgMFMode', 'wgIsMainPage' ] ),
+		module;
+
+	/**
+	 * Retrieves the data required to render a card.
+	 *
+	 * Given a title, the following additional information is retrieved
+	 * from the API:
+	 *
+	 * * The ID of the page corresponding to the title
+	 * * The thumbnail, if any
+	 * * The Wikidata description, if any
+	 *
+	 * @private
+	 *
+	 * @param {string[]} titles
+	 * @return {jQuery.Promise}
+	 */
+	function getData( titles ) {
+		var api = new mw.Api();
+
+		return api.get( {
+			action: 'query',
+			prop: 'pageimages|pageterms',
+			wbptterms: 'description',
+			pilimit: titles.length,
+			'continue': '',
+
+			titles: titles
+		} ).then( function ( data ) {
+			if ( !data.query || !data.query.pages ) {
+				return [];
+			}
+
+			return $.map( data.query.pages, function ( page ) {
+				var result = {
+					id: page.pageid,
+					title: page.title,
+					thumbnail: page.thumbnail,
+					description: undefined
+				};
+
+				if (
+					page.terms &&
+					page.terms.description &&
+					page.terms.description.length > 0
+				) {
+					result.description = page.terms.description[ 0 ];
+				}
+
+				return result;
+			} );
+		} );
+	}
+
+	if (
+		relatedArticles.length > 0 &&
+		config.wgNamespaceNumber === 0 &&
+		!config.wgIsMainPage &&
+		config.skin === 'minerva' &&
+		config.wgMFMode === 'beta'
+	) {
+		module = 'ext.relatedArticles.readMore.minerva';
+
+		$( function () {
+			$.when(
+				mw.loader.using( module ),
+				getData( relatedArticles )
+			).done( function ( _, data ) {
+				mw.track( 'ext.relatedArticles.init', { pages: data } );
+			} );
+		} );
+	}
+
+}( jQuery ) );

resources/ext.relatedArticles.readMore.minerva/index.js

@@ -0,0 +1,52 @@
+( function ( $ ) {
+
+	var MOBILE_WEB_WATCHING_FUNNEL = 'read-more';
+
+	/**
+	 * Converts the set of pages generated in the init script into a set of
+	 * `Page`s, suitable for use with `WatchstarPageList`.
+	 *
+	 * @param {Object[]} pages
+	 * @return {Page[]}
+	 */
+	function convertPages( pages ) {
+		var Page = mw.mobileFrontend.require( 'mobile.startup/Page' );
+
+		return $.map( pages, function ( rawPage ) {
+			return new Page( {
+				id: rawPage.id,
+				title: rawPage.title,
+				thumbnail: rawPage.thumbnail,
+				wikidataDescription: rawPage.description
+			} );
+		} );
+	}
+
+	mw.trackSubscribe( 'ext.relatedArticles.init', function ( _, data ) {
+		var WatchstarPageList = mw.mobileFrontend.require( 'mobile.pagelist.scripts/WatchstarPageList' ),
+			pageList,
+			$container = $( '#content' ),
+			$readMore;
+
+		pageList = new WatchstarPageList( {
+			pages: convertPages( data.pages ),
+
+			// FIXME: When the user clicks any watchstar, a
+			// MobileWebWatching event is logged. Watchstar, which
+			// logs the event, has a sensible default value for
+			// MobileWebWatching.funnel, but it's overwritten
+			// by WatchstarPageList.
+			funnel: MOBILE_WEB_WATCHING_FUNNEL
+		} );
+
+		$readMore = $( '<aside class="ra-read-more post-content"></aside>' );
+		$readMore.append(
+			$( '<h2></h2>' ).text( mw.msg( 'relatedarticles-read-more-heading' ) )
+		);
+
+		$readMore.append( pageList.$el );
+
+		$container.append( $readMore );
+	} );
+
+}( jQuery ) );

resources/ext.relatedArticles.readMore.minerva/readMore.less

@@ -0,0 +1,25 @@
+@import "mediawiki.ui/variables";
+
+.ra-read-more {
+	margin-top: 35px;
+	margin-bottom: 70px;
+}
+
+.ra-read-more h2 {
+	font-size: 1em;
+	font-weight: bold;
+	color: @colorGray6;
+
+	padding-left: 0.5em;
+	padding-bottom: 0.5em;
+}
+
+.ra-read-more .page-list {
+	border-top: 1px solid @colorGray14;
+}
+
+// See MobileFrontend/resources/mobile.pagelist.styles/pagelist.less for
+// example HTML.
+.ra-read-more .page-summary h3 {
+	color: black;
+}