feature(river): convert river JS to AMD modules

Deprecates elgg.ui.river library in favour of component AMD modules.
Autofocusing of the comment input in river is no longer dependant on the
the river selector being present on the page (that was the only view loading
the JS library).

docs/guides/upgrading.rst

@@ -9,6 +9,19 @@ See the administrator guides for :doc:`how to upgrade a live site </admin/upgrad
    :local:
    :depth: 2
 
+From 2.1 to 2.2
+===============
+
+Deprecated APIs
+---------------
+
+ * ``elgg.ui.river`` JavaScript library: Remove calls to ``elgg_load_js('elgg.ui.river')`` from plugin code. Update ``core/river/filter`` and ``forms/comment/save``, if overwritten, to require component AMD modules
+
+Deprecated Views
+----------------
+
+ * ``elgg/ui.river.js`` is deprecated: Do not rely on simplecache URLs to work.
+
 From 2.0 to 2.1
 ===============
 

engine/lib/river.php

@@ -832,6 +832,12 @@ function _elgg_river_init() {
 	elgg_register_action('river/delete', '', 'admin');
 
 	elgg_register_plugin_hook_handler('unit_test', 'system', '_elgg_river_test');
+
+	// For BC, we want required AMD modules to be loaded even if plugins
+	// overwrite these views
+	elgg_extend_view('core/river/filter', 'core/river/filter_deps');
+	elgg_extend_view('forms/comment/save', 'forms/comment/save_deps');
+
 }
 
 return function(\Elgg\EventsService $events, \Elgg\HooksRegistrationService $hooks) {

engine/lib/views.php

@@ -1708,6 +1708,8 @@ function elgg_views_boot() {
 
 	elgg_register_js('elgg.friendspicker', elgg_get_simplecache_url('elgg/ui.friends_picker.js'));
 	elgg_register_js('elgg.avatar_cropper', elgg_get_simplecache_url('elgg/ui.avatar_cropper.js'));
+
+	// @deprecated 2.2
 	elgg_register_js('elgg.ui.river', elgg_get_simplecache_url('elgg/ui.river.js'));
 
 	elgg_register_js('jquery.imgareaselect', elgg_get_simplecache_url('jquery.imgareaselect.js'));

engine/views.php

@@ -30,6 +30,8 @@
 
 		"elgg/ui.avatar_cropper.js" => dirname(__DIR__) . "/js/lib/ui.avatar_cropper.js",
 		"elgg/ui.friends_picker.js" => dirname(__DIR__) . "/js/lib/ui.friends_picker.js",
+
+		// @deprecated 2.2
 		"elgg/ui.river.js" => dirname(__DIR__) . "/js/lib/ui.river.js",
 
 		// For datepicker. More info in the jquery-ui.js view

js/lib/ui.river.js

@@ -1,27 +1,17 @@
-elgg.provide('elgg.ui.river');
+/**
+ * This file is registered as a elgg/ui.river.js view in engine/views.php
+ * and loaded as elgg.ui.river js via simplecache URL.
+ * Since deprecation in 2.2, core does not use this file any more. Plugins may still
+ * be loading it from core/river/filter view via elgg_load_js("elgg.ui.river")
+ * @deprecated 2.2
+ */
+require(['elgg'], function (elgg) {
+	elgg.provide('elgg.ui.river');
 
-elgg.ui.river.init = function() {
-	$(document).on('change', '#elgg-river-selector', function() {
-		var url = window.location.href;
-		if (window.location.search.length) {
-			url = url.substring(0, url.indexOf('?'));
-		}
-		url += '?' + $(this).val();
-		elgg.forward(url);
-	});
+	elgg.ui.river.init = function () {
+		elgg.deprecated_notice('ui.river.js library has been deprecated. Update core/river/filter and forms/comment/save views to require component AMD modules instead.', '2.2')
+		require(['core/river/filter', 'forms/comment/save']);
+	};
 
-	$(document).on('elgg_ui_toggle', function (e, data) {
-		var $toggle = $(e.target);
-		var $elements = data.$toggled_elements;
-
-		if ($elements.is('.elgg-river-responses > .elgg-form-comment-save')) {
-			if ($toggle.hasClass('elgg-state-active')) {
-				$elements.find('.elgg-input-text').focus();
-			} else {
-				$toggle.blur();
-			}
-		}
-	});
-};
-
-elgg.register_hook_handler('init', 'system', elgg.ui.river.init);
+	elgg.register_hook_handler('init', 'system', elgg.ui.river.init);
+});

views/default/core/river/filter.js

@@ -0,0 +1,15 @@
+/**
+ * Initiates page reload when river selector value changes
+ * @module core/river/filter
+ */
+define(function (require) {
+	var $ = require('jquery');
+	$(document).on('change', '#elgg-river-selector', function () {
+		var url = window.location.href;
+		if (window.location.search.length) {
+			url = url.substring(0, url.indexOf('?'));
+		}
+		url += '?' + $(this).val();
+		window.location.href = url;
+	});
+});

views/default/core/river/filter.php

@@ -41,5 +41,3 @@
 
 $input = elgg_format_element('label', $attr, elgg_format_element('span', [], elgg_echo('filter')) . " $select");
 echo elgg_format_element('div', ['class' => 'clearfix'], $input);
-
-elgg_load_js('elgg.ui.river');

views/default/core/river/filter_deps.php

@@ -0,0 +1,6 @@
+<?php
+
+/**
+ * Extends core/river/filter view to load AMD modules in a BC way
+ */
+elgg_require_js('core/river/filter');

views/default/forms/comment/save.js

@@ -0,0 +1,19 @@
+/**
+ * Autofocuses first text input in a comment form when toggled
+ * @module forms/comment/save
+ */
+define(function (require) {
+	var $ = require('jquery');
+	$(document).on('elgg_ui_toggle', function (e, data) {
+		var $toggle = $(e.target);
+		var $elements = data.$toggled_elements;
+
+		if ($elements.is('.elgg-river-responses > .elgg-form-comment-save')) {
+			if ($toggle.hasClass('elgg-state-active')) {
+				$elements.find('.elgg-input-text').focus();
+			} else {
+				$toggle.blur();
+			}
+		}
+	});
+});

views/default/forms/comment/save_deps.php

@@ -0,0 +1,6 @@
+<?php
+
+/**
+ * Extends forms/comment/save view to load AMD modules in a BC way
+ */
+elgg_require_js('forms/comment/save');