feature(js): adds elgg/lightbox AMD module, loaded on all pages

`elgg/lightbox` AMD module can now be used to open and close the lightbox
programmatically. The module is inlined in `elgg.js` alongside the colorbox
library, and the CSS is included with `elgg.css` as well.

Hence it's no longer necessary to use `elgg_load_js('lightbox')` or
`elgg_load_css('lightbox')`.

Fixes Elgg#7895
Fixes Elgg#8309
Fixes Elgg#6991

docs/guides/javascript.rst

@@ -542,6 +542,66 @@ Plugins that load a widget layout via Ajax should initialize via this module:
        widgets.init();
    });
 
+Module ``elgg/lightbox``
+------------------------
+
+Elgg is distributed with the Colorbox jQuery library. Please go to http://www.jacklmoore.com/colorbox for more information on the options of this lightbox.
+
+Use the following classes to bind your anchor elements to a lightbox:
+
+ * ``elgg-lightbox`` - loads an HTML resource
+ * ``elgg-lightbox-photo`` - loads an image resource (should be used to avoid displaying raw image bytes instead of an ``img`` tag)
+ * ``elgg-lightbox-inline`` - displays an inline HTML element in a lightbox
+ * ``elgg-lightbox-iframe`` - loads a resource in an ``iframe``
+
+You may apply colorbox options to an individual ``elgg-lightbox`` element by setting the attribute ``data-colorbox-opts`` to a JSON settings object.
+
+.. code:: php
+
+   echo elgg_view('output/url', [
+      'text' => 'Open lightbox',
+      'href' => 'ajax/view/my_view',
+      'class' => 'elgg-lightbox',
+      'data-colorbox-opts' => json_encode([
+         'width' => '300px',
+      ])
+   ]);
+
+Use ``"getOptions", "ui.lightbox"`` plugin hook to filter options passed to ``$.colorbox()`` whenever a lightbox is opened. Note that the hook handler should depend on ``elgg/init`` AMD module.
+
+``elgg/lightbox`` AMD module should be used to open and close the lightbox programmatically:
+
+.. code:: js
+
+   define(function(require) {
+      var lightbox = require('elgg/lightbox');
+      var spinner = require('elgg/spinner');
+
+      lightbox.open({
+         html: '<p>Hello world!</p>',
+         onClosed: function() {
+            lightbox.open({
+               onLoad: spinner.start,
+               onComplete: spinner.stop,
+               photo: true,
+               href: 'https://elgg.org/cache/1457904417/default/community_theme/graphics/logo.png',
+            });
+         }
+      });
+   });
+
+To support gallery sets (via ``rel`` attribute), you need to bind colorbox directly to a specific selector (note that this will ignore ``data-colorbox-opts`` on all elements in a set):
+
+.. code:: js
+
+   require(['elgg/lightbox'], function(lightbox) {
+      var options = {
+         photo: true,
+         width: 500
+      };
+      lightbox.bind('a[rel="my-gallery"]', options, false); // 3rd attribute ensures binding is done without proxies
+   });
+
 Traditional scripts
 ===================
 
@@ -639,6 +699,9 @@ Available hooks
 **getOptions, ui.popup**
     This hook is fired for pop up displays (``"rel"="popup"``) and allows for customized placement options.
 
+**getOptions, ui.lightbox**
+    This hook can be used to filter options passed to ``$.colorbox()``
+
 **config, ckeditor**
     This filters the CKEditor config object. Register for this hook in a plugin boot module. The defaults can be seen in the module ``elgg/ckeditor/config``.
 

docs/guides/upgrading.rst

@@ -17,17 +17,25 @@ 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
  * ``elgg.ui.popupOpen()`` and ``elgg.ui.popupClose()`` methods in ``elgg.ui`` JS library: Use ``elgg/popup`` module instead.
+ * ``lightbox.js`` library: Do not use ``elgg_load_js('lightbox.js');`` unless your code references deprecated ``elgg.ui.lightbox`` namespace. Use ``elgg/lightbox`` AMD module instead.
+ * ``lightbox.css`` library: Lightbox CSS now extends ``elgg.css``. Calls to ``elgg_require_css('lightbox.css')`` have no effect.
 
 Deprecated Views
 ----------------
 
  * ``elgg/ui.river.js`` is deprecated: Do not rely on simplecache URLs to work.
+ * ``lightbox/settings.js`` is deprecated: Use ``getOptions, ui.lightbox`` JS plugin hook or ``data-colorbox-opts`` attribute.
 
 Added ``elgg/popup`` module
 -----------------------------
 
 New :doc:`elgg/popup module <javascript>` can be used to build out more complex trigger-popup interactions, including binding custom anchor types and opening/closing popups programmatically.
 
+Added ``elgg/lightbox`` module
+------------------------------
+
+New :doc:`elgg/lightbox module <javascript>` can be used to open and close the lightbox programmatically.
+
 From 2.0 to 2.1
 ===============
 

