diff options
| -rw-r--r-- | mod/embed/README.txt | 236 | ||||
| -rw-r--r-- | mod/embed/views/default/js/embed/embed.php | 25 |
2 files changed, 66 insertions, 195 deletions
diff --git a/mod/embed/README.txt b/mod/embed/README.txt index 33c9fff65..c7ce2e528 100644 --- a/mod/embed/README.txt +++ b/mod/embed/README.txt @@ -1,198 +1,74 @@ -Embed plugin - Point-and-click embedding using ECML. +Embed 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 + 2. Adding a Tab + 3. Populating a Select Tab + 4. Populating an Upload Tab + 5. Other WYSIWYG Editors and Embed 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. + The Embed plugin adds a menu item to the longtext menu. Clicking on this + link pops up a lightbox. The lightbox has two types of tabs: one for + selecting content to embed and one for uploading new content. -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. Adding a Tab + The Embed plugin uses the menu system to manage its tabs. Use + elgg_register_menu_item() for the embed menu to add a new tab like this: + $item = ElggMenuItem::factory(array( + 'name' => 'file', + 'text' => elgg_echo('file'), + 'section' => 'select', + 'data' => array( + 'options' => array( + 'type' => 'object', + 'subtype' => 'file', + ), + ), + )); + elgg_register_menu_item('embed', $item); -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. - internal_name - Internal name of the input field - - 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. + Parameters: + name: The unique name of the tab. + text: The text shown on the tab + section: 'select' for embed selection or 'upload' for uploading new content + data: an array of parameters for creating the tab and its content. See + the two sections below for data key values for the two tab types. + Select tab data parameters: + options: array of options passed to elgg_list_entities() -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, textAreaId) - - Content is the pre-formatted content to insert into the text area, - and textAreaId is the name of the text area. This name is - sent via GET as 'internal_name.' - + Upload tab data parameters: + view: the view used to render the tab content + + See the file plugin for examples of registering both tab types. + + +3. Populating a Select Tab + Nothing should be required other than setting the options parameter array + when registering the tab. See the view embed/item to see how an entity is + rendered. + +4. Populating an Upload Tab + The view that is registered must be defined. It must include a form for + uploading the content. The form must be wrapped in a div with the class + .embed-upload. Somewhere in the view must be a hidden input field with the + name embed_hidden with its value be the name of the tab to forward the user + to when uploading is complete. + + See the view embed/file_upload/content for an example -3. Other Editors and Embed +5. Other WYSIWYG Editors and Embed Embed ships with support for the default input/longtext textarea. - Plugins replacing this view are expected to include Javascript to + 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 textAreaId The name of the textarea to receive the content. - - 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 + To add custom JavaScript into the Embed plugin's elgg.embed.insert() function, + override the view embed/custom_insert_js. The textarea jQuery object is + available as the variable textArea and the content to be inserted is the + variable content. See the TinyMCE plugin for an example of this view.
\ No newline at end of file diff --git a/mod/embed/views/default/js/embed/embed.php b/mod/embed/views/default/js/embed/embed.php index 6d4e2e4ea..840d8f89c 100644 --- a/mod/embed/views/default/js/embed/embed.php +++ b/mod/embed/views/default/js/embed/embed.php @@ -14,9 +14,9 @@ elgg.embed.init = function() { }); // special pagination helper for lightbox - $('.embed-wrapper .elgg-pagination a').live('click', elgg.embed.loadContent); + $('.embed-wrapper .elgg-pagination a').live('click', elgg.embed.forward); - $('.embed-section').live('click', elgg.embed.loadContent); + $('.embed-section').live('click', elgg.embed.forward); $('.embed-upload .elgg-form').live('submit', elgg.embed.submit); } @@ -31,25 +31,20 @@ elgg.embed.init = function() { */ elgg.embed.insert = function(event) { var textAreaId = elgg.embed.textAreaId; + var textArea = $('#' + textAreaId); // generalize this based on a css class attached to what should be inserted var content = ' ' + $(this).find(".elgg-image").html() + ' '; + textArea.val(textArea.val() + content); + textArea.focus(); + <?php -// If a wysiwyg editor has been registered, it handles the insertion by -// overriding the embed/custom_insert_js view. See the TinyMCE plugin for an -// example of this. -$custom_insert_code = elgg_view('embed/custom_insert_js'); -if ($custom_insert_code) { - echo $custom_insert_code; -} else { -?> - $('#' + textAreaId).val($('#' + textAreaId).val() + content); - $('#' + textAreaId).focus(); -<?php -} +// See the TinyMCE plugin for an example of this view + echo elgg_view('embed/custom_insert_js'); ?> + $.fancybox.close(); event.preventDefault(); @@ -98,7 +93,7 @@ elgg.embed.submit = function(event) { * @param {Object} event * @return void */ -elgg.embed.loadContent = function(event) { +elgg.embed.forward = function(event) { $('.embed-wrapper').parent().load($(this).attr('href')); event.preventDefault(); } |