Updated documentation for embed. Fixed bug passing internal_name for elggEmbedInsertContent(). Showing a message if no embedable items are returned.

git-svn-id: http://code.elgg.org/elgg/trunk@6644 36083f99-b078-4883-b0ff-0f9b5a30f544

5 files changed, 232 insertions, 50 deletions

diff --git a/mod/embed/README.txt b/mod/embed/README.txt
index 9cc21d949..1ed21262c 100644
--- a/mod/embed/README.txt
+++ b/mod/embed/README.txt
@@ -1,23 +1,197 @@
-Embed plugin
-(c) 2009 Curverider Ltd
-Released under the GNU Public License version 2
-http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+Embed plugin - Point-and-click embedding using ECML.
 
-The embed plugin requires Elgg 1.5 (or prior to the Elgg 1.5
-release, Elgg revision 2634 or above) and the file plugin.
+CONTENTS:
+	1. Overview
+	2. Extending Embed
+		1. Registering and Populating Embed Sections
+		2. Registering Upload Sections
+		3. Advanced Layouts
+		4. Javascript
+	3. Other Editors and Embed
 
-To insert into the active editor, use elggEmbedInsert(html, textAreaName).
+	
+1. Overview
+	The Embed plugin is a simple way to allow users to link to or embed
+	their personal network content or third party resources in any text area.
+	
+	Embed includes support for the default input/longtext view, but is easily
+	extendable to include support for rich text editors like TinyMCE or CK 
+	Editor.
+
+
+2. Extending Embed
+	The Embed plugin can be extended by other plugins using a combination
+	of plugin hooks and specific views.
+	
+	Plugins can register a new content section or a new upload section.
+	
+	Plugins can also provide special views for their embed section, if
+	they require something the default view doesn't provide.
+
+
+2.1  Registering and Populating Embed Sections
+	Plugins providing embed content should reply to two hooks: embed_get_sections:all
+	and embed_get_items:$section_name.
+	
+	Embed emits the 'embed_get_sections' hook to populate the tabs of the modal display.
+	Plugins supporting embed should reply by pushing an array element to the passed
+	$value.
+	
+	Register plugins hooks like this:
+	
+		register_plugin_hook('embed_get_sections', 'all', 'my_plugin_embed_get_sections');
+		
+		function my_plugin_embed_get_sections($hook, $type, $value, $params) {
+			$value['videolist'] = array(
+				'name' => elgg_echo('my_plugin'),
+				'layout' => 'list',
+				'icon_size' => 'medium',
+			);
+		
+			return $value;
+		}
+	
+	The index of the returned array is the id used for the Embed section.
+	
+	Options available in the array value are:
+		name => The friendly name to display in the tab
+		layout => The layout style to use.  Layouts are found in the 
+				embed/layouts/$layout and embed/item/$layout views.  
+				Default supported layouts are list and gallery.
+		icon_size => The icon size to use for in the item list.
+		
+		
+	Embed emits the 'embed_get_items' hook to populate the embed section.  Plugins
+	supporting embed should reply by returning an array of ElggEntities, which will
+	be formatted by Embed.  If you need specific formatting for items, see section 2.3.
+	
+		register_plugin_hook('embed_get_items', 'videolist', 'videolist_embed_get_items');
+		
+		function my_plugin_embed_get_items($hook, $type, $value, $params) {
+			$options = array(
+				'owner_guid' => get_loggedin_userid(),
+				'type_subtype_pair' => array('object' => 'my_plugin_type'),
+				'count' => TRUE
+			);
+		
+			if ($count = elgg_get_entities($options)) {
+				$value['count'] += $count;
+			
+				unset($options['count']);
+				$options['offset'] = $params['offset'];
+				$options['limit'] = $params['limit'];
+			
+				$items = elgg_get_entities($options);
+			
+				$value['items'] = array_merge($items, $value['items']);
+			}
+		
+			return $value;
+		}
+		
+		Values passed in $params are:
+			offset - Offset for entity list.
+			limit - Limit for entity list.
+			section - The current active section.
+			upload_sections - Valid upload sections.
+			
+		The function should return $value as:
+			items - An array of ElggEntities
+			count - The count of all available entities to embed
+			
+		In case other plugins want to mangle the value, be sure to
+		check for existing values before appending.
 
-The default behavior searches for all textareas with name textAreaName and 
-inserts the content into them.
 
