From d7549a210074a29f004642d713ede6ce04703bcc Mon Sep 17 00:00:00 2001 From: cash Date: Sat, 1 Oct 2011 17:38:47 -0400 Subject: Updated the instructions --- mod/embed/README.txt | 236 ++++++++++++--------------------------------------- 1 file changed, 56 insertions(+), 180 deletions(-) (limited to 'mod/embed/README.txt') 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 -- cgit v1.2.3 From fa04d6615760a014f7557f2d28ff864eebce8551 Mon Sep 17 00:00:00 2001 From: cash Date: Mon, 3 Oct 2011 21:30:30 -0400 Subject: removed the sections from the menu to provide more flexibility in tab ordering --- mod/embed/README.txt | 36 ++++++++++++---------- mod/embed/views/default/embed/css.php | 2 +- mod/embed/views/default/embed/layout.php | 25 +++++++-------- mod/embed/views/default/js/embed/embed.php | 2 +- mod/embed/views/default/navigation/menu/embed.php | 19 +++++------- mod/file/start.php | 6 ++-- .../views/default/embed/file_upload/content.php | 8 ++--- 7 files changed, 44 insertions(+), 54 deletions(-) (limited to 'mod/embed/README.txt') diff --git a/mod/embed/README.txt b/mod/embed/README.txt index c7ce2e528..cecee08c0 100644 --- a/mod/embed/README.txt +++ b/mod/embed/README.txt @@ -13,8 +13,9 @@ CONTENTS: their personal network content or third party resources in any text area. 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. + link pops up a lightbox. The lightbox supports lists of content for insertion + and uploading new content. + 2. Adding a Tab The Embed plugin uses the menu system to manage its tabs. Use @@ -23,7 +24,7 @@ CONTENTS: $item = ElggMenuItem::factory(array( 'name' => 'file', 'text' => elgg_echo('file'), - 'section' => 'select', + 'priority' => 10, 'data' => array( 'options' => array( 'type' => 'object', @@ -36,32 +37,33 @@ CONTENTS: 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() - - Upload tab data parameters: - view: the view used to render the tab content + 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 Select Tab +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
  • elements must have a class of .embed-item. + The HTML content that is inserted must use the class .elgg-image. + + 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. + 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 + 5. Other WYSIWYG Editors and Embed Embed ships with support for the default input/longtext textarea. diff --git a/mod/embed/views/default/embed/css.php b/mod/embed/views/default/embed/css.php index 324ed1038..034c0fcfe 100644 --- a/mod/embed/views/default/embed/css.php +++ b/mod/embed/views/default/embed/css.php @@ -8,7 +8,7 @@ .embed-wrapper { width: 730px; min-height: 400px; - margin: 15px; + margin: 20px 15px; } .embed-wrapper h2 { color: #333333; diff --git a/mod/embed/views/default/embed/layout.php b/mod/embed/views/default/embed/layout.php index 73c26810d..c1e43f13c 100644 --- a/mod/embed/views/default/embed/layout.php +++ b/mod/embed/views/default/embed/layout.php @@ -8,20 +8,17 @@ $title = elgg_view_title(elgg_echo('embed:media')); $menu = elgg_view_menu('embed'); $selected = elgg_get_config('embed_tab'); -switch ($selected->getData('tab_type')) { - case 'select': - $tab = elgg_list_entities( - embed_get_list_options($selected->getData('options')), - 'elgg_get_entities', - 'embed_list_items' - ); - if (!$tab) { - $tab = elgg_echo('embed:no_section_content'); - } - break; - case 'upload': - $tab = elgg_view($selected->getData('view'), $vars); - break; +if ($selected->getData('view')) { + $tab = elgg_view($selected->getData('view'), $vars); +} else { + $tab = elgg_list_entities( + embed_get_list_options($selected->getData('options')), + 'elgg_get_entities', + 'embed_list_items' + ); + if (!$tab) { + $tab = elgg_echo('embed:no_section_content'); + } } echo << $menu_item->getText(), - 'url' => 'embed/tab/' . $menu_item->getName(), - 'url_class' => 'embed-section', - 'selected' => $menu_item->getSelected(), - ); - } +foreach ($vars['menu']['default'] as $menu_item) { + $tabs[] = array( + 'title' => $menu_item->getText(), + 'url' => 'embed/tab/' . $menu_item->getName(), + 'url_class' => 'embed-section', + 'selected' => $menu_item->getSelected(), + ); } echo elgg_view('navigation/tabs', array('tabs' => $tabs)); diff --git a/mod/file/start.php b/mod/file/start.php index 16ce0e233..843ae0794 100644 --- a/mod/file/start.php +++ b/mod/file/start.php @@ -61,9 +61,8 @@ function file_init() { $item = ElggMenuItem::factory(array( 'name' => 'file', 'text' => elgg_echo('file'), - 'section' => 'select', + 'priority' => 10, 'data' => array( - 'tab_type' => 'select', 'options' => array( 'type' => 'object', 'subtype' => 'file', @@ -75,9 +74,8 @@ function file_init() { $item = ElggMenuItem::factory(array( 'name' => 'file_upload', 'text' => elgg_echo('file:upload'), - 'section' => 'upload', + 'priority' => 100, 'data' => array( - 'tab_type' => 'upload', 'view' => 'embed/file_upload/content', ), )); diff --git a/mod/file/views/default/embed/file_upload/content.php b/mod/file/views/default/embed/file_upload/content.php index a530b3194..4d3db0d97 100644 --- a/mod/file/views/default/embed/file_upload/content.php +++ b/mod/file/views/default/embed/file_upload/content.php @@ -5,13 +5,9 @@ $form_vars = array( 'enctype' => 'multipart/form-data', - 'class' => 'elgg-form', + 'class' => 'elgg-form-embed', ); -$upload_content = elgg_view_form('file/upload', $form_vars); - -echo "
    "; -echo $upload_content; -echo "
    "; +echo elgg_view_form('file/upload', $form_vars); // the tab we want to be forwarded to after upload is complete echo elgg_view('input/hidden', array( -- cgit v1.2.3 From 9d5c00c78c0666a31485d870a1e657d4557b23c4 Mon Sep 17 00:00:00 2001 From: cash Date: Mon, 3 Oct 2011 21:56:14 -0400 Subject: using better insert class --- mod/embed/README.txt | 2 +- mod/embed/views/default/embed/item.php | 2 +- mod/embed/views/default/js/embed/embed.php | 2 +- mod/file/views/default/icon/object/file.php | 15 ++++++++++----- views/default/icon/default.php | 5 ++++- 5 files changed, 17 insertions(+), 9 deletions(-) (limited to 'mod/embed/README.txt') diff --git a/mod/embed/README.txt b/mod/embed/README.txt index cecee08c0..51b120d96 100644 --- a/mod/embed/README.txt +++ b/mod/embed/README.txt @@ -53,7 +53,7 @@ CONTENTS: rendered. If creating a custom list, the
  • elements must have a class of .embed-item. - The HTML content that is inserted must use the class .elgg-image. + The HTML content that is inserted must use the class .embed-insert. 4. Populating an Upload Tab diff --git a/mod/embed/views/default/embed/item.php b/mod/embed/views/default/embed/item.php index 4087b7408..3060de879 100644 --- a/mod/embed/views/default/embed/item.php +++ b/mod/embed/views/default/embed/item.php @@ -34,6 +34,6 @@ $params = array( ); $body = elgg_view('object/elements/summary', $params); -$image = elgg_view_entity_icon($entity, 'small'); +$image = elgg_view_entity_icon($entity, 'small', array('link_class' => 'embed-insert')); echo elgg_view_image_block($image, $body); diff --git a/mod/embed/views/default/js/embed/embed.php b/mod/embed/views/default/js/embed/embed.php index bb80919a9..3126e12f7 100644 --- a/mod/embed/views/default/js/embed/embed.php +++ b/mod/embed/views/default/js/embed/embed.php @@ -34,7 +34,7 @@ elgg.embed.insert = function(event) { var textArea = $('#' + textAreaId); // generalize this based on a css class attached to what should be inserted - var content = ' ' + $(this).find(".elgg-image").html() + ' '; + var content = ' ' + $(this).find(".embed-insert").parent().html() + ' '; textArea.val(textArea.val() + content); textArea.focus(); diff --git a/mod/file/views/default/icon/object/file.php b/mod/file/views/default/icon/object/file.php index 6357d418f..7feba7af3 100644 --- a/mod/file/views/default/icon/object/file.php +++ b/mod/file/views/default/icon/object/file.php @@ -2,9 +2,10 @@ /** * File icon view * - * @uses $vars['entity'] The entity the icon represents - uses getIconURL() method - * @uses $vars['size'] topbar, tiny, small, medium (default), large, master - * @uses $vars['href'] Optional override for link + * @uses $vars['entity'] The entity the icon represents - uses getIconURL() method + * @uses $vars['size'] topbar, tiny, small, medium (default), large, master + * @uses $vars['href'] Optional override for link + * @uses $vars['link_class'] Optional CSS class added to img */ $entity = $vars['entity']; @@ -32,10 +33,14 @@ $img_src = elgg_format_url($img_src); $img = "\"$title\""; if ($url) { - echo elgg_view('output/url', array( + $params = array( 'href' => $url, 'text' => $img, - )); + ); + if (isset($vars['link_class'])) { + $params['class'] = $vars['link_class']; + } + echo elgg_view('output/url', $params); } else { echo $img; } diff --git a/views/default/icon/default.php b/views/default/icon/default.php index c5749ba04..3abd96b96 100644 --- a/views/default/icon/default.php +++ b/views/default/icon/default.php @@ -8,6 +8,7 @@ * @uses $vars['entity'] The entity the icon represents - uses getIconURL() method * @uses $vars['size'] topbar, tiny, small, medium (default), large, master * @uses $vars['href'] Optional override for link + * @uses $vars['img_class'] Optional CSS class added to img */ $entity = $vars['entity']; @@ -18,6 +19,8 @@ if (!in_array($vars['size'], $sizes)) { $vars['size'] = "medium"; } +$class = elgg_extract('img_class', $vars, ''); + if (isset($entity->name)) { $title = $entity->name; } else { @@ -30,7 +33,7 @@ if (isset($vars['href'])) { } $img_src = $entity->getIconURL($vars['size']); -$img = "\"$title\""; +$img = "\"$title\""; if ($url) { echo elgg_view('output/url', array( -- cgit v1.2.3