aboutsummaryrefslogtreecommitdiff
path: root/mod/embed/README.txt
diff options
context:
space:
mode:
Diffstat (limited to 'mod/embed/README.txt')
-rw-r--r--mod/embed/README.txt238
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