Add secondary link details: icon & description

We should probably merge this ASAP now that a lot of presentation
models still have to be implemented. There's a bit of B/C code that
will take care of the previous format, but it would be nice to be
able to remove that soon.

Meanwhile I've also changed getPrimaryLink to follow the same format.

Bug: T115421
Change-Id: Ic18a050d2ee0239f287a6d55c572df6f8aebb59a

includes/formatters/EchoFlyoutFormatter.php

@@ -39,8 +39,9 @@ class EchoFlyoutFormatter extends EchoEventFormatter {
 		);
 
 		$footerItems = array( $ts );
-		foreach ( $model->getSecondaryLinks() as $target => $text ) {
-			$footerItems[] = Html::element( 'a', array( 'href' => $target ), $text );
+		$secondaryLinks = $this->normalizeSecondaryLinks( $model->getSecondaryLinks() );
+		foreach ( $secondaryLinks as $link ) {
+			$footerItems[] = Html::element( 'a', array( 'href' => $link['url'] ), $link['label'] );
 		}
 		$html .= Xml::tags(
 			'div',
@@ -51,11 +52,11 @@ class EchoFlyoutFormatter extends EchoEventFormatter {
 		// Add the primary link afterwards, if it has one
 		$primaryLink = $model->getPrimaryLink();
 		if ( $primaryLink !== false ) {
-			list( $primaryUrl, $primaryText ) = $primaryLink;
+			$primaryLink = $this->normalizePrimaryLink( $primaryLink );
 			$html .= Html::element(
 				'a',
-				array( 'class' => 'mw-echo-notification-primary-link', 'href' => $primaryUrl ),
-				$primaryText
+				array( 'class' => 'mw-echo-notification-primary-link', 'href' => $primaryLink['url'] ),
+				$primaryLink['label']
 			) . "\n";
 		}
 
@@ -74,4 +75,53 @@ class EchoFlyoutFormatter extends EchoEventFormatter {
 				$this->language->getDir()
 		);
 	}
+
+	/**
+	 * Utility method to ensure B/C compat with previous getPrimaryLink return
+	 * types, until all of them have been fixed.
+	 *
+	 * @deprecated
+	 * @param string|array|bool $link
+	 * @return string|bool
+	 */
+	protected function normalizePrimaryLink( $link ) {
+		// B/C for old format: [url, label]
+		if ( !isset( $link['url'] ) ) {
+			return array(
+				'url' => $link[0],
+				'label' => $link[1],
+			);
+		}
+
+		// current primary link format: ['url' => ..., 'label' => ...]
+		return $link;
+	}
+
+	/**
+	 * Utility method to ensure B/C compat with previous getSecondaryLinks
+	 * return types, until all of them have been fixed.
+	 *
+	 * @deprecated
+	 * @param array $link
+	 * @return array
+	 */
+	protected function normalizeSecondaryLinks( array $link ) {
+		// B/C for old secondary links format: [url => label, ...]
+		if ( !isset( $link[0] ) || !isset( $link[0]['url'] ) ) {
+			$links = array();
+			foreach ( $link as $url => $text ) {
+				$links[] = array(
+					'url' => $url,
+					'label' => $text,
+					'description' => '',
+					'icon' => false,
+					'prioritized' => false,
+				);
+			}
+			return $links;
+		}
+
+		// current secondary links format: [['url' => ..., 'label' => ..., ...], ...]
+		return $link;
+	}
 }

includes/formatters/EchoModelFormatter.php

@@ -12,6 +12,8 @@ class EchoModelFormatter extends EchoFlyoutFormatter {
 	protected function formatModel( EchoEventPresentationModel $model ) {
 		$data = $model->jsonSerialize();
 		$data['iconUrl'] = EchoNotificationFormatter::getIconUrl( $model->getIconType(), $this->language->getDir() );
+		$data['links']['primary'] = $this->normalizePrimaryLink( $data['links']['primary'] );
+		$data['links']['secondary'] = $this->normalizeSecondaryLinks( $data['links']['secondary'] );
 		return $data;
 	}
 }

includes/formatters/EventPresentationModel.php

@@ -195,18 +195,25 @@ abstract class EchoEventPresentationModel {
 	}
 
 	/**
-	 * Possibly-relative URL to the primary link for this,
-	 * if it has one
+	 * Array of primary link details, with possibly-relative URL & label.
 	 *
-	 * @return array|bool [URL, link text (non-escaped)], false
-	 *                    for no link
+	 * @return array|bool Array of link data, or false for no link:
+	 *                    ['url' => url, 'label' => link text (non-escaped)]
 	 */
 	abstract public function getPrimaryLink();
 
 	/**
-	 * Possibly-relative URLs to the secondary links
+	 * Array of secondary link details, including possibly-relative URLs, label,
+	 * description & icon name.
 	 *
-	 * @return array URL => link text (non-escaped)
+	 * @return array Array of links in the format of:
+	 *               [['url' => url,
+	 *                 'label' => link text (non-escaped),
+	 *                 'description' => descriptive text (non-escaped),
+	 *                 'icon' => symbolic icon name (or false if there is none),
+	 *                 'prioritized' => true if the link should be outside the
+	 *                                  action menu, false for inside)],
+	 *                ...]
 	 */
 	public function getSecondaryLinks() {
 		return array();