aboutsummaryrefslogtreecommitdiff
path: root/mod/embed
diff options
context:
space:
mode:
authorcash <cash.costello@gmail.com>2011-10-01 17:38:47 -0400
committercash <cash.costello@gmail.com>2011-10-01 17:38:47 -0400
commitd7549a210074a29f004642d713ede6ce04703bcc (patch)
tree8efeba98e1f675a62cf70be2539807c73763db6c /mod/embed
parentbc292c96ac6b118bd7a99509fce1c11bb232aeb2 (diff)
downloadelgg-d7549a210074a29f004642d713ede6ce04703bcc.tar.gz
elgg-d7549a210074a29f004642d713ede6ce04703bcc.tar.bz2
Updated the instructions
Diffstat (limited to 'mod/embed')
-rw-r--r--mod/embed/README.txt236
-rw-r--r--mod/embed/views/default/js/embed/embed.php25
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();
}