From 086831a67c650c6773b96f286255611bebb3fd22 Mon Sep 17 00:00:00 2001 From: Penelope Leach Date: Mon, 16 Nov 2009 12:57:15 +0000 Subject: [PATCH] NOBUG - Added a bunch more phpdocs to the portfolio code --- lang/en_utf8/portfolio.php | 1 + lib/portfolio/caller.php | 28 ++++++++++++++++++++++++++++ lib/portfolio/exporter.php | 1 + lib/portfolio/formats.php | 34 +++++++++++++++++++++++++++++----- lib/portfolio/plugin.php | 15 +++++++++++++-- 5 files changed, 72 insertions(+), 7 deletions(-) diff --git a/lang/en_utf8/portfolio.php b/lang/en_utf8/portfolio.php index f957c94d8e..58f63de096 100644 --- a/lang/en_utf8/portfolio.php +++ b/lang/en_utf8/portfolio.php @@ -8,6 +8,7 @@ $string['addalltoportfolio'] = 'Save all...'; $string['activeexport'] = 'Resolve active export'; $string['alreadyexporting'] = 'You already have an active portfolio export in this session. Before continuing, you must either complete this export, or cancel it. Would you like to continue it? (No will cancel it)'; $string['availableformats'] = 'Available export formats'; +$string['callbackclassinvalid'] = 'Callback class specified was invalid or not part of the portfolio_caller hierarchy'; $string['callercouldnotpackage'] = 'Failed to package up your data for export: original error was $a'; $string['cannotsetvisible'] = 'Cannot set this to visible - the plugin has been completely disabled because of a misconfiguration'; $string['configexport'] = 'Configure exported data'; diff --git a/lib/portfolio/caller.php b/lib/portfolio/caller.php index fb9be145d5..0c852eceb1 100644 --- a/lib/portfolio/caller.php +++ b/lib/portfolio/caller.php @@ -355,6 +355,23 @@ abstract class portfolio_caller_base { public abstract function load_data(); + /** + * set up the required files for this export. + * this supports either passing files directly + * or passing area arguments directly through + * to the files api using file_storage::get_area_files + * + * @param mixed $ids one of: + * - single file id + * - single stored_file ojbect + * - array of file ids or stored_file objects + * - null + * @param int $contextid (optional), passed to {@link see file_storage::get_area_files} + * @param string $filearea (optional), passed to {@link see file_storage::get_area_files} + * @param int $itemid (optional), passed to {@link see file_storage::get_area_files} + * @param string $sort (optional), passed to {@link see file_storage::get_area_files} + * @param bool $includedirs (optional), passed to {@link see file_storage::get_area_files} + */ public function set_file_and_format_data($ids=null /* ..pass arguments to area files here. */) { $args = func_get_args(); array_shift($args); // shift off $ids @@ -393,6 +410,17 @@ abstract class portfolio_caller_base { } } + /** + * array of arguments the caller expects to be passed through to it + * this must be keyed on the argument name, and the array value is a boolean, + * whether it is requrired, or just optional + * eg array( + * id => true, + * somethingelse => false, + * ) + * + * @return array + */ public static abstract function expected_callbackargs(); } diff --git a/lib/portfolio/exporter.php b/lib/portfolio/exporter.php index da50f0ff26..c79c247227 100644 --- a/lib/portfolio/exporter.php +++ b/lib/portfolio/exporter.php @@ -719,6 +719,7 @@ class portfolio_exporter { * * @param string $content content to write * @param string $name filename to use + * @param bool $maifest whether this is the main file or an secondary file (eg attachment) * @return new stored_file object */ public function write_new_file($content, $name, $manifest=true) { diff --git a/lib/portfolio/formats.php b/lib/portfolio/formats.php index 88d14d152c..3ba6c7d8ff 100644 --- a/lib/portfolio/formats.php +++ b/lib/portfolio/formats.php @@ -32,14 +32,28 @@ * the most basic type - pretty much everything is a subtype */ class portfolio_format_file { + + /** + * array of mimetypes this format supports + */ public static function mimetypes() { return array(null); } + /** + * for multipart formats, eg html with attachments, + * we need to have a directory to place associated files in + * inside the zip file. this is the name of that directory + */ public static function get_file_directory() { return null; } + /** + * given a file, return a snippet of markup in whatever format + * to link to that file. + * usually involves the path given by {@link get_file_directory} + */ public static function file_output($file) { return ''; } @@ -49,6 +63,9 @@ class portfolio_format_file { * image format, subtype of file. */ class portfolio_format_image extends portfolio_format_file { + /** + * return all mimetypes that use image.gif (eg all images) + */ public static function mimetypes() { return mimeinfo_from_icon('type', 'image.gif', true); } @@ -68,15 +85,14 @@ class portfolio_format_plainhtml extends portfolio_format_file { /** * video format, subtype of file. * -* I guess there could be a youtube/google video plugin -* and anyway, the flickr plugin can support it already +* for portfolio plugins that support videos specifically */ class portfolio_format_video extends portfolio_format_file { public static function mimetypes() { return array_merge( - mimeinfo_from_icon('type', 'video.gif', true), - mimeinfo_from_icon('type', 'avi.gif', true) - ); + mimeinfo_from_icon('type', 'video.gif', true), + mimeinfo_from_icon('type', 'avi.gif', true) + ); } } @@ -90,12 +106,20 @@ class portfolio_format_text extends portfolio_format_file { } } +/** + * base class for rich formats. + * these are multipart - eg things with attachments + */ class portfolio_format_rich { public static function mimetypes() { return array(null); } } +/** + * most commonly used rich format - richhtml - html with attachments + * eg inline images + */ class portfolio_format_richhtml extends portfolio_format_rich { public static function get_file_directory() { return 'site_files'; diff --git a/lib/portfolio/plugin.php b/lib/portfolio/plugin.php index 56055d2e09..44c1cb5085 100644 --- a/lib/portfolio/plugin.php +++ b/lib/portfolio/plugin.php @@ -145,6 +145,12 @@ abstract class portfolio_plugin_base { */ public abstract function is_push(); + /** + * returns the user-friendly name for this plugin + * usually just get_string('pluginname', 'portfolio_something') + * + * @return string + */ public static abstract function get_name(); /** @@ -152,7 +158,7 @@ abstract class portfolio_plugin_base { * if this function returns something non empty, ALL instances of your plugin * will be set to invisble and not be able to be set back until it's fixed * - * @return mixed - string = error string KEY (must be inside plugin_$yourplugin) or 0/false if you're ok + * @return mixed - string = error string KEY (must be inside portfolio_$yourplugin) or 0/false if you're ok */ public static function plugin_sanity_check() { return 0; @@ -163,7 +169,7 @@ abstract class portfolio_plugin_base { * if this function returns something non empty, the instance will be * set to invislbe and not be able to be set back until it's fixed. * - * @return mixed - string = error string KEY (must be inside plugin_$yourplugin) or 0/false if you're ok + * @return mixed - string = error string KEY (must be inside portfolio_$yourplugin) or 0/false if you're ok */ public function instance_sanity_check() { return 0; @@ -702,6 +708,11 @@ abstract class portfolio_plugin_base { return true; } + /** + * return array of mnet methods, keyed by service (pf) + * in the same format used everywhere else in moodle. + * see the mahara portfolio plugin for an example + */ public static function mnet_publishes() { return array(); } -- 2.39.5