-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
$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');
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');
}
$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;
projects / lorea / elgg.git / commitdiff