-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
projects / lorea / elgg.git / commitdiff