diff options
| -rw-r--r-- | mod/embed/README.txt | 210 | ||||
| -rw-r--r-- | mod/embed/languages/en.php | 1 | ||||
| -rw-r--r-- | mod/embed/start.php | 2 | ||||
| -rw-r--r-- | mod/embed/views/default/embed/embed.php | 67 | ||||
| -rw-r--r-- | mod/embed/views/default/embed/link.php | 2 |
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> |