engine/lib/views.php

@@ -1688,9 +1688,10 @@ function elgg_views_boot() {
 
 	elgg_register_simplecache_view('elgg/init.js');
 
-	// optional stuff
+	elgg_extend_view('elgg.css', 'colorbox.css');
+
+	// provide warning to use elgg/lightbox AMD
 	elgg_register_js('lightbox', elgg_get_simplecache_url('lightbox.js'));
-	elgg_register_css('lightbox', elgg_get_simplecache_url('lightbox/elgg-colorbox-theme/colorbox.css'));
 
 	// just provides warning to use elgg/autocomplete AMD
 	elgg_register_js('elgg.autocomplete', elgg_normalize_url('js/lib/ui.autocomplete.js'));

engine/views.php

@@ -42,5 +42,8 @@
 		"jquery.jeditable.js" => dirname(__DIR__) . "/bower_components/jquery-jeditable/jquery.jeditable.js",
 		"jquery.ui.autocomplete.html.js" => dirname(__DIR__) . "/bower_components/jquery-ui-extensions/src/autocomplete/jquery.ui.autocomplete.html.js",
 		"sprintf.js" => dirname(__DIR__) . "/bower_components/sprintf/src/sprintf.js",
+
+		'colorbox.css' => dirname(__DIR__) . "/views/default/lightbox/elgg-colorbox-theme/colorbox.css",
+		'colorbox-images/' => dirname(__DIR__) . "/views/default/lightbox/elgg-colorbox-theme/colorbox-images/",
 	],
 ];

js/lib/elgglib.js

