diff options
Diffstat (limited to 'mod/embed/README.txt')
| -rw-r--r-- | mod/embed/README.txt | 238 |
1 files changed, 58 insertions, 180 deletions
diff --git a/mod/embed/README.txt b/mod/embed/README.txt index 33c9fff65..51b120d96 100644 --- a/mod/embed/README.txt +++ b/mod/embed/README.txt @@ -1,198 +1,76 @@ -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 supports lists of content for insertion + and 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: -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. + $item = ElggMenuItem::factory(array( + 'name' => 'file', + 'text' => elgg_echo('file'), + 'priority' => 10, + 'data' => array( + 'options' => array( + 'type' => 'object', + 'subtype' => 'file', + ), + ), + )); + elgg_register_menu_item('embed', $item); + Parameters: + name: The unique name of the tab. + text: The text shown on the tab + priority: Placement of the tab. + data: An array of parameters for creating the tab and its content. + When listing content using the embed list view, pass the options for the + elgg_list_entities() function as 'options'. + When using a custom view for listing content or for uploading new + content, pass the view name as 'view'. + + See the file plugin for examples of registering both tab types. + + +3. Populating a Content 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. + + If creating a custom list, the <li> elements must have a class of .embed-item. + The HTML content that is inserted must use the class .embed-insert. + + +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 .elgg-form-embed. 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 -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.' - -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 |