-If you need to use special embed code to insert content into a custom textarea
-(like tinyMce, FCK, etc), extend (nb: EXTEND, not override) the embed/custom_insert_js
-view with your custom JS.  The vars available to you are:
-	str content The content to insert.
-	str textAreaName The name of the textarea to receive the content.
+2.2 Registering Upload Sections
+	Embed includes a special tab, Upload, that allows users to immediatley
+	upload a new item.  Like the embed sections, plugins can extend this
+	to add their own upload form.
+	
+	Embed emits the embed_get_upload_sections:all hook to populate the
+	dropdown in the upload tab.  Plugins should respond to this hook
+	by returning an array with details about the upload section:  
+	
+		register_plugin_hook('embed_get_upload_sections', 'all', 'my_plugin_embed_get_upload_sections');
+		
+		function my_plugin_embed_get_upload_sections($hook, $type, $value, $params) {
+			$value['my_plugin'] = array(
+				'name' => elgg_echo('my_plugin'),
+				'view' => 'my_plugin/forms/embed_upload'
+			);
+	
+			return $value;
+		}
+		
+	The array index is the ID of the upload section, and the values are:
+		name - The friendly name of the upload section
+		view - The view to use for the upload section's content
+	
+	The upload form view should use AJAX to upload a file and return
+	the user to the correct section or automatically insert the new upload
+	into the text area.  See Tidypics as an example. 
+	
+	
+2.3 Advanced Layouts
+	By default, Embed will automatically format items returned by 
+	embed_get_items hooks.  If you need special formatting you can
+	override both the content and layout views.
+	
+	Embed looks for a section-specific views before defaulting to built
+	in formatting:
+		embed/$section/content - The content of the embed section
+								including all headers and navigation elements.
+		embed/$section/item/$layout - The content of the embed section
+								for the specific layout.  Inserted
+								between navigation elements.
+								
+	Embed also supports adhoc layouts that can be shared among different plugins.
+	To use a specific layout, register the embed section with your own layout
+	and create the appropriate layout view:
+	
+		function my_plugin_embed_get_sections($hook, $type, $value, $params) {
+			$value['videolist'] = array(
+				'name' => elgg_echo('my_plugin'),
+				'layout' => 'shared_embed_layout',
+				'icon_size' => 'medium',
+			);
+		
+			return $value;
+		}
+		
+		Create the views 'embed/layouts/shared_embed_layout' and 
+		'embed/items/shared_embed_layout.'  See the default list and 
+		gallery layouts as examples.
+		
+		
+2.4 Javascript
+	If you use a custom layout you need to provide a way to insert
+	the user's selection into the current editor.  Usually this will be
+	an onClick event via Javascript.  Embed provides a helper function for
+	this:
+	
+	elggEmbedInsertContent(content, textAreaName)
+	
+	Content is the pre-formatted content to insert into the text area,
+	and textAreaName is the name of the text area.  This name is
+	sent via GET as 'internal_name.'
+	
+	
+3. Other Editors and Embed
+	Embed ships with support for the default input/longtext textarea.
+	Plugins replacing this view are expected to include Javascript to
+	allow embed to work with the new editors.
+	
+	The elggEmbedInsertContent() JS function can be extened for custom
+	text editors by extending the embed/custom_insert_js view.  Plugins 
+	should extend this view with javascript code that inserts
+	content into the specific text area.  Variables available within
+	this view are:
+		str content The content to insert.
+		str textAreaName The name of the textarea to receive the content.
 	
-It is important to correctly extend this view for compatibility across 
-multiple plugins and textarea states.  Your custom JS should run without
-error no matter plugin order or rich text editor status.  See TinyMCE as
-an example of how to losely extend this function.
\ No newline at end of file
+	Note: Extend this view; don't override it.  It is important to correctly
+	extend this view for compatibility across multiple plugins and textarea 
+	states.  Your custom JS should run without error no matter plugin order 
+	or rich text editor status.  See TinyMCE as an example of how to losely 
+	extend this function.
\ No newline at end of file
diff --git a/mod/embed/languages/en.php b/mod/embed/languages/en.php
index 738c37a28..f7c95334a 100644
--- a/mod/embed/languages/en.php
+++ b/mod/embed/languages/en.php
@@ -12,6 +12,7 @@ $english = array(
 
 	// messages
 	'embed:no_upload_content' => 'No upload content!',
+	'embed:no_section_content' => 'No items found.',
 );
 
 add_translation("en", $english);