@@ -403,7 +403,7 @@ elgg.register_error = function(errors, delay) {
 /**
  * Logs a notice about use of a deprecated function or capability
  * @param {String} msg         The deprecation message to display
- * @param {Number} dep_version The version the function was deprecated for
+ * @param {String} dep_version The version the function was deprecated for
  * @since 1.9
  */
 elgg.deprecated_notice = function(msg, dep_version) {

mod/developers/start.php

@@ -68,8 +68,6 @@ function developers_process_settings() {
 
 	if (!empty($settings['show_gear']) && elgg_is_admin_logged_in() && !elgg_in_context('admin')) {
 		elgg_require_js('elgg/dev/gear');
-		elgg_load_js('lightbox');
-		elgg_load_css('lightbox');
 		elgg_register_ajax_view('developers/gear_popup');
 		elgg_register_simplecache_view('elgg/dev/gear.html');
 

mod/developers/views/default/elgg/dev/gear.js

@@ -6,6 +6,7 @@ define(function (require) {
 	var elgg = require('elgg');
 	var spinner = require('elgg/spinner');
 	var gear_html = require('text!elgg/dev/gear.html');
+	require('elgg/lightbox');
 
 	$(gear_html)
 		.appendTo('body')

mod/developers/views/default/theme_sandbox/javascript/lightbox.js

@@ -0,0 +1,8 @@
+define(function(require) {
+	var lightbox = require('elgg/lightbox');
+	var opts = {
+		photo: true,
+		width: 600
+	};
+	lightbox.bind('[rel="lightbox-gallery"]', opts, false);
+});

mod/developers/views/default/theme_sandbox/javascript/lightbox.php

@@ -1,12 +1,72 @@
 <?php
 
-elgg_load_js('lightbox');
-elgg_load_css('lightbox');
-
-$link = elgg_view('output/url', array(
+echo elgg_view('output/url', array(
 	'text' => 'Open lighbox',
 	'href' => "ajax/view/developers/ajax",
 	'class' => 'elgg-lightbox'
 ));
 
-echo $link;
+echo elgg_view('output/url', array(
+	'text' => 'Open iframe lightbox',
+	'href' => 'https://elgg.org',
+	'class' => 'elgg-lightbox-iframe mll',
+	'data-colorbox-opts' => json_encode([
+		'width' => '80%',
+		'height' => '80%',
+	]),
+));
+
+echo elgg_view('output/url', array(
+	'text' => 'Open inline HTML lightbox',
+	'href' => '#lightbox-inline',
+	'class' => 'elgg-lightbox-inline mll',
+));
+?>
+<div class="hidden">
+	<div id="lightbox-inline">
+		<?= elgg_view('developers/ipsum') ?>
+	</div>
+</div>
+<?php
+$files = elgg_get_entities_from_metadata(array(
+	'types' => 'object',
+	'subtypes' => 'file',
+	'metadata_name_value_paris' => [
+		'name' => 'simpletype',
+		'value' => 'image',
+	],
+		));
+
+if (!$files) {
+	return;
+}
+
+elgg_require_js('theme_sandbox/javascript/lightbox');
+
+echo elgg_view('output/url', array(
+	'text' => 'Open photo lightbox',
+	'href' => elgg_get_download_url($files[0]),
+	'class' => 'elgg-lightbox-photo mll',
+));
+?>
+<ul class="elgg-gallery elgg-gallery-fluid">
+	<?php
+	foreach ($files as $file) {
+		?>
+		<li class="pam">
+			<?php
+			echo elgg_view('output/url', array(
+				'text' => elgg_view('output/img', array(
+					'src' => $file->getIconURL('small'),
+					'alt' => $file->getDisplayName(),
+				)),
+				'href' => $file->getIconURL('large'),
+				'rel' => 'lightbox-gallery',
+			));
+			?>
+		</li>
+		<?php
+	}
+	?>
+</ul>
+

mod/embed/start.php

@@ -49,8 +49,6 @@ function embed_longtext_menu($hook, $type, $items, $vars) {
 		$url = 'embed?container_guid=' . $page_owner->getGUID();
 	}
 
-	elgg_load_js('lightbox');
-	elgg_load_css('lightbox');
 	elgg_require_js('jquery.form');
 	elgg_load_js('elgg.embed');
 

mod/embed/views/default/embed/embed.js.php

@@ -91,7 +91,9 @@
 		textArea.val(result);
 	}
 
-	elgg.ui.lightbox.close();
+	require(['elgg/lightbox'], function(lightbox) {
+		lightbox.close();
+	});
 
 	event.preventDefault();
 };

mod/file/views/default/file/specialcontent/image/default.php

@@ -12,8 +12,6 @@
 $download_url = elgg_get_download_url($file);
 
 if ($vars['full_view']) {
-	elgg_load_js('lightbox');
-	elgg_load_css('lightbox');
 	echo <<<HTML
 		<div class="file-photo">
 			<a href="$download_url" class="elgg-lightbox-photo"><img class="elgg-photo" src="$image_url" /></a>

mod/likes/views/default/likes/count.php

@@ -8,9 +8,6 @@
 $num_of_likes = \Elgg\Likes\DataService::instance()->getNumLikes($vars['entity']);
 $guid = $vars['entity']->guid;
 
-elgg_load_js('lightbox');
-elgg_load_css('lightbox');
-
 // display the number of likes
 if ($num_of_likes == 1) {
 	$likes_string = elgg_echo('likes:userlikedthis', array($num_of_likes));

mod/reportedcontent/views/default/elgg/reportedcontent.js

@@ -16,15 +16,19 @@ define(function (require) {
 			data: $form.serialize(),
 			success: function (data) {
 				if (data.status == 0) {
-					elgg.ui.lightbox.close();
+					require(['elgg/lightbox'], function(lightbox) {
+						lightbox.close();
+					});
 				}
 			}
 		});
 	});
 
 	$(document).on('click', '.elgg-form-reportedcontent-add .elgg-button-cancel', function (e) {
 		if ($(this).is('#colorbox *')) {
-			elgg.ui.lightbox.close();
+			require(['elgg/lightbox'], function(lightbox) {
+				lightbox.close();
+			});
 		} else {
 			if (history.length > 1) {
 				history.go(-1);

views/default/admin/plugins.php

@@ -8,9 +8,6 @@
  * @subpackage Admin.Plugins
  */
 
-elgg_load_js('lightbox');
-elgg_load_css('lightbox');
-
 // @todo this should occur in the controller code
 _elgg_generate_plugin_entities();
 

views/default/elgg.js.php

@@ -2,8 +2,6 @@
 /**
  * Core Elgg JavaScript file
  */
-
-use Elgg\Filesystem\Directory;
 
 global $CONFIG;
 
@@ -25,9 +23,10 @@
 // @todo: remove in 3.x and use async calls
 echo elgg_view('elgg/widgets.js');
 
-// We use a named AMD module and inine it here in order to save HTTP requests, 
-// as this module will be required on each page
+// We use named AMD modules and inine them here in order to save HTTP requests,
+// as these modules will be required on each page
 echo elgg_view('elgg/popup.js');
+echo elgg_view('elgg/lightbox.js');
 
 $elggDir = \Elgg\Application::elggDir();
 $files = array(
@@ -110,4 +109,21 @@
 
 elgg.trigger_hook('boot', 'system');
 
-require(['elgg/init', 'elgg/ready']);
+require(['elgg/init', 'elgg/ready']);
+
+<?php
+if (_elgg_view_may_be_altered('lightbox/settings.js', 'lightbox/settings.js.php')) {
+	elgg_deprecated_notice('lightbox/settings.js view has been deprecated. Use "getOptions", "ui.lightbox" ' .
+		'JS plugin hook or data-colorbox-opts attribute instead', '2.2');
+	?>
+	require(['elgg'], function(elgg) {
+		elgg.provide('elgg.ui.lightbox');
+		<?= elgg_view('lightbox/settings.js') ?>
+	});
+	<?php
+}
+?>
+
+// we inline this in 2.x because both elgg/lightbox and the legacy lightbox.js library use it
+// and legacy code assumes that lightbox.js loads the library synchronously.
+<?= elgg_view('jquery.colorbox.js'); ?>