\ No newline at end of file
diff --git a/mod/embed/start.php b/mod/embed/start.php
index 29dc78530..99d620746 100644
--- a/mod/embed/start.php
+++ b/mod/embed/start.php
@@ -53,7 +53,7 @@ function embed_page_handler($page) {
 			asort($sections, SORT_LOCALE_STRING);
 			asort($upload_sections, SORT_LOCALE_STRING);
 			$active_section = get_input('active_section', NULL);
-			$internal_name = get_input('internalname', NULL);
+			$internal_name = get_input('internal_name', NULL);
 
 			echo elgg_view('embed/embed', array(
 				'sections' => $sections,
diff --git a/mod/embed/views/default/embed/embed.php b/mod/embed/views/default/embed/embed.php
index 250a7a465..b57c3b289 100644
--- a/mod/embed/views/default/embed/embed.php
+++ b/mod/embed/views/default/embed/embed.php
@@ -12,7 +12,7 @@
 $sections = elgg_get_array_value('sections', $vars, array());
 $active_section = elgg_get_array_value('active_section', $vars, array_shift(array_keys($sections)));
 $upload_sections = elgg_get_array_value('upload_sections', $vars, array());
-$internal_name = elgg_get_array_value('internal_name', $vars, array());
+$internal_name = elgg_get_array_value('internal_name', $vars);
 
 if (!$sections) {
 	$content = elgg_echo('embed:no_sections');
@@ -80,34 +80,38 @@ if (!$sections) {
 			if (!elgg_view_exists($view)) {
 				$view = "embed/item/$layout";
 			}
-
-			// pull out some common tests
-			// embed requires ECML, but until we have plugin deps working
-			// we need to explicitly check and use a fallback.
-			if ($ecml_enabled = is_plugin_enabled('ecml')){
-				$ecml_valid_keyword = ecml_is_valid_keyword($active_section);
+			
+			if (!isset($embed_info['items']) || !is_array($embed_info['items']) || !count($embed_info['items'])) {
+				$content .= elgg_echo('embed:no_section_content');
 			} else {
-				$ecml_valid_keyword = FALSE;
-			}
-
-			$items_content = '';
-			foreach ($embed_info['items'] as $item) {
-				$item_params = array(
-					'section' => $active_section,
-					'item' => $item,
-					'ecml_enabled' => $ecml_enabled,
-					'ecml_keyword' => ($ecml_valid_keyword) ? $active_section : 'entity',
-					'icon_size' => elgg_get_array_value('icon_size', $section_info, 'tiny'),
-				);
-
-				$items_content .= elgg_view($view, $item_params);
+				// pull out some common tests
+				// embed requires ECML, but until we have plugin deps working
+				// we need to explicitly check and use a fallback.
+				if ($ecml_enabled = is_plugin_enabled('ecml')){
+					$ecml_valid_keyword = ecml_is_valid_keyword($active_section);
+				} else {
+					$ecml_valid_keyword = FALSE;
+				}
+	
+				$items_content = '';
+				foreach ($embed_info['items'] as $item) {
+					$item_params = array(
+						'section' => $active_section,
+						'item' => $item,
+						'ecml_enabled' => $ecml_enabled,
+						'ecml_keyword' => ($ecml_valid_keyword) ? $active_section : 'entity',
+						'icon_size' => elgg_get_array_value('icon_size', $section_info, 'tiny'),
+					);
+	
+					$items_content .= elgg_view($view, $item_params);
+				}
+	
+				$params['content'] = $items_content;
+				$params['count'] = $embed_info['count'];
+	
+				$content .= elgg_view('navigation/pagination', $params);
+				$content .= elgg_view("embed/layouts/$layout", $params);
 			}
-
-			$params['content'] = $items_content;
-			$params['count'] = $embed_info['count'];
-
-			$content .= elgg_view('navigation/pagination', $params);
-			$content .= elgg_view("embed/layouts/$layout", $params);
 		} else {
 			$content .= elgg_echo('embed:no_section_content');
 		}
@@ -115,21 +119,24 @@ if (!$sections) {
 		$content .= elgg_echo('embed:invalid_section');
 	}
 }
+
 echo $content;
 ?>
 
 <script type="text/javascript">
 $(document).ready(function() {
+	var internal_name = '<?php echo addslashes($internal_name); ?>';
+	
 	// insert embed codes
 	$('.embed_data').click(function() {
-		var embed_code = $(this).data('embed_code');
-		elggEmbedInsertContent(embed_code, '<?php echo addslashes($internal_name); ?>');
+		var embed_code = $(this).data('embed_code')
+		elggEmbedInsertContent(embed_code, internal_name);
 	});
 
 	// tabs
 	$('.embed_section').click(function() {
 		var section = $(this).attr('id');
-		var url = '<?php echo $vars['url']; ?>pg/embed/embed?active_section=' + section;
+		var url = '<?php echo $vars['url']; ?>pg/embed/embed?active_section=' + section + '&internal_name=' + internal_name;
 		$('#facebox .body .content').load(url);
 
 		return false;
diff --git a/mod/embed/views/default/embed/link.php b/mod/embed/views/default/embed/link.php
index 8776893ec..6740b8e1a 100644
--- a/mod/embed/views/default/embed/link.php
+++ b/mod/embed/views/default/embed/link.php
@@ -3,4 +3,4 @@
  * Displays an "Embed media" link in longtext inputs.
  */
 ?>
-<a class="longtext_control small link" href="<?php echo $vars['url'] . 'pg/embed'; ?>?internalname=<?php echo $vars['internalname']; ?>" rel="facebox"><?php echo elgg_echo('media:insert'); ?></a>
+<a class="longtext_control small link" href="<?php echo $vars['url'] . 'pg/embed'; ?>?internal_name=<?php echo $vars['internalname']; ?>" rel="facebox"><?php echo elgg_echo('media:insert'); ?></a>