diff --git a/lib/portfolio/caller.php b/lib/portfolio/caller.php index 7990978833e..240aeb976d3 100644 --- a/lib/portfolio/caller.php +++ b/lib/portfolio/caller.php @@ -1,86 +1,74 @@ . + /** - * Moodle - Modular Object-Oriented Dynamic Learning Environment - * http://moodle.org - * Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com + * This file contains the base classes that are extended to create portfolio export functionality. * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 2 of the License, or - * (at your option) any later version. + * For places in moodle that want to + * add export functionality to subclass from {@link http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page} * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program. If not, see . - * - * @package core - * @subpackage portfolio - * @author Penny Leach - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL - * @copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * - * This file contains the base classes for places in moodle that want to - * add export functionality to subclass from. - * See http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page + * @package core_portfolio + * @copyright 2008 Penny Leach , Martin Dougiamas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ defined('MOODLE_INTERNAL') || die(); /** -* base class for callers -* -* See http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page -* {@see also portfolio_module_caller_base} -*/ + * Base class for callers + * + * {@link See http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page} + * {@see also portfolio_module_caller_base} + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ abstract class portfolio_caller_base { - /** - * stdclass object - * course that was active during the caller - */ + /** @var stdClass course active during the call */ protected $course; - /** - * named array of export config - * use{@link set_export_config} and {@link get_export_config} to access - */ + /** @var array configuration used for export. Use {@see set_export_config} and {@see get_export_config} to access */ protected $exportconfig = array(); - /** - * stdclass object - * user currently exporting content - */ + /** @var stdclass user currently exporting content */ protected $user; - /** - * a reference to the exporter object - */ + /** @var stdClass a reference to the exporter object */ protected $exporter; - /** - * this can be overridden in subclasses constructors if they want - */ + /** @var array can be optionally overridden by subclass constructors */ protected $supportedformats; - /** - * set this for single file exports - */ + /** @var stored_file single file exports configuration*/ protected $singlefile; - /** - * set this for multi file exports - */ + /** @var stored_file|object set this for multi file exports */ protected $multifiles; - /** - * set this for generated-file exports - */ + /** @var string set this for generated-file exports */ protected $intendedmimetype; + /** + * Create portfolio_caller object + * + * @param array $callbackargs argument properties + */ public function __construct($callbackargs) { $expected = call_user_func(array(get_class($this), 'expected_callbackargs')); foreach ($expected as $key => $required) { @@ -96,51 +84,49 @@ abstract class portfolio_caller_base { } /** - * if this caller wants any additional config items - * they should be defined here. - * - * @param array $mform moodleform object (passed by reference) to add elements to - * @param object $instance subclass of portfolio_plugin_base - * @param integer $userid id of user exporting content - */ + * If this caller wants any additional config items, + * they should be defined here. + * + * @param moodleform $mform passed by reference, add elements to it. + * @param portfolio_plugin_base $instance subclass of portfolio_plugin_base + */ public function export_config_form(&$mform, $instance) {} /** - * whether this caller wants any additional - * config during export (eg options or metadata) - * - * @return boolean - */ + * Whether this caller wants any additional + * config during export (eg options or metadata) + * + * @return bool + */ public function has_export_config() { return false; } /** - * just like the moodle form validation function - * this is passed in the data array from the form - * and if a non empty array is returned, form processing will stop. - * - * @param array $data data from form. - * @return array keyvalue pairs - form element => error string - */ + * Just like the moodle form validation function, + * this is passed in the data array from the form + * and if a non empty array is returned, form processing will stop. + * + * @param array $data data from form. + */ public function export_config_validation($data) {} /** - * how long does this reasonably expect to take.. - * should we offer the user the option to wait.. - * this is deliberately nonstatic so it can take filesize into account - * the portfolio plugin can override this. - * (so for example even if a huge file is being sent, - * the download portfolio plugin doesn't care ) - * - * @return string (see PORTFOLIO_TIME_* constants) - */ + * How long does this reasonably expect to take.. + * Should we offer the user the option to wait..? + * This is deliberately nonstatic so it can take filesize into account + * the portfolio plugin can override this. + * (so for example even if a huge file is being sent, + * the download portfolio plugin doesn't care ) + */ public abstract function expected_time(); /** - * helper method to calculate expected time for multi or single file exports - */ + * Helper method to calculate expected time for multi or single file exports + * + * @return string file time expectation + */ public function expected_time_file() { if ($this->multifiles) { return portfolio_expected_time_file($this->multifiles); @@ -152,25 +138,20 @@ abstract class portfolio_caller_base { } /** - * used for displaying the navigation during the export screens. - * - * this function must be implemented, but can really return anything. - * an Exporting.. string will be added on the end. - * @return array of $extranav and $cm - * - * to pass to build_navigation - * - */ + * Function to build navigation + */ public abstract function get_navigation(); /** - * - */ + * Helper function to get sha1 + */ public abstract function get_sha1(); /** - * helper function to calculate the sha1 for multi or single file exports - */ + * Helper function to calculate the sha1 for multi or single file exports + * + * @return string sha1 file exports + */ public function get_sha1_file() { if (empty($this->singlefile) && empty($this->multifiles)) { throw new portfolio_caller_exception('invalidsha1file', 'portfolio', $this->get_return_url()); @@ -186,11 +167,15 @@ abstract class portfolio_caller_base { return sha1(implode('', $sha1s)); } - /* - * generic getter for properties belonging to this instance - * outside the subclasses - * like name, visible etc. - */ + /** + * Generic getter for properties belonging to this instance + * outside the subclasses + * like name, visible etc. + * + * @param string $field property's name + * @return mixed + * @throws portfolio_export_exception + */ public function get($field) { if (property_exists($this, $field)) { return $this->{$field}; @@ -200,11 +185,15 @@ abstract class portfolio_caller_base { } /** - * generic setter for properties belonging to this instance - * outside the subclass - * like name, visible, etc. - * - */ + * Generic setter for properties belonging to this instance + * outside the subclass + * like name, visible, etc. + * + * @param string $field property's name + * @param mixed $value property's value + * @return bool + * @throws moodle_exception + */ public final function set($field, &$value) { if (property_exists($this, $field)) { $this->{$field} =& $value; @@ -216,12 +205,12 @@ abstract class portfolio_caller_base { } /** - * stores the config generated at export time. - * subclasses can retrieve values using - * {@link get_export_config} - * - * @param array $config formdata - */ + * Stores the config generated at export time. + * Subclasses can retrieve values using + * {@see get_export_config} + * + * @param array $config formdata + */ public final function set_export_config($config) { $allowed = array_merge( array('wait', 'hidewait', 'format', 'hideformat'), @@ -237,11 +226,12 @@ abstract class portfolio_caller_base { } /** - * returns a particular export config value. - * subclasses shouldn't need to override this - * - * @param string key the config item to fetch - */ + * Returns a particular export config value. + * Subclasses shouldn't need to override this + * + * @param string $key the config item to fetch + * @return null|mixed of export configuration + */ public final function get_export_config($key) { $allowed = array_merge( array('wait', 'hidewait', 'format', 'hideformat'), @@ -258,47 +248,47 @@ abstract class portfolio_caller_base { } /** - * Similar to the other allowed_config functions - * if you need export config, you must provide - * a list of what the fields are. - * - * even if you want to store stuff during export - * without displaying a form to the user, - * you can use this. - * - * @return array array of allowed keys - */ + * Similar to the other allowed_config functions + * if you need export config, you must provide + * a list of what the fields are. + * Even if you want to store stuff during export + * without displaying a form to the user, + * you can use this. + * + * @return array array of allowed keys + */ public function get_allowed_export_config() { return array(); } /** - * after the user submits their config - * they're given a confirm screen - * summarising what they've chosen. - * - * this function should return a table of nice strings => values - * of what they've chosen - * to be displayed in a table. - * - * @return array array of config items. - */ + * After the user submits their config, + * they're given a confirm screen + * summarising what they've chosen. + * This function should return a table of nice strings => values + * of what they've chosen + * to be displayed in a table. + * + * @return bool + */ public function get_export_summary() { return false; } /** - * called before the portfolio plugin gets control - * this function should copy all the files it wants to - * the temporary directory, using {@see copy_existing_file} - * or {@see write_new_file} - */ + * Called before the portfolio plugin gets control. + * This function should copy all the files it wants to + * the temporary directory, using {@see copy_existing_file} + * or {@see write_new_file} + */ public abstract function prepare_package(); /** - * helper function to copy files into the temp area - * for single or multi file exports. - */ + * Helper function to copy files into the temp area + * for single or multi file exports. + * + * @return stored_file|bool + */ public function prepare_package_file() { if (empty($this->singlefile) && empty($this->multifiles)) { throw new portfolio_caller_exception('invalidpreparepackagefile', 'portfolio', $this->get_return_url()); @@ -312,15 +302,10 @@ abstract class portfolio_caller_base { } /** - * array of formats this caller supports - * the intersection of what this function returns - * and what the selected portfolio plugin supports - * will be used - * use the constants PORTFOLIO_FORMAT_* - * - * @return array list of formats - * - */ + * Array of formats this caller supports. + * + * @return array list of formats + */ public final function supported_formats() { $basic = $this->base_supported_formats(); if (empty($this->supportedformats)) { @@ -334,45 +319,51 @@ abstract class portfolio_caller_base { return portfolio_most_specific_formats($specific, $basic); } + /** + * Base supported formats + * + * @throws coding_exception + */ public static function base_supported_formats() { throw new coding_exception('base_supported_formats() method needs to be overridden in each subclass of portfolio_caller_base'); } /** - * this is the "return to where you were" url - * - * @return string url - */ + * This is the "return to where you were" url + */ public abstract function get_return_url(); /** - * callback to do whatever capability checks required - * in the caller (called during the export process - */ + * Callback to do whatever capability checks required + * in the caller (called during the export process + */ public abstract function check_permissions(); /** - * nice name to display to the user about this caller location - */ + * Clean name to display to the user about this caller location + */ public static function display_name() { throw new coding_exception('display_name() method needs to be overridden in each subclass of portfolio_caller_base'); } /** - * return a string to put at the header summarising this export - * by default, just the display name (usually just 'assignment' or something unhelpful - * - * @return string - */ + * Return a string to put at the header summarising this export. + * By default, it just display the name (usually just 'assignment' or something unhelpful + * + * @return string + */ public function heading_summary() { return get_string('exportingcontentfrom', 'portfolio', $this->display_name()); } + /** + * Load data + */ public abstract function load_data(); /** - * set up the required files for this export. - * this supports either passing files directly + * 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 * @@ -381,12 +372,7 @@ abstract class portfolio_caller_base { * - single stored_file object * - array of file ids or stored_file objects * - null - * @param int $contextid (optional), passed to {@link see file_storage::get_area_files} - * @param string $component (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} + * @return void */ public function set_file_and_format_data($ids=null /* ..pass arguments to area files here. */) { $args = func_get_args(); @@ -426,10 +412,12 @@ abstract class portfolio_caller_base { } /** - * the button-location always knows best + * The button-location always knows best * what the formats are... so it should be trusted. * + * @todo MDL-31298 - re-analyze set_formats_from_button comment * @param array $formats array of PORTFOLIO_FORMAT_XX + * @return void */ public function set_formats_from_button($formats) { $base = $this->base_supported_formats(); @@ -445,12 +433,11 @@ abstract class portfolio_caller_base { } /** - * adds a new format to the list of supported formats. - * handles removing conflicting and less specific + * Adds a new format to the list of supported formats. + * This functions also handles removing conflicting and less specific * formats at the same time. * * @param string $format one of PORTFOLIO_FORMAT_XX - * * @return void */ protected function add_format($format) { @@ -460,6 +447,11 @@ abstract class portfolio_caller_base { $this->supportedformats = portfolio_most_specific_formats(array($format), $this->supportedformats); } + /** + * Gets mimetype + * + * @return string + */ public function get_mimetype() { if ($this->singlefile instanceof stored_file) { return $this->singlefile->get_mimetype(); @@ -469,15 +461,13 @@ 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, + * 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 required, or just optional * eg array( * id => true, - * somethingelse => false, + * somethingelse => false * ) - * - * @return array */ public static function expected_callbackargs() { throw new coding_exception('expected_callbackargs() method needs to be overridden in each subclass of portfolio_caller_base'); @@ -485,66 +475,68 @@ abstract class portfolio_caller_base { /** - * return the context for this export. used for $PAGE->set_context + * Return the context for this export. used for $PAGE->set_context * - * @return stdclass + * @param moodle_page $PAGE global page object */ public abstract function set_context($PAGE); } /** -* base class for module callers -* this just implements a few of the abstract functions -* from portfolio_caller_base so that caller authors -* don't need to. -* -* See http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page -* {@see also portfolio_caller_base} -*/ + * Base class for module callers. + * This just implements a few of the abstract functions + * from portfolio_caller_base so that caller authors + * don't need to. + * {@link http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page} + * {@see also portfolio_caller_base} + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ abstract class portfolio_module_caller_base extends portfolio_caller_base { - /** - * coursemodule object - * set this in the constructor like - * $this->cm = get_coursemodule_from_instance('forum', $this->forum->id); - */ + /** @var object coursemodule object. set this in the constructor like $this->cm = get_coursemodule_from_instance('forum', $this->forum->id); */ protected $cm; - /** - * - * int cmid - */ + /** @var int cmid */ protected $id; - /** - * stdclass course object - */ + /** @var stdclass course object */ protected $course; /** - * navigation passed to print_header - * override this to do something more specific than the module view page - */ + * Navigation passed to print_header. + * Override this to do something more specific than the module view page + * + * @return array + */ public function get_navigation() { $extranav = array('name' => $this->cm->name, 'link' => $this->get_return_url()); return array($extranav, $this->cm); } /** - * the url to return to after export or on cancel - * defaults to the module 'view' page - * override this if it's deeper inside the module - */ + * The url to return to after export or on cancel. + * Defaults value is set to the module 'view' page. + * Override this if it's deeper inside the module. + * + * @return string + */ public function get_return_url() { global $CFG; return $CFG->wwwroot . '/mod/' . $this->cm->modname . '/view.php?id=' . $this->cm->id; } /** - * override the parent get function - * to make sure when we're asked for a course - * we retrieve the object from the database as needed - */ + * Override the parent get function + * to make sure when we're asked for a course, + * We retrieve the object from the database as needed. + * + * @param string $key the name of get function + * @return stdClass + */ public function get($key) { if ($key != 'course') { return parent::get($key); @@ -557,16 +549,20 @@ abstract class portfolio_module_caller_base extends portfolio_caller_base { } /** - * return a string to put at the header summarising this export - * by default, just the display name and the module instance name - * override this to do something more specific - */ + * Return a string to put at the header summarising this export. + * by default, this function just display the name and module instance name. + * Override this to do something more specific + * + * @return string + */ public function heading_summary() { return get_string('exportingcontentfrom', 'portfolio', $this->display_name() . ': ' . $this->cm->name); } /** - * overridden to return the course module context + * Overridden to return the course module context + * + * @param moodle_page $PAGE global PAGE */ public function set_context($PAGE) { $PAGE->set_cm($this->cm); diff --git a/lib/portfolio/constants.php b/lib/portfolio/constants.php index f7565b5d9fb..04e59656c53 100644 --- a/lib/portfolio/constants.php +++ b/lib/portfolio/constants.php @@ -1,222 +1,202 @@ . + /** - * Moodle - Modular Object-Oriented Dynamic Learning Environment - * http://moodle.org - * Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program. If not, see . - * - * @package core - * @subpackage portfolio - * @author Penny Leach - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL - * @copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * * This file contains all the defined constants to do with portfolios. + * + * @package core_portfolio + * @copyright 2008 Penny Leach , Martin Dougiamas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ defined('MOODLE_INTERNAL') || die(); -// ************************************************** // -// EXPORT STAGE CONSTANTS -// ************************************************** // +//EXPORT STAGE CONSTANTS + /** -* display a form to the user -* this one might not be used if neither -* the plugin, or the caller has any config. -*/ + * PORTFOLIO_STAGE_CONFIG - display a form to the user this one might not be + * used if neither the plugin, or the caller has any config. + */ define('PORTFOLIO_STAGE_CONFIG', 1); /** -* summarise the form and ask for confirmation -* if we skipped PORTFOLIO_STAGE_CONFIG, -* just confirm the send. -*/ + * PORTFOLIO_STAGE_CONFIRM - summarise the form and ask for confirmation + * if we skipped PORTFOLIO_STAGE_CONFIG, + * just confirm the send. + */ define('PORTFOLIO_STAGE_CONFIRM', 2); /** -* either queue the event and skip to PORTFOLIO_STAGE_FINISHED -* or continue to PORTFOLIO_STAGE_PACKAGE -*/ - + * PORTFOLIO_STAGE_QUEUEORWAIT - either queue the event and skip to PORTFOLIO_STAGE_FINISHED + */ define('PORTFOLIO_STAGE_QUEUEORWAIT', 3); /** -* package up the various bits -* during this stage both the caller -* and the plugin get their package methods called -*/ + * PORTFOLIO_STAGE_PACKAGE - package up the various bits during this stage both the caller + * and the plugin get their package methods called + */ define('PORTFOLIO_STAGE_PACKAGE', 4); -/* -* the portfolio plugin must send the file -*/ +/** + * PORTFOLIO_STAGE_SEND - the portfolio plugin must send the file + */ define('PORTFOLIO_STAGE_SEND', 5); /** -* cleanup the temporary area -*/ + * PORTFOLIO_STAGE_CLEANUP - cleanup the temporary area + */ define('PORTFOLIO_STAGE_CLEANUP', 6); /** -* display the "finished notification" -*/ + * PORTFOLIO_STAGE_FINISHED - display the "finished notification" + */ define('PORTFOLIO_STAGE_FINISHED', 7); -// ************************************************** // + // EXPORT FORMAT CONSTANTS -// these should always correspond to a string -// in the portfolio module, called format_{$value} -// ************************************************** // +// These should always correspond to a string in the portfolio module, called format_{$value} /** -* file - the most basic fallback format. -* this should always be supported -* in remote system.s -*/ + * PORTFOLIO_FORMAT_FILE - the most basic fallback format. this should always be supported + * in remote system.s + */ define('PORTFOLIO_FORMAT_FILE', 'file'); /** -* moodle backup - the plugin needs to be able to write a complete backup -* the caller need to be able to export the particular XML bits to insert -* into moodle.xml (?and the file bits if necessary) -*/ + * PORTFOLIO_FORMAT_MBKP - the plugin needs to be able to write a complete backup + * the caller need to be able to export the particular XML bits to insert + * into moodle.xml (?and the file bits if necessary) + */ define('PORTFOLIO_FORMAT_MBKP', 'mbkp'); /** -* richhtml - like html but with attachments. -*/ + * PORTFOLIO_FORMAT_RICHHTML - like html but with attachments. + */ define('PORTFOLIO_FORMAT_RICHHTML', 'richhtml'); - /** -* plainhtml - a single html representation - no attachments -*/ + * PORTFOLIO_FORMAT_PLAINHTML - a single html representation - no attachments + */ define('PORTFOLIO_FORMAT_PLAINHTML', 'plainhtml'); /** -* image - subtype of file -*/ + * PORTFOLIO_FORMAT_IMAGE - subtype of file + */ define('PORTFOLIO_FORMAT_IMAGE', 'image'); /** -* video - subtype of file -*/ + * PORTFOLIO_FORMAT_VIDEO - subtype of file + */ define('PORTFOLIO_FORMAT_VIDEO', 'video'); /** -* text - subtype of file -*/ + * PORTFOLIO_FORMAT_TEXT - subtype of file + */ define('PORTFOLIO_FORMAT_TEXT', 'text'); /** -* pdf - subtype of file -*/ + * PORTFOLIO_FORMAT_PDF - subtype of file + */ define('PORTFOLIO_FORMAT_PDF', 'pdf'); /** -* document - subtype of file -*/ + * PORTFOLIO_FORMAT_DOCUMENT - subtype of file + */ define('PORTFOLIO_FORMAT_DOCUMENT', 'document'); /** -* document - subtype of file -*/ + * PORTFOLIO_FORMAT_SPREADSHEET - subtype of file + */ define('PORTFOLIO_FORMAT_SPREADSHEET', 'spreadsheet'); /** -* document - subtype of file -*/ + * PORTFOLIO_FORMAT_PRESENTATION - subtype of file + */ define('PORTFOLIO_FORMAT_PRESENTATION', 'presentation'); /** - * abstract - just used to say, "we support all these" + * PORTFOLIO_FORMAT_RICH - just used to say, "we support all these" */ define('PORTFOLIO_FORMAT_RICH', 'rich'); /** - * leap2a http://wiki.cetis.ac.uk/LEAP_2.0 - * supported by mahara and and others + * PORTFOLIO_FORMAT_LEAP2A - supported by mahara and and others {http://wiki.cetis.ac.uk/LEAP_2.0} */ define('PORTFOLIO_FORMAT_LEAP2A', 'leap2a'); -// ************************************************** // -// EXPORT TIME LEVELS -// these should correspond to a string -// in the portfolio module, called time_{$value} -// ************************************************** // - +// EXPORT TIME LEVELS +// These should correspond to a string in the portfolio module, called time_{$value} /** -* no delay. don't even offer the user the option -* of not waiting for the transfer -*/ + * PORTFOLIO_TIME_LOW - no delay. don't even offer the user the option + * of not waiting for the transfer + */ define('PORTFOLIO_TIME_LOW', 'low'); /** -* a small delay. user can still easily opt to -* watch this transfer and wait. -*/ + * PORTFOLIO_TIME_MODERATE - a small delay. user can still easily opt to + * watch this transfer and wait. + */ define('PORTFOLIO_TIME_MODERATE', 'moderate'); /** -* slow. the user really should not be given the option -* to choose this. -*/ + * PORTFOLIO_TIME_HIGH - slow. the user really should not be given the option + * to choose this. + */ define('PORTFOLIO_TIME_HIGH', 'high'); /** -* very slow, or immediate transfers not supported -*/ + * PORTFOLIO_TIME_FORCEQUEUE - very slow, or immediate transfers not supported + */ define('PORTFOLIO_TIME_FORCEQUEUE', 'queue'); -// ************************************************** // -// BUTTON FORMATS -// available ways to add the portfolio export to a page -// ************************************************** // + // BUTTON FORMATS + // Available ways to add the portfolio export to a page /** -* a whole form, containing a drop down menu (where necessary) -* and a submit button -*/ + * PORTFOLIO_ADD_FULL_FORM - a whole form, containing a drop down menu (where necessary) + * and a submit button + */ define('PORTFOLIO_ADD_FULL_FORM', 1); /** -* a whole form, containing a drop down menu (where necessary) -* but has an icon instead of a button to submit -*/ + * PORTFOLIO_ADD_ICON_FORM - a whole form, containing a drop down menu (where necessary) + * but has an icon instead of a button to submit + */ define('PORTFOLIO_ADD_ICON_FORM', 2); /** -* just an icon with a link around it (yuk, as will result in a long url -* only use where necessary) -*/ + * PORTFOLIO_ADD_ICON_LINK - just an icon with a link around it (yuk, as will result in a long url + * only use where necessary) + */ define('PORTFOLIO_ADD_ICON_LINK', 3); /** -* just some text with a link around it (yuk, as will result in a long url -* only use where necessary) -*/ + * PORTFOLIO_ADD_TEXT_LINK - just some text with a link around it (yuk, as will result in a long url + * only use where necessary) + */ define('PORTFOLIO_ADD_TEXT_LINK', 4); /** - * hacky way to turn the button class into a url to redirect to - * this replaces the old portfolio_fake_add_url function + * PORTFOLIO_ADD_FAKE_URL - hacky way to turn the button class into a url to redirect to + * this replaces the old portfolio_fake_add_url function */ define('PORTFOLIO_ADD_FAKE_URL', 5); diff --git a/lib/portfolio/exceptions.php b/lib/portfolio/exceptions.php index d39e6d570d5..e6fbac68e8f 100644 --- a/lib/portfolio/exceptions.php +++ b/lib/portfolio/exceptions.php @@ -1,52 +1,59 @@ . + /** - * Moodle - Modular Object-Oriented Dynamic Learning Environment - * http://moodle.org - * Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program. If not, see . - * - * @package core - * @subpackage portfolio - * @author Penny Leach - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL - * @copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * * This file contains all the portfolio exception classes. + * + * @package core_portfolio + * @copyright 2008 Penny Leach , Martin Dougiamas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ defined('MOODLE_INTERNAL') || die(); /** -* top level portfolio exception. -* sometimes caught and rethrown as {@see portfolio_export_exception} -*/ + * Top level portfolio exception. + * Sometimes caught and re-thrown as {@see portfolio_export_exception} + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class portfolio_exception extends moodle_exception {} /** -* exception to throw during an export - will clean up session and tempdata -*/ + * Exception to throw during an export - will clean up session and tempdata + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class portfolio_export_exception extends portfolio_exception { /** - * constructor. - * @param object $exporter instance of portfolio_exporter (will handle null case) - * @param string $errorcode language string key - * @param string $module language string module (optional, defaults to moodle) - * @param string $continue url to continue to (optional, defaults to wwwroot) - * @param mixed $a language string data (optional, defaults to null) - */ + * Constructor. + * + * @param portfolio_exporter $exporter instance of portfolio_exporter (will handle null case) + * @param string $errorcode language string key + * @param string $module language string module (optional, defaults to moodle) + * @param string $continue url to continue to (optional, defaults to wwwroot) + * @param object $a language string data (optional, defaults to null) + */ public function __construct($exporter, $errorcode, $module=null, $continue=null, $a=null) { global $CFG; // This static variable is necessary because sometimes the code below @@ -82,23 +89,43 @@ class portfolio_export_exception extends portfolio_exception { } /** -* exception for callers to throw when they have a problem. -* usually caught and rethrown as {@see portfolio_export_exception} -*/ + * Exception for callers to throw when they have a problem. + * Usually caught and rethrown as {@see portfolio_export_exception} + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class portfolio_caller_exception extends portfolio_exception {} /** -* exception for portfolio plugins to throw when they have a problem. -* usually caught and rethrown as {@see portfolio_export_exception} -*/ + * Exception for portfolio plugins to throw when they have a problem. + * Usually caught and rethrown as {@see portfolio_export_exception} + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class portfolio_plugin_exception extends portfolio_exception {} /** -* exception for interacting with the button class -*/ + * Exception for interacting with the button class + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class portfolio_button_exception extends portfolio_exception {} /** - * leap2a exception - for invalid api calls + * Leap2a exception - for invalid api calls + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class portfolio_format_leap2a_exception extends portfolio_exception {} diff --git a/lib/portfolio/exporter.php b/lib/portfolio/exporter.php index 9a836bcbb12..02c1b0095c2 100644 --- a/lib/portfolio/exporter.php +++ b/lib/portfolio/exporter.php @@ -1,137 +1,121 @@ . + /** - * Moodle - Modular Object-Oriented Dynamic Learning Environment - * http://moodle.org - * Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program. If not, see . - * - * @package core - * @subpackage portfolio - * @author Penny Leach - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL - * @copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * * This file contains the class definition for the exporter object. + * + * @package core_portfolio + * @copyright 2008 Penny Leach + * Martin Dougiamas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ defined('MOODLE_INTERNAL') || die(); /** -* The class that handles the various stages of the actual export -* and the communication between the caller and the portfolio plugin. -* this is stored in the database between page requests in serialized base64 encoded form -* also contains helper methods for the plugin and caller to use (at the end of the file) -* {@see get_base_filearea} - where to write files to -* {@see write_new_file} - write some content to a file in the export filearea -* {@see copy_existing_file} - copy an existing file into the export filearea -* {@see get_tempfiles} - return list of all files in the export filearea -*/ + * The class that handles the various stages of the actual export + * and the communication between the caller and the portfolio plugin. + * this is stored in the database between page requests in serialized base64 encoded form + * also contains helper methods for the plugin and caller to use (at the end of the file) + * {@see get_base_filearea} - where to write files to + * {@see write_new_file} - write some content to a file in the export filearea + * {@see copy_existing_file} - copy an existing file into the export filearea + * {@see get_tempfiles} - return list of all files in the export filearea + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * Martin Dougiamas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class portfolio_exporter { - /** - * the caller object used during the export - */ + /** @var portfolio_caller_base the caller object used during the export */ private $caller; - /** the portfolio plugin instanced used during the export - */ + /** @var portfolio_plugin_base the portfolio plugin instanced used during the export */ private $instance; - /** - * if there has been no config form displayed to the user - */ + /** @var bool if there has been no config form displayed to the user */ private $noexportconfig; /** - * the user currently exporting content - * always $USER, but more conveniently placed here - */ + * @var stdClass the user currently exporting content always $USER, + * but more conveniently placed here + */ private $user; - /** the file to include that contains the class defintion - * of the portfolio instance plugin - * used to re-waken the object after sleep - */ + /** + * @var string the file to include that contains the class defintion of + * the portfolio instance plugin used to re-waken the object after sleep + */ public $instancefile; /** - * the file to include that contains the class definition - * of the caller object - * used to re-waken the object after sleep - */ + * @var string the file to include that contains the class definition of + * the caller object used to re-waken the object after sleep + */ public $callerfile; - /** - * the current stage of the export - */ + /** @var int the current stage of the export */ private $stage; - /** - * whether something (usually the portfolio plugin) - * has forced queuing - */ + /** @var bool whether something (usually the portfolio plugin) has forced queuing */ private $forcequeue; /** - * id of this export - * matches record in portfolio_tempdata table - * and used for itemid for file storage. - */ + * @var int id of this export matches record in portfolio_tempdata table + * and used for itemid for file storage. + */ private $id; - /** - * array of stages that have had the portfolio plugin already steal control from them - */ + /** @var array of stages that have had the portfolio plugin already steal control from them */ private $alreadystolen; /** - * files that the exporter has written to this temp area - * keep track of this in case of duplicates within one export - * see MDL-16390 - */ + * @var stored_file files that the exporter has written to this temp area keep track of + * this in case of duplicates within one export see MDL-16390 + */ private $newfilehashes; /** - * selected exportformat - * this is also set in export_config in the portfolio and caller classes - */ + * @var string selected exportformat this is also set in + * export_config in the portfolio and caller classes + */ private $format; - /** - * queued - this is set after the event is triggered - */ + /** @var bool queued - this is set after the event is triggered */ private $queued = false; - /** - * expiry time - set the first time the object is saved out - */ + /** @var int expiry time - set the first time the object is saved out */ private $expirytime; /** - * deleted - this is set during the cleanup routine - * so that subsequent save() calls can detect it + * @var bool deleted - this is set during the cleanup routine so + * that subsequent save() calls can detect it */ private $deleted = false; /** - * construct a new exporter for use - * - * @param portfolio_plugin_base subclass $instance portfolio instance (passed by reference) - * @param portfolio_caller_base subclass $caller portfolio caller (passed by reference) - * @param string $callerfile path to callerfile (relative to dataroot) - */ + * Construct a new exporter for use + * + * @param portfolio_plugin_base $instance portfolio instance (passed by reference) + * @param portfolio_caller_base $caller portfolio caller (passed by reference) + * @param string $callerfile path to callerfile (relative to dataroot) + */ public function __construct(&$instance, &$caller, $callerfile) { $this->instance =& $instance; $this->caller =& $caller; @@ -146,11 +130,13 @@ class portfolio_exporter { $this->newfilehashes = array(); } - /* - * generic getter for properties belonging to this instance - * outside the subclasses - * like name, visible etc. - */ + /** + * Generic getter for properties belonging to this instance + * outside the subclasses like name, visible etc. + * + * @param string $field property's name + * @return portfolio_format|mixed + */ public function get($field) { if ($field == 'format') { return portfolio_format_object($this->format); @@ -165,10 +151,14 @@ class portfolio_exporter { } /** - * generic setter for properties belonging to this instance - * outside the subclass - * like name, visible, etc. - */ + * Generic setter for properties belonging to this instance + * outside the subclass like name, visible, etc. + * + * @param string $field property's name + * @param mixed $value property's value + * @return bool + * @throws portfolio_export_exception + */ public function set($field, &$value) { if (property_exists($this, $field)) { $this->{$field} =& $value; @@ -185,23 +175,22 @@ class portfolio_exporter { } /** - * sets this export to force queued - * sometimes plugins need to set this randomly - * if an external system changes its mind - * about what's supported - */ + * Sets this export to force queued. + * Sometimes plugins need to set this randomly + * if an external system changes its mind + * about what's supported + */ public function set_forcequeue() { $this->forcequeue = true; } /** - * process the given stage calling whatever functions are necessary - * - * @param int $stage (see PORTFOLIO_STAGE_* constants) - * @param boolean $alreadystolen used to avoid letting plugins steal control twice. - * - * @return boolean whether or not to process the next stage. this is important as the function is called recursively. - */ + * Process the given stage calling whatever functions are necessary + * + * @param int $stage (see PORTFOLIO_STAGE_* constants) + * @param bool $alreadystolen used to avoid letting plugins steal control twice. + * @return bool whether or not to process the next stage. this is important as the function is called recursively. + */ public function process_stage($stage, $alreadystolen=false) { $this->set('stage', $stage); if ($alreadystolen) { @@ -259,28 +248,28 @@ class portfolio_exporter { } /** - * helper function to return the portfolio instance - * - * @return portfolio_plugin_base subclass - */ + * Helper function to return the portfolio instance + * + * @return portfolio_plugin_base subclass + */ public function instance() { return $this->instance; } /** - * helper function to return the caller object - * - * @return portfolio_caller_base subclass - */ + * Helper function to return the caller object + * + * @return portfolio_caller_base subclass + */ public function caller() { return $this->caller; } /** - * processes the 'config' stage of the export - * - * @return boolean whether or not to process the next stage. this is important as the control function is called recursively. - */ + * Processes the 'config' stage of the export + * + * @return bool whether or not to process the next stage. this is important as the control function is called recursively. + */ public function process_stage_config() { global $OUTPUT, $CFG; $pluginobj = $callerobj = null; @@ -368,10 +357,10 @@ class portfolio_exporter { } /** - * processes the 'confirm' stage of the export - * - * @return boolean whether or not to process the next stage. this is important as the control function is called recursively. - */ + * Processes the 'confirm' stage of the export + * + * @return bool whether or not to process the next stage. this is important as the control function is called recursively. + */ public function process_stage_confirm() { global $CFG, $DB, $OUTPUT; @@ -433,10 +422,10 @@ class portfolio_exporter { } /** - * processes the 'queueornext' stage of the export - * - * @return boolean whether or not to process the next stage. this is important as the control function is called recursively. - */ + * Processes the 'queueornext' stage of the export + * + * @return bool whether or not to process the next stage. this is important as the control function is called recursively. + */ public function process_stage_queueorwait() { $wait = $this->instance->get_export_config('wait'); if (empty($wait)) { @@ -448,10 +437,11 @@ class portfolio_exporter { } /** - * processes the 'package' stage of the export - * - * @return boolean whether or not to process the next stage. this is important as the control function is called recursively. - */ + * Processes the 'package' stage of the export + * + * @return bool whether or not to process the next stage. this is important as the control function is called recursively. + * @throws portfolio_export_exception + */ public function process_stage_package() { // now we've agreed on a format, // the caller is given control to package it up however it wants @@ -477,12 +467,12 @@ class portfolio_exporter { } /** - * processes the 'cleanup' stage of the export - * - * @param boolean $pullok normally cleanup is deferred for pull plugins until after the file is requested from portfolio/file.php - * if you want to clean up earlier, pass true here (defaults to false) - * @return boolean whether or not to process the next stage. this is important as the control function is called recursively. - */ + * Processes the 'cleanup' stage of the export + * + * @param bool $pullok normally cleanup is deferred for pull plugins until after the file is requested from portfolio/file.php + * if you want to clean up earlier, pass true here (defaults to false) + * @return bool whether or not to process the next stage. this is important as the control function is called recursively. + */ public function process_stage_cleanup($pullok=false) { global $CFG, $DB; @@ -501,10 +491,10 @@ class portfolio_exporter { } /** - * processes the 'send' stage of the export - * - * @return boolean whether or not to process the next stage. this is important as the control function is called recursively. - */ + * Processes the 'send' stage of the export + * + * @return bool whether or not to process the next stage. this is important as the control function is called recursively. + */ public function process_stage_send() { // send the file try { @@ -523,10 +513,11 @@ class portfolio_exporter { } /** - * log the transfer - * this should only be called after the file has been sent - * either via push, or sent from a pull request. - */ + * Log the transfer + * + * this should only be called after the file has been sent + * either via push, or sent from a pull request. + */ public function log_transfer() { global $DB; $l = array( @@ -544,8 +535,10 @@ class portfolio_exporter { } /** - * in some cases (mahara) we need to update this after the log has been done + * In some cases (mahara) we need to update this after the log has been done * because of MDL-20872 + * + * @param string $url link to be recorded to portfolio log */ public function update_log_url($url) { global $DB; @@ -553,10 +546,11 @@ class portfolio_exporter { } /** - * processes the 'finish' stage of the export - * - * @return boolean whether or not to process the next stage. this is important as the control function is called recursively. - */ + * Processes the 'finish' stage of the export + * + * @param bool $queued let the process to be queued + * @return bool whether or not to process the next stage. this is important as the control function is called recursively. + */ public function process_stage_finished($queued=false) { global $OUTPUT; $returnurl = $this->caller->get_return_url(); @@ -578,10 +572,12 @@ class portfolio_exporter { /** - * local print header function to be reused across the export - * - * @param string $headerstring full language string - */ + * Local print header function to be reused across the export + * + * @param string $headingstr full language string + * @param bool $summary (optional) to print summary, default is set to true + * @return void + */ public function print_header($headingstr, $summary=true) { global $OUTPUT, $PAGE; $titlestr = get_string('exporting', 'portfolio'); @@ -609,9 +605,13 @@ class portfolio_exporter { } /** - * cancels a potfolio request and cleans up the tempdata - * and redirects the user back to where they started - */ + * Cancels a potfolio request and cleans up the tempdata + * and redirects the user back to where they started + * + * @param bool $logreturn options to return to porfolio log or caller return page + * @return void + * @uses exit + */ public function cancel_request($logreturn=false) { global $CFG; if (!isset($this)) { @@ -626,8 +626,10 @@ class portfolio_exporter { } /** - * writes out the contents of this object and all its data to the portfolio_tempdata table and sets the 'id' field. - */ + * Writes out the contents of this object and all its data to the portfolio_tempdata table and sets the 'id' field. + * + * @return void + */ public function save() { global $DB; if (empty($this->id)) { @@ -654,13 +656,12 @@ class portfolio_exporter { } /** - * rewakens the data from the database given the id - * makes sure to load the required files with the class definitions - * - * @param int $id id of data - * - * @return portfolio_exporter - */ + * Rewakens the data from the database given the id. + * Makes sure to load the required files with the class definitions + * + * @param int $id id of data + * @return portfolio_exporter + */ public static function rewaken_object($id) { global $DB, $CFG; require_once($CFG->libdir . '/filelib.php'); @@ -692,12 +693,13 @@ class portfolio_exporter { } /** - * helper function to create the beginnings of a file_record object - * to create a new file in the portfolio_temporary working directory - * use {@see write_new_file} or {@see copy_existing_file} externally - * - * @param string $name filename of new record - */ + * Helper function to create the beginnings of a file_record object + * to create a new file in the portfolio_temporary working directory. + * Use {@see write_new_file} or {@see copy_existing_file} externally + * + * @param string $name filename of new record + * @return object + */ private function new_file_record_base($name) { return (object)array_merge($this->get_base_filearea(), array( 'filepath' => '/', @@ -706,15 +708,12 @@ class portfolio_exporter { } /** - * verifies a rewoken object - * - * checks to make sure it belongs to the same user and session as is currently in use. - * - * @param boolean $readonly if we're reawakening this for a user to just display in the log view, don't verify the sessionkey - * when continuing transfers, you must pass false here. - * - * @throws portfolio_exception - */ + * Verifies a rewoken object. + * Checks to make sure it belongs to the same user and session as is currently in use. + * + * @param bool $readonly if we're reawakening this for a user to just display in the log view, don't verify the sessionkey + * @throws portfolio_exception + */ public function verify_rewaken($readonly=false) { global $USER, $CFG; if ($this->get('user')->id != $USER->id) { // make sure it belongs to the right user @@ -735,13 +734,13 @@ class portfolio_exporter { } } /** - * copies a file from somewhere else in moodle - * to the portfolio temporary working directory - * associated with this export - * - * @param $oldfile stored_file object - * @return stored_file new file object - */ + * Copies a file from somewhere else in moodle + * to the portfolio temporary working directory + * associated with this export + * + * @param stored_file $oldfile existing stored file object + * @return stored_file|bool new file object + */ public function copy_existing_file($oldfile) { if (array_key_exists($oldfile->get_contenthash(), $this->newfilehashes)) { return $this->newfilehashes[$oldfile->get_contenthash()]; @@ -761,15 +760,15 @@ class portfolio_exporter { } /** - * writes out some content to a file in the - * portfolio temporary working directory - * associated with this export - * - * @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 stored_file new file object - */ + * Writes out some content to a file + * in the portfolio temporary working directory + * associated with this export. + * + * @param string $content content to write + * @param string $name filename to use + * @param bool $manifest whether this is the main file or an secondary file (eg attachment) + * @return stored_file + */ public function write_new_file($content, $name, $manifest=true) { $fs = get_file_storage(); $file_record = $this->new_file_record_base($name); @@ -780,13 +779,12 @@ class portfolio_exporter { } /** - * zips all files in the temporary directory - * - * @param string $filename name of resulting zipfile (optional, defaults to portfolio-export.zip - * @param string $filepath subpath in the filearea (optional, defaults to final) - * - * @return stored_file resulting stored_file object - */ + * Zips all files in the temporary directory + * + * @param string $filename name of resulting zipfile (optional, defaults to portfolio-export.zip) + * @param string $filepath subpath in the filearea (optional, defaults to final) + * @return stored_file|bool resulting stored_file object, or false + */ public function zip_tempfiles($filename='portfolio-export.zip', $filepath='/final/') { $zipper = new zip_packer(); @@ -799,12 +797,13 @@ class portfolio_exporter { } /** - * returns an arary of files in the temporary working directory - * for this export - * always use this instead of the files api directly - * - * @return array of stored_file objects keyed by name - */ + * Returns an arary of files in the temporary working directory + * for this export. + * Always use this instead of the files api directly + * + * @param string $skipfile name of the file to be skipped + * @return array of stored_file objects keyed by name + */ public function get_tempfiles($skipfile='portfolio-export.zip') { $fs = get_file_storage(); $files = $fs->get_area_files(SYSCONTEXTID, 'portfolio', 'exporter', $this->id, '', false); @@ -822,14 +821,14 @@ class portfolio_exporter { } /** - * returns the context, filearea, and itemid - * parts of a filearea (not filepath) to be used by - * plugins if they want to do things like zip up the contents of - * the temp area to here, or something that can't be done just using - * write_new_file, copy_existing_file or get_tempfiles - * - * @return array contextid, filearea, itemid are the keys. - */ + * Returns the context, filearea, and itemid. + * Parts of a filearea (not filepath) to be used by + * plugins if they want to do things like zip up the contents of + * the temp area to here, or something that can't be done just using + * write_new_file, copy_existing_file or get_tempfiles + * + * @return array contextid, filearea, itemid are the keys. + */ public function get_base_filearea() { return array( 'contextid' => SYSCONTEXTID, @@ -839,11 +838,13 @@ class portfolio_exporter { ); } - /** wrapper function to print a friendly error to users - * - * this is generally caused by them hitting an expired transfer - * through the usage of the backbutton - */ + /** + * Wrapper function to print a friendly error to users + * This is generally caused by them hitting an expired transfer + * through the usage of the backbutton + * + * @uses exit + */ public static function print_expired_export() { global $CFG, $OUTPUT, $PAGE; $title = get_string('exportexpired', 'portfolio'); @@ -857,6 +858,13 @@ class portfolio_exporter { exit; } + /** + * Wrapper function to print a friendly error to users + * + * @param stdClass $log portfolio_log object + * @param portfolio_plugin_base $instance portfolio instance + * @uses exit + */ public static function print_cleaned_export($log, $instance=null) { global $CFG, $OUTPUT, $PAGE; if (empty($instance) || !$instance instanceof portfolio_plugin_base) { @@ -874,6 +882,13 @@ class portfolio_exporter { exit; } + /** + * Wrapper function to print continue and/or return link + * + * @param string $returnurl link to previos page + * @param string $continueurl continue to next page + * @param array $extras (optional) other links to be display. + */ public static function print_finish_info($returnurl, $continueurl, $extras=null) { if ($returnurl) { echo '' . get_string('returntowhereyouwere', 'portfolio') . '
'; diff --git a/lib/portfolio/formats.php b/lib/portfolio/formats.php index c462daa87c1..e38acd766a9 100644 --- a/lib/portfolio/formats.php +++ b/lib/portfolio/formats.php @@ -1,75 +1,90 @@ . + /** - * Moodle - Modular Object-Oriented Dynamic Learning Environment - * http://moodle.org - * Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program. If not, see . - * - * @package core - * @subpackage portfolio - * @author Penny Leach - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL - * @copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * * This file contains all the class definitions of the export formats. * They are implemented in php classes rather than just a simpler hash * Because it provides an easy way to do subtyping using php inheritance. + * + * @package core_portfolio + * @copyright 2008 Penny Leach , + * Martin Dougiamas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ defined('MOODLE_INTERNAL') || die(); /** - * base class to inherit from - * do not use this anywhere in supported_formats + * Base class to inherit from. + * Do not use this anywhere in supported_formats + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach , + * Martin Dougiamas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * */ abstract class portfolio_format { /** - * array of mimetypes this format supports + * Array of mimetypes this format supports + * + * @throws coding_exception */ public static function mimetypes() { throw new coding_exception('mimetypes() method needs to be overridden in each subclass of portfolio_format'); } /** - * 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 + * For multipart formats, eg html with attachments, + * we need to have a directory to place associated files from + * inside the zip file. This is the name of that directory + * + * @throws coding_exception */ public static function get_file_directory() { throw new coding_exception('get_file_directory() method needs to be overridden in each subclass of portfolio_format'); } /** - * given a file, return a snippet of markup in whatever format + * 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} - * this is not supported in subclasses of portfolio_format_file + * Usually involves the path given by {@see get_file_directory}. + * This is not supported in subclasses of portfolio_format_file * since they're all just single files. * - * @param stored_file $file - * @param array $options array of options to pass. can contain: + * @param stored_file $file file information object + * @param array $options array of options to pass. can contain: * attributes => hash of existing html attributes (eg title, height, width, etc) - * and whatever the sub class adds into this list * - * @return string some html or xml or whatever + * @throws coding_exception */ public static function file_output($file, $options=null) { throw new coding_exception('file_output() method needs to be overridden in each subclass of portfolio_format'); } + /** + * Create portfolio tag + * + * @param stored_file $file file information object + * @param string $path file path + * @param array $attributes portfolio attributes + * @return string + */ public static function make_tag($file, $path, $attributes) { $srcattr = 'href'; $tag = 'a'; @@ -97,23 +112,21 @@ abstract class portfolio_format { } /** - * whether this format conflicts with the given format - * this is used for the case where an export location + * Whether this format conflicts with the given format. + * This is used for the case where an export location * "generally" supports something like FORMAT_PLAINHTML - * but then in a specific export case, must add attachments - * which means that FORMAT_RICHHTML is supported in that case + * but then in a specific export case, must add attachments, + * which means that FORMAT_RICHHTML is supported in that case, * which implies removing support for FORMAT_PLAINHTML. * Note that conflicts don't have to be bi-directional * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML * but not the other way around) and things within the class hierarchy * are resolved automatically anyway. - * * This is really just between subclasses of format_rich * and subclasses of format_file. * * @param string $format one of the FORMAT_XX constants - * - * @return boolean + * @return bool */ public static function conflicts($format) { return false; @@ -121,34 +134,86 @@ abstract class portfolio_format { } /** -* the most basic type - pretty much everything is a subtype -*/ + * The most basic type - pretty much everything is a subtype + * + * @package core_portfolio + * @category portfolio + * @copyright 2009 Penny Leach , Martin Dougiamas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class portfolio_format_file extends portfolio_format { + /** + * Array of mimetypes this format supports + * + * @return array + */ public static function mimetypes() { return array(); } + /** + * For multipart formats, eg html with attachments, + * we need to have a directory to place associated files from + * inside the zip file. This is the name of that directory + * + * @return bool + */ public static function get_file_directory() { return false; } + /** + * Given a file, return a snippet of markup in whatever format + * to link to that file. + * Usually involves the path given by {@see get_file_directory}. + * This is not supported in subclasses of portfolio_format_file + * since they're all just single files. + * + * @param stored_file $file informations object + * @param array $options array of options to pass. can contain: + * attributes => hash of existing html attributes (eg title, height, width, etc) + */ public static function file_output($file, $options=null) { throw new portfolio_exception('fileoutputnotsupported', 'portfolio'); } } /** -* image format, subtype of file. -*/ + * Image format, subtype of file. + * + * @package core_portfolio + * @category portfolio + * @copyright 2009 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class portfolio_format_image extends portfolio_format_file { /** - * return all mimetypes that use image.gif (eg all images) + * Return all mimetypes that use image.gif (eg all images) + * + * @return string */ public static function mimetypes() { return mimeinfo_from_icon('type', 'image', true); } + /** + * Whether this format conflicts with the given format. + * This is used for the case where an export location + * "generally" supports something like FORMAT_PLAINHTML + * but then in a specific export case, must add attachments, + * which means that FORMAT_RICHHTML is supported in that case, + * which implies removing support for FORMAT_PLAINHTML. + * Note that conflicts don't have to be bi-directional + * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML + * but not the other way around) and things within the class hierarchy + * are resolved automatically anyway. + * This is really just between subclasses of format_rich + * and subclasses of format_file. + * + * @param string $format one of the FORMAT_XX constants + * @return bool + */ public static function conflicts($format) { return ($format == PORTFOLIO_FORMAT_RICHHTML || $format == PORTFOLIO_FORMAT_PLAINHTML); @@ -156,16 +221,42 @@ class portfolio_format_image extends portfolio_format_file { } /** -* html format - could be used for an external cms or something -* -* in case we want to be really specific. -*/ + * HTML format + * Could be used for an external cms or something in case we want to be really specific. + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class portfolio_format_plainhtml extends portfolio_format_file { + /** + * Return html mimetype + * + * @return array + */ public static function mimetypes() { return array('text/html'); } + /** + * Whether this format conflicts with the given format. + * This is used for the case where an export location + * "generally" supports something like FORMAT_PLAINHTML + * but then in a specific export case, must add attachments, + * which means that FORMAT_RICHHTML is supported in that case, + * which implies removing support for FORMAT_PLAINHTML. + * Note that conflicts don't have to be bi-directional + * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML + * but not the other way around) and things within the class hierarchy + * are resolved automatically anyway. + * This is really just between subclasses of format_rich + * and subclasses of format_file. + * + * @param string $format one of the FORMAT_XX constants + * @return bool + */ public static function conflicts($format) { return ($format == PORTFOLIO_FORMAT_RICHHTML || $format == PORTFOLIO_FORMAT_FILE); @@ -173,11 +264,21 @@ class portfolio_format_plainhtml extends portfolio_format_file { } /** -* video format, subtype of file. -* -* for portfolio plugins that support videos specifically -*/ + * Video format + * For portfolio plugins that support videos specifically + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class portfolio_format_video extends portfolio_format_file { + + /** + * Return video mimetypes + * + * @return array + */ public static function mimetypes() { return array_merge( mimeinfo_from_icon('type', 'video', true), @@ -187,14 +288,43 @@ class portfolio_format_video extends portfolio_format_file { } /** -* class for plain text format.. not sure why we would need this yet -* but since resource module wants to export it... we can -*/ + * Class for plain text format. + * Not sure why we would need this yet, + * but since resource module wants to export it... we can + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class portfolio_format_text extends portfolio_format_file { + + /** + * Return plain text mimetypes + * + * @return array + */ public static function mimetypes() { return array('text/plain'); } + /** + * Whether this format conflicts with the given format. + * This is used for the case where an export location + * "generally" supports something like FORMAT_PLAINHTML + * but then in a specific export case, must add attachments, + * which means that FORMAT_RICHHTML is supported in that case, + * which implies removing support for FORMAT_PLAINHTML. + * Note that conflicts don't have to be bi-directional + * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML + * but not the other way around) and things within the class hierarchy + * are resolved automatically anyway. + * This is really just between subclasses of format_rich + * and subclasses of format_file. + * + * @param string $format one of the FORMAT_XX constants + * @return bool + */ public static function conflicts($format ) { return ($format == PORTFOLIO_FORMAT_PLAINHTML || $format == PORTFOLIO_FORMAT_RICHHTML); @@ -202,11 +332,21 @@ class portfolio_format_text extends portfolio_format_file { } /** - * base class for rich formats. - * these are multipart - eg things with attachments + * Base class for rich formats. + * These are multipart - eg things with attachments + * + * @package core_portfolio + * @category portfolio + * @copyright 2009 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ abstract class portfolio_format_rich extends portfolio_format { + /** + * Return rich text mimetypes + * + * @return array + */ public static function mimetypes() { return array(); } @@ -214,13 +354,40 @@ abstract class portfolio_format_rich extends portfolio_format { } /** - * most commonly used rich format - richhtml - html with attachments + * Richhtml - html with attachments. + * The most commonly used rich format * eg inline images + * + * @package core_portfolio + * @category portfolio + * @copyright 2009 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class portfolio_format_richhtml extends portfolio_format_rich { + + /** + * For multipart formats, eg html with attachments, + * we need to have a directory to place associated files from + * inside the zip file. this is the name of that directory + * + * @return string + */ public static function get_file_directory() { return 'site_files/'; } + + /** + * Given a file, return a snippet of markup in whatever format + * to link to that file. + * Usually involves the path given by {@see get_file_directory}. + * This is not supported in subclasses of portfolio_format_file + * since they're all just single files. + * + * @param stored_file $file information for existing file + * @param array $options array of options to pass. can contain: + * attributes => hash of existing html attributes (eg title, height, width, etc) + * @return string + */ public static function file_output($file, $options=null) { $path = self::get_file_directory() . $file->get_filename(); $attributes = array(); @@ -229,28 +396,68 @@ class portfolio_format_richhtml extends portfolio_format_rich { } return self::make_tag($file, $path, $attributes); } + + /** + * Whether this format conflicts with the given format. + * This is used for the case where an export location + * "generally" supports something like FORMAT_PLAINHTML + * but then in a specific export case, must add attachments, + * which means that FORMAT_RICHHTML is supported in that case, + * which implies removing support for FORMAT_PLAINHTML. + * Note that conflicts don't have to be bi-directional + * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML + * but not the other way around) and things within the class hierarchy + * are resolved automatically anyway. + * This is really just between subclasses of format_rich + * and subclasses of format_file. + * + * @todo MDL-31305 - revisit the conflict with file, since we zip here + * @param string $format one of the FORMAT_XX constants + * @return bool + */ public static function conflicts($format) { // TODO revisit the conflict with file, since we zip here return ($format == PORTFOLIO_FORMAT_PLAINHTML || $format == PORTFOLIO_FORMAT_FILE); } } +/** + * Class used for leap2a format + * + * @package core_portfolio + * @category portfolio + * @copyright 2009 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class portfolio_format_leap2a extends portfolio_format_rich { + /** + * For multipart formats, eg html with attachments, + * we need to have a directory to place associated files from + * inside the zip file. this is the name of that directory + * + * @return string + */ public static function get_file_directory() { return 'files/'; } + /** + * Return the file prefix + * + * @return string + */ public static function file_id_prefix() { return 'storedfile'; } /** - * return the link to a file + * Return the link to a file * - * @param stored_file $file - * @param array $options can contain the same as normal, with the addition of: - * entry => whether the file is a LEAP2A entry or just a bundled file (default true) + * @param stored_file $file information for existing file + * @param array $options array of options to pass. can contain: + * attributes => hash of existing html attributes (eg title, height, width, etc) + * @return string */ public static function file_output($file, $options=null) { $id = ''; @@ -273,6 +480,12 @@ class portfolio_format_leap2a extends portfolio_format_rich { return self::make_tag($file, $path, $attributes); } + /** + * Generate portfolio_format_leap2a + * + * @param stdclass $user user information object + * @return portfolio_format_leap2a_writer + */ public static function leap2a_writer(stdclass $user=null) { global $CFG; if (empty($user)) { @@ -283,35 +496,58 @@ class portfolio_format_leap2a extends portfolio_format_rich { return new portfolio_format_leap2a_writer($user); } + /** + * Return the manifest name + * + * @return string + */ public static function manifest_name() { return 'leap2a.xml'; } } -/** -* later.... a moodle plugin might support this. -* it's commented out in portfolio_supported_formats so cannot currently be used. -*/ +// later.... a moodle plugin might support this. +// it's commented out in portfolio_supported_formats so cannot currently be used. //class portfolio_format_mbkp extends portfolio_format_rich {} /** -* 'PDF format', subtype of file. -* -* for portfolio plugins that support PDFs specifically -*/ + * 'PDF format', subtype of file. + * For portfolio plugins that support PDFs specifically. + * + * @package core_portfolio + * @category portfolio + * @copyright 2009 Dan Poltawski + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class portfolio_format_pdf extends portfolio_format_file { + + /** + * Return pdf mimetypes + * + * @return array + */ public static function mimetypes() { return array('application/pdf'); } } /** -* 'Document format', subtype of file. -* -* for portfolio plugins that support documents specifically -*/ + * 'Document format', subtype of file. + * For portfolio plugins that support documents specifically. + * + * @package core_portfolio + * @category portfolio + * @copyright 2009 Dan Poltawski + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class portfolio_format_document extends portfolio_format_file { + + /** + * Return documents mimetypes + * + * @return array of documents mimetypes + */ public static function mimetypes() { return array_merge( array('text/plain', 'text/rtf'), @@ -323,11 +559,21 @@ class portfolio_format_document extends portfolio_format_file { } /** -* 'Spreadsheet format', subtype of file. -* -* for portfolio plugins that support spreadsheets specifically -*/ + * 'Spreadsheet format', subtype of file. + * For portfolio plugins that support spreadsheets specifically. + * + * @package core_portfolio + * @category portfolio + * @copyright 2009 Dan Poltawski + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class portfolio_format_spreadsheet extends portfolio_format_file { + + /** + * Return spreadsheet spreadsheet mimetypes + * + * @return array of documents mimetypes + */ public static function mimetypes() { return array_merge( mimeinfo_from_icon('type', 'excel', true), @@ -338,11 +584,21 @@ class portfolio_format_spreadsheet extends portfolio_format_file { } /** -* 'Presentation format', subtype of file. -* -* for portfolio plugins that support presentation specifically -*/ + * 'Presentation format', subtype of file. + * For portfolio plugins that support presentation specifically. + * + * @package core_portfolio + * @category portfolio + * @copyright 2009 Dan Poltawski + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class portfolio_format_presentation extends portfolio_format_file { + + /** + * Return presentation documents mimetypes + * + * @return array presentation document mimetypes + */ public static function mimetypes() { return mimeinfo_from_icon('type', 'powerpoint', true); } diff --git a/lib/portfolio/formats/leap2a/lib.php b/lib/portfolio/formats/leap2a/lib.php index f705b674ebc..57e8a89337e 100644 --- a/lib/portfolio/formats/leap2a/lib.php +++ b/lib/portfolio/formats/leap2a/lib.php @@ -1,37 +1,33 @@ . + /** - * Moodle - Modular Object-Oriented Dynamic Learning Environment - * http://moodle.org - * Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program. If not, see . - * - * @package core - * @subpackage portfolio - * @author Penny Leach - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL - * @copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * * This file contains the LEAP2a writer used by portfolio_format_leap2a + * + * @package core_portfolio + * @copyright 2009 Penny Leach (penny@liip.ch), Martin Dougiamas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * */ defined('MOODLE_INTERNAL') || die(); /** - * object to encapsulate the writing of leap2a. - * should be used like: - * + * Object to encapsulate the writing of leap2a. + * Should be used like: * $writer = portfolio_format_leap2a::leap2a_writer($USER); * $entry = new portfolio_format_leap2a_entry('forumpost6', $title, 'leap2', 'somecontent') * $entry->add_link('something', 'has_part')->add_link('somethingelse', 'has_part'); @@ -39,26 +35,34 @@ defined('MOODLE_INTERNAL') || die(); * $writer->add_entry($entry); * $xmlstr = $writer->to_xml(); * - * @TODO find a way to ensure that all referenced files are included + * @todo MDL-31287 - find a way to ensure that all referenced files are included + * @package core_portfolio + * @category portfolio + * @copyright 2009 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class portfolio_format_leap2a_writer { - /** the domdocument object used to create elements */ + /** @var DomDocument the domdocument object used to create elements */ private $dom; - /** the top level feed element */ + + /** @var DOMElement the top level feed element */ private $feed; - /** the user exporting data */ + + /** @var stdClass the user exporting data */ private $user; - /** the id of the feed - this is unique to the user and date and used for portfolio ns as well as feed id */ + + /** @var string the id of the feed - this is unique to the user and date and used for portfolio ns as well as feed id */ private $id; - /** the entries for the feed - keyed on id */ + + /** @var array the entries for the feed - keyed on id */ private $entries = array(); /** - * constructor - usually generated from portfolio_format_leap2a::leap2a_writer($USER); + * Constructor - usually generated from portfolio_format_leap2a::leap2a_writer($USER); * + * @todo MDL-31302 - add exporter and format * @param stdclass $user the user exporting (almost always $USER) - * */ public function __construct(stdclass $user) { // todo something else - exporter, format, etc global $CFG; @@ -98,9 +102,10 @@ class portfolio_format_leap2a_writer { } /** - * adds a entry to the feed ready to be exported + * Adds a entry to the feed ready to be exported * - * @param portfolio_format_leap2a_entry $entry the entry to add + * @param portfolio_format_leap2a_entry $entry new feed entry to add + * @return portfolio_format_leap2a_entry */ public function add_entry(portfolio_format_leap2a_entry $entry) { if (array_key_exists($entry->id, $this->entries)) { @@ -113,11 +118,11 @@ class portfolio_format_leap2a_writer { } /** - * make an entry that has previously been added into the feed into a selection. + * Select an entry that has previously been added into the feed * - * @param mixed $selectionentry the entry to make a selection (id or entry object) + * @param portfolio_format_leap2a_entry|string $selectionentry the entry to make a selection (id or entry object) * @param array $ids array of ids this selection includes - * @param string $selectiontype http://wiki.cetis.ac.uk/2009-03/LEAP2A_categories/selection_type + * @param string $selectiontype for selection type, see: http://wiki.cetis.ac.uk/2009-03/LEAP2A_categories/selection_type */ public function make_selection($selectionentry, $ids, $selectiontype) { $selectionid = null; @@ -144,9 +149,9 @@ class portfolio_format_leap2a_writer { } /** - * helper function to link some stored_files into the feed and link them to a particular entry + * Helper function to link some stored_files into the feed and link them to a particular entry * - * @param portfolio_format_leap2a_entry $entry the entry to link the files into + * @param portfolio_format_leap2a_entry $entry feed object * @param array $files array of stored_files to link */ public function link_files($entry, $files) { @@ -159,7 +164,7 @@ class portfolio_format_leap2a_writer { } /** - * validate the feed and all entries + * Validate the feed and all entries */ private function validate() { foreach ($this->entries as $entry) { @@ -183,10 +188,10 @@ class portfolio_format_leap2a_writer { } /** - * return the entire feed as a string - * calls validate() first on everything + * Return the entire feed as a string. + * Then, it calls for validation * - * @return string + * @return string feeds' content in xml */ public function to_xml() { $this->validate(); @@ -199,45 +204,57 @@ class portfolio_format_leap2a_writer { } /** - * this class represents a single leap2a entry. - * you can create these directly and then add them to the main leap feed object + * This class represents a single leap2a entry. + * You can create these directly and then add them to the main leap feed object + * + * @package core_portfolio + * @category portfolio + * @copyright 2009 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class portfolio_format_leap2a_entry { - /** entry id - something like forumpost6, must be unique to the feed **/ + /** @var string entry id - something like forumpost6, must be unique to the feed */ public $id; - /** title of the entry **/ + + /** @var string title of the entry */ public $title; - /** leap2a entry type **/ + + /** @var string leap2a entry type */ public $type; - /** optional author (only if different to feed author) **/ + + /** @var string optional author (only if different to feed author) */ public $author; - /** summary - for split long content **/ + + /** @var string summary - for split long content */ public $summary; - /** main content of the entry. can be html,text,or xhtml. for a stored_file, use portfolio_format_leap2a_file **/ + + /** @var mixed main content of the entry. can be html,text,or xhtml. for a stored_file, use portfolio_format_leap2a_file **/ public $content; - /** updated date - unix timestamp */ + + /** @var int updated date - unix timestamp */ public $updated; - /** published date (ctime) - unix timestamp */ + + /** @var int published date (ctime) - unix timestamp */ public $published; - /** the required fields for a leap2a entry */ + /** @var array the required fields for a leap2a entry */ private $requiredfields = array( 'id', 'title', 'type'); - /** extra fields which usually should be set (except author) but are not required */ + /** @var array extra fields which usually should be set (except author) but are not required */ private $optionalfields = array('author', 'updated', 'published', 'content', 'summary'); - /** links from this entry to other entries */ + /** @var array links from this entry to other entries */ public $links = array(); - /** attachments to this entry */ + /** @var array attachments to this entry */ public $attachments = array(); - /** categories for this entry */ + /** @var array categories for this entry */ private $categories = array(); /** - * constructor. All arguments are required (and will be validated) + * Constructor. All arguments are required (and will be validated) * http://wiki.cetis.ac.uk/2009-03/LEAP2A_types * * @param string $id unique id of this entry. @@ -256,8 +273,12 @@ class portfolio_format_leap2a_entry { } /** - * override __set to do proper dispatching for different things - * only allows the optional and required leap2a entry fields to be set + * Override __set to do proper dispatching for different things. + * Only allows the optional and required leap2a entry fields to be set + * + * @param string $field property's name + * @param mixed $value property's value + * @return mixed */ public function __set($field, $value) { // detect the case where content is being set to be a file directly @@ -272,9 +293,11 @@ class portfolio_format_leap2a_entry { /** - * validate this entry. - * at the moment this just makes sure required fields exist + * Validate this entry. + * At the moment this just makes sure required fields exist * but it could also check things against a list, for example + * + * @todo MDL-31303 - add category with a scheme 'selection_type' */ public function validate() { foreach ($this->requiredfields as $key) { @@ -291,17 +314,17 @@ class portfolio_format_leap2a_entry { } /** - * add a link from this entry to another one - * these will be collated at the end of the export (during to_xml) + * Add a link from this entry to another one. + * These will be collated at the end of the export (during to_xml) * and validated at that point. This function does no validation - * http://wiki.cetis.ac.uk/2009-03/LEAP2A_relationships + * {@link http://wiki.cetis.ac.uk/2009-03/LEAP2A_relationships} * - * @param mixed $otherentry portfolio_format_leap2a_entry or its id + * @param portfolio_format_leap2a_entry|string $otherentry portfolio_format_leap2a_entry or its id * @param string $reltype (no leap2: ns required) - * - * @return the current entry object. This is so that these calls can be chained - * eg $entry->add_link('something6', 'has_part')->add_link('something7', 'has_part'); - * + * @param string $displayorder (optional) + * @return portfolio_format_leap2a_entry the current entry object. This is so that these calls can be chained + * eg $entry->add_link('something6', 'has_part')->add_link('something7', + * 'has_part'); */ public function add_link($otherentry, $reltype, $displayorder=null) { if ($otherentry instanceof portfolio_format_leap2a_entry) { @@ -321,15 +344,14 @@ class portfolio_format_leap2a_entry { } /** - * add a category to this entry - * http://wiki.cetis.ac.uk/2009-03/LEAP2A_categories + * Add a category to this entry + * {@link http://wiki.cetis.ac.uk/2009-03/LEAP2A_categories} + * "tags" should just pass a term here and no scheme or label. + * They will be automatically normalised if they have spaces. * * @param string $term eg 'Offline' * @param string $scheme (optional) eg resource_type * @param string $label (optional) eg File - * - * "tags" should just pass a term here and no scheme or label. - * they will be automatically normalised if they have spaces. */ public function add_category($term, $scheme=null, $label=null) { // "normalise" terms and set their label if they have spaces @@ -351,8 +373,8 @@ class portfolio_format_leap2a_entry { * This is handled by the main writer object. * * @param DomDocument $dom use this to create elements - * - * @return DomElement + * @param stdClass $feedauthor object of author(user) info + * @return DOMDocument */ public function to_dom(DomDocument $dom, $feedauthor) { $entry = $dom->createElement('entry'); @@ -413,16 +435,16 @@ class portfolio_format_leap2a_entry { } /** - * try to load whatever is in $content into xhtml and add it to the dom. - * failing that, load the html, escape it, and set it as the body of the tag - * either way it sets the type attribute of the top level element - * moodle should always provide xhtml content, but user-defined content can't be trusted + * Try to load whatever is in $content into xhtml and add it to the dom. + * Failing that, load the html, escape it, and set it as the body of the tag. + * Either way it sets the type attribute of the top level element. + * Moodle should always provide xhtml content, but user-defined content can't be trusted * + * @todo MDL-31304 - convert to xml * @param DomDocument $dom the dom doc to use * @param string $tagname usually 'content' or 'summary' * @param string $content the content to use, either xhtml or html. - * - * @return DomElement + * @return DomDocument */ private function create_xhtmlish_element(DomDocument $dom, $tagname, $content) { $topel = $dom->createElement($tagname); @@ -455,22 +477,29 @@ class portfolio_format_leap2a_entry { } /** - * hook function for subclasses to add extra links (like for files) + * Hook function for subclasses to add extra links (like for files) */ protected function add_extra_links() {} } - /** - * subclass of entry, purely for dealing with files + * Subclass of entry, purely for dealing with files + * + * @package core_portfolio + * @category portfolio + * @copyright 2009 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class portfolio_format_leap2a_file extends portfolio_format_leap2a_entry { + /** @var file_stored for the dealing file */ protected $referencedfile; /** - * overridden constructor to set up the file. + * Overridden constructor to set up the file. * + * @param string $title title of the entry + * @param stored_file $file file storage instance */ public function __construct($title, stored_file $file) { $id = portfolio_format_leap2a::file_id_prefix() . $file->get_id(); @@ -482,7 +511,10 @@ class portfolio_format_leap2a_file extends portfolio_format_leap2a_entry { } /** - * implement the hook to add extra links to attach the file in an enclosure + * Implement the hook to add extra links to attach the file in an enclosure + * + * @param DomDocument $dom feed object + * @param DomDocument $entry feed added link */ protected function add_extra_links($dom, $entry) { $link = $dom->createElement('link'); diff --git a/lib/portfolio/forms.php b/lib/portfolio/forms.php index db7880c0825..db93ef24f92 100644 --- a/lib/portfolio/forms.php +++ b/lib/portfolio/forms.php @@ -1,29 +1,26 @@ . + /** - * Moodle - Modular Object-Oriented Dynamic Learning Environment - * http://moodle.org - * Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program. If not, see . - * - * @package core - * @subpackage portfolio - * @author Penny Leach - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL - * @copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * * This file contains all the form definitions used by the portfolio code. + * + * @package core_portfolio + * @copyright 2008 Penny Leach , + * Martin Dougiamas (http://dougiamas.com) + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ defined('MOODLE_INTERNAL') || die(); @@ -32,17 +29,24 @@ defined('MOODLE_INTERNAL') || die(); require_once ($CFG->libdir.'/formslib.php'); /** -* During-export config form. -* -* This is the form that is actually used while exporting. -* Plugins and callers don't get to define their own class -* as we have to handle form elements from both places -* See the docs here for more information: -* http://docs.moodle.org/dev/Writing_a_Portfolio_Plugin#has_export_config -* http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page#has_export_config -*/ + * During-export config form. + * This is the form that is actually used while exporting. + * Plugins and callers don't get to define their own class + * as we have to handle form elements from both places + * See the docs here for more information: + * http://docs.moodle.org/dev/Writing_a_Portfolio_Plugin#has_export_config + * http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page#has_export_config + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ final class portfolio_export_form extends moodleform { + /** + * prepare form + */ public function definition() { $mform =& $this->_form; @@ -96,6 +100,12 @@ final class portfolio_export_form extends moodleform { $this->add_action_buttons(true, get_string('next')); } + /** + * Validate portfolio export form + * + * @param stdClass $data portfolio information from form data + * @return array + */ public function validation($data) { $errors = array(); @@ -117,20 +127,36 @@ final class portfolio_export_form extends moodleform { } /** -* Admin config form -* -* This form is extendable by plugins who want the admin to be able to configure more than just the name of the instance. -* This is NOT done by subclassing this class, see the docs for portfolio_plugin_base for more information: -* http://docs.moodle.org/dev/Writing_a_Portfolio_Plugin#has_admin_config -*/ + * Admin config form. + * This form is extendable by plugins who want the admin to be able to configure more than just the name of the instance. + * This is NOT done by subclassing this class, see the docs for portfolio_plugin_base for more information: + * {@link http://docs.moodle.org/dev/Writing_a_Portfolio_Plugin#has_admin_config} + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ final class portfolio_admin_form extends moodleform { + /** @var object to hold porfolio instance configuration */ protected $instance; + + /** @var string plugin name*/ protected $plugin; + + /** @var string portfolio plugin name*/ protected $portfolio; + + /** @var string plugin availability*/ protected $action; + + /** @var int portfolio plugin visibility*/ protected $visible; + /** + * prepare form + */ public function definition() { global $CFG; $this->plugin = $this->_customdata['plugin']; @@ -194,6 +220,12 @@ final class portfolio_admin_form extends moodleform { $this->add_action_buttons(true, get_string('save', 'portfolio')); } + /** + * Validate admin config form + * + * @param stdObject $data form data + * @return array + */ public function validation($data) { global $DB; @@ -217,18 +249,28 @@ final class portfolio_admin_form extends moodleform { } /** -* User config form. -* -* This is the form for letting the user configure an instance of a plugin. -* In order to extend this, you don't subclass this in the plugin.. -* see the docs in portfolio_plugin_base for more information: -* http://docs.moodle.org/dev/Writing_a_Portfolio_Plugin#has_user_config -*/ + * User config form. + * This is the form for letting the user configure an instance of a plugin. + * In order to extend this, you don't subclass this in the plugin.. + * see the docs in portfolio_plugin_base for more information: + * {@link http://docs.moodle.org/dev/Writing_a_Portfolio_Plugin#has_user_config} + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ final class portfolio_user_form extends moodleform { + /** @var object user porfolio instance */ protected $instance; + + /** @var int hold user id */ protected $userid; + /** + * prepare form + */ public function definition() { $this->instance = $this->_customdata['instance']; $this->userid = $this->_customdata['userid']; @@ -246,6 +288,11 @@ final class portfolio_user_form extends moodleform { $this->add_action_buttons(true, get_string('save', 'portfolio')); } + /** + * User user config form. + * + * @param stdClass $data form data + */ public function validation($data) { $errors = $this->instance->user_config_validation($data); @@ -255,15 +302,23 @@ final class portfolio_user_form extends moodleform { /** -* Form that just contains the dropdown menu of available instances -* -* This is not used by portfolio_add_button, but on the first step of the export -* if the plugin instance has not yet been selected. -*/ + * Form that just contains the dropdown menu of available instances. + * This is not used by portfolio_add_button, but on the first step of the export, + * if the plugin instance has not yet been selected. + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class portfolio_instance_select extends moodleform { + /** @var portfolio_caller_base plugin instance */ private $caller; + /** + * The required basic elements to the form. + */ function definition() { $this->caller = $this->_customdata['caller']; $options = $this->_customdata['options']; diff --git a/lib/portfolio/plugin.php b/lib/portfolio/plugin.php index a7b62658ab4..592d60632b5 100644 --- a/lib/portfolio/plugin.php +++ b/lib/portfolio/plugin.php @@ -1,246 +1,211 @@ . + /** - * Moodle - Modular Object-Oriented Dynamic Learning Environment - * http://moodle.org - * Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program. If not, see . - * - * @package core - * @subpackage portfolio - * @author Penny Leach - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL - * @copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * * This file contains the base classes for portfolio plugins to inherit from: + * * portfolio_plugin_pull_base and portfolio_plugin_push_base * which both in turn inherit from portfolio_plugin_base. - * See http://docs.moodle.org/dev/Writing_a_Portfolio_Plugin + * {@link http://docs.moodle.org/dev/Writing_a_Portfolio_Plugin} + * + * @package core_portfolio + * @copyright 2008 Penny Leach , + * Martin Dougiamas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ defined('MOODLE_INTERNAL') || die(); /** -* the base class for portfolio plugins -* all plugins must subclass this -* either via {@see portfolio_plugin_pull_base} or {@see portfolio_plugin_push_base} -*/ + * The base class for portfolio plugins. + * All plugins must subclass this + * either via {@see portfolio_plugin_pull_base} or {@see portfolio_plugin_push_base} + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ abstract class portfolio_plugin_base { - /** - * whether this object needs writing out to the database - * @var boolean $dirty - */ + /** @var bool whether this object needs writing out to the database */ protected $dirty; - /** - * id of instance - * @var integer $id - */ + /** @var integer id of instance */ protected $id; - /** - * name of instance - * @var string $name - */ + /** @var string name of instance */ protected $name; - /** - * plugin this instance belongs to - * @var string $plugin - */ + /** @var string plugin this instance belongs to */ protected $plugin; - /** - * whether this instance is visible or not - * @var boolean $visible - */ + /** @var bool whether this instance is visible or not */ protected $visible; - /** - * named array - * admin configured config - * use {@link set_config} and {@get_config} to access - */ + /** @var array admin configured config use {@link set_config} and {@get_config} to access */ protected $config; - /** - * - * user config cache - * named array of named arrays - * keyed on userid and then on config field => value - * use {@link get_user_config} and {@link set_user_config} to access. - */ + /** @var array user config cache. keyed on userid and then on config field => value use {@link get_user_config} and {@link set_user_config} to access. */ protected $userconfig; - /** - * named array - * export config during export - * use {@link get_export_config} and {@link set export_config} to access. - */ + /** @var array export config during export use {@link get_export_config} and {@link set export_config} to access. */ protected $exportconfig; - /** - * stdclass object - * user currently exporting data - */ + /** @var stdClass user currently exporting data */ protected $user; - /** - * a reference to the exporter object - */ + /** @var stdClass a reference to the exporter object */ protected $exporter; /** - * array of formats this portfolio supports - * the intersection of what this function returns - * and what the caller supports will be used - * use the constants PORTFOLIO_FORMAT_* - * - * @return array list of formats - */ + * Array of formats this portfolio supports + * the intersection of what this function returns + * and what the caller supports will be used. + * Use the constants PORTFOLIO_FORMAT_* + * + * @return array list of formats + */ public function supported_formats() { return array(PORTFOLIO_FORMAT_FILE, PORTFOLIO_FORMAT_RICH); } /** - * override this if you are supporting the 'file' type (or a subformat) - * but have restrictions on mimetypes - * - * @return boolean - */ + * Override this if you are supporting the 'file' type (or a subformat) + * but have restrictions on mimetypes + * + * @param string $mimetype file type or subformat + * @return bool + */ public static function file_mime_check($mimetype) { return true; } /** - * how long does this reasonably expect to take.. - * should we offer the user the option to wait.. - * this is deliberately nonstatic so it can take filesize into account - * - * @param string $callertime - what the caller thinks - * the portfolio plugin instance - * is given the final say - * because it might be (for example) download. - * @return string (see PORTFOLIO_TIME_* constants) - */ + * How long does this reasonably expect to take.. + * Should we offer the user the option to wait.. + * This is deliberately nonstatic so it can take filesize into account + * + * @param string $callertime - what the caller thinks + * the portfolio plugin instance + * is given the final say + * because it might be (for example) download. + */ public abstract function expected_time($callertime); /** - * is this plugin push or pill. - * if push, cleanup will be called directly after send_package - * if not, cleanup will be called after portfolio/file.php is requested - * - * @return boolean - */ + * Is this plugin push or pull. + * If push, cleanup will be called directly after send_package + * If not, cleanup will be called after portfolio/file.php is requested + */ public abstract function is_push(); /** - * returns the user-friendly name for this plugin - * usually just get_string('pluginname', 'portfolio_something') - * - * @return string + * Returns the user-friendly name for this plugin. + * Usually just get_string('pluginname', 'portfolio_something') */ public static function get_name() { throw new coding_exception('get_name() method needs to be overridden in each subclass of portfolio_plugin_base'); } /** - * check sanity of plugin - * 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 portfolio_$yourplugin) or 0/false if you're ok - */ + * Check sanity of plugin. + * 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 string|int|bool - string = error string KEY (must be inside portfolio_$yourplugin) or 0/false if you're ok + */ public static function plugin_sanity_check() { return 0; } /** - * check sanity of instances - * 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 portfolio_$yourplugin) or 0/false if you're ok - */ + * Check sanity of instances. + * 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 int|string|bool - string = error string KEY (must be inside portfolio_$yourplugin) or 0/false if you're ok + */ public function instance_sanity_check() { return 0; } /** - * does this plugin need any configuration by the administrator? - * - * if you override this to return true, - * you must implement {@see admin_config_form} - */ + * Does this plugin need any configuration by the administrator? + * If you override this to return true, + * you must implement {@see admin_config_form} + * + * @return bool + */ public static function has_admin_config() { return false; } /** - * can this plugin be configured by the user in their profile? - * - * if you override this to return true, - * you must implement {@see user_config_form} - */ + * Can this plugin be configured by the user in their profile? + * If you override this to return true, + * you must implement {@see user_config_form} + * + * @return bool + */ public function has_user_config() { return false; } /** - * does this plugin need configuration during export time? - * - * if you override this to return true, - * you must implement {@see export_config_form} - */ + * Does this plugin need configuration during export time? + * If you override this to return true, + * you must implement {@see export_config_form} + * + * @return bool + */ public function has_export_config() { return false; } /** - * just like the moodle form validation function - * this is passed in the data array from the form - * and if a non empty array is returned, form processing will stop. - * - * @param array $data data from form. - * @return array keyvalue pairs - form element => error string - */ + * Just like the moodle form validation function. + * This is passed in the data array from the form + * and if a non empty array is returned, form processing will stop. + * + * @param array $data data from form. + */ public function export_config_validation(array $data) {} /** - * just like the moodle form validation function - * this is passed in the data array from the form - * and if a non empty array is returned, form processing will stop. - * - * @param array $data data from form. - * @return array keyvalue pairs - form element => error string - */ + * Just like the moodle form validation function. + * This is passed in the data array from the form + * and if a non empty array is returned, form processing will stop. + * + * @param array $data data from form. + */ public function user_config_validation(array $data) {} /** - * sets the export time config from the moodle form. - * you can also use this to set export config that - * isn't actually controlled by the user - * eg things that your subclasses want to keep in state - * across the export. - * keys must be in {@see get_allowed_export_config} - * - * this is deliberately not final (see boxnet plugin) - * - * @param array $config named array of config items to set. - */ + * Sets the export time config from the moodle form. + * You can also use this to set export config that + * isn't actually controlled by the user. + * Eg: things that your subclasses want to keep in state + * across the export. + * Keys must be in {@see get_allowed_export_config} + * This is deliberately not final (see boxnet plugin) + * + * @param array $config named array of config items to set. + */ public function set_export_config($config) { $allowed = array_merge( array('wait', 'hidewait', 'format', 'hideformat'), @@ -256,14 +221,12 @@ abstract class portfolio_plugin_base { } /** - * gets an export time config value. - * subclasses should not override this. - * - * @param string key field to fetch - * - * @return string config value - * - */ + * Gets an export time config value. + * Subclasses should not override this. + * + * @param string $key field to fetch + * @return null|string config value + */ public final function get_export_config($key) { $allowed = array_merge( array('hidewait', 'wait', 'format', 'hideformat'), @@ -280,179 +243,175 @@ abstract class portfolio_plugin_base { } /** - * after the user submits their config - * they're given a confirm screen - * summarising what they've chosen. - * - * this function should return a table of nice strings => values - * of what they've chosen - * to be displayed in a table. - * - * @return array array of config items. - */ + * After the user submits their config, + * they're given a confirm screen + * summarising what they've chosen. + * This function should return a table of nice strings => values + * of what they've chosen + * to be displayed in a table. + * + * @return bool + */ public function get_export_summary() { return false; } /** - * called after the caller has finished having control - * of its prepare_package function. - * this function should read all the files from the portfolio - * working file area and zip them and send them or whatever it wants. - * {@see get_tempfiles} to get the list of files. - * - */ + * Called after the caller has finished having control + * of its prepare_package function. + * This function should read all the files from the portfolio + * working file area and zip them and send them or whatever it wants. + * {@see get_tempfiles} to get the list of files. + * + */ public abstract function prepare_package(); /** - * this is the function that is responsible for sending - * the package to the remote system, - * or whatever request is necessary to initiate the transfer. - * - * @return boolean success - */ + * This is the function that is responsible for sending + * the package to the remote system, + * or whatever request is necessary to initiate the transfer. + * + * @return bool success + */ public abstract function send_package(); /** - * once everything is done and the user - * has the finish page displayed to them - * the base class takes care of printing them - * "return to where you are" or "continue to portfolio" links - * this function allows for exta finish options from the plugin - * - * @return array named array of links => titles - */ + * Once everything is done and the user + * has the finish page displayed to them. + * The base class takes care of printing them + * "return to where you are" or "continue to portfolio" links. + * This function allows for exta finish options from the plugin + * + * @return bool + */ public function get_extra_finish_options() { return false; } /** - * the url for the user to continue to their portfolio - * during the lifecycle of the request - * - * @return string url or false. - */ + * The url for the user to continue to their portfolio + * during the lifecycle of the request + */ public abstract function get_interactive_continue_url(); /** - * the url to save in the log as the continue url - * this is passed through resolve_static_continue_url() + * The url to save in the log as the continue url. + * This is passed through resolve_static_continue_url() * at display time to the user. + * + * @return string */ public function get_static_continue_url() { return $this->get_interactive_continue_url(); } /** - * override this function if you need to add something on to the url - * for post-export continues (eg from the log page) - * mahara does this, for example, to start a jump session + * Override this function if you need to add something on to the url + * for post-export continues (eg from the log page). + * Mahara does this, for example, to start a jump session. + * + * @param string $url static continue url + * @return string */ public function resolve_static_continue_url($url) { return $url; } /** - * mform to display to the user in their profile - * if your plugin can't be configured by the user, - * (see {@link has_user_config}) - * don't bother overriding this function - * - * @param moodleform $mform passed by reference, add elements to it - */ + * mform to display to the user in their profile + * if your plugin can't be configured by the user, + * (see {@see has_user_config}). + * Don't bother overriding this function + * + * @param moodleform $mform passed by reference, add elements to it + */ public function user_config_form(&$mform) {} /** - * mform to display to the admin configuring the plugin. - * if your plugin can't be configured by the admin, - * (see {@link} has_admin_config) - * don't bother overriding this function - * - * this function can be called statically or non statically, - * depending on whether it's creating a new instance (statically), - * or editing an existing one (non statically) - * - * @param moodleform $mform passed by reference, add elements to it. - */ + * mform to display to the admin configuring the plugin. + * If your plugin can't be configured by the admin, + * (@see has_admin_config). + * Don't bother overriding this function. + * This function can be called statically or non statically, + * depending on whether it's creating a new instance (statically), + * or editing an existing one (non statically) + * + * @param moodleform $mform passed by reference, add elements to it. + */ public function admin_config_form(&$mform) {} /** - * just like the moodle form validation function - * this is passed in the data array from the form - * and if a non empty array is returned, form processing will stop. - * - * @param array $data data from form. - * @return array keyvalue pairs - form element => error string - */ + * Just like the moodle form validation function, + * this is passed in the data array from the form + * and if a non empty array is returned, form processing will stop. + * + * @param array $data data from form. + */ public function admin_config_validation($data) {} + /** - * mform to display to the user exporting data using this plugin. - * if your plugin doesn't need user input at this time, - * (see {@link has_export_config} - * don't bother overrideing this function - * - * @param moodleform $mform passed by reference, add elements to it. - */ + * mform to display to the user exporting data using this plugin. + * If your plugin doesn't need user input at this time, + * (see {@see has_export_config}. + * Don't bother overrideing this function + * + * @param moodleform $mform passed by reference, add elements to it. + */ public function export_config_form(&$mform) {} /** - * override this if your plugin doesn't allow multiple instances - * - * @return boolean - */ + * Override this if your plugin doesn't allow multiple instances + * + * @return bool + */ public static function allows_multiple_instances() { return true; } /** - * - * If at any point the caller wants to steal control - * it can, by returning something that isn't false - * in this function - * The controller will redirect to whatever url - * this function returns. - * Afterwards, you can redirect back to portfolio/add.php?postcontrol=1 - * and {@link post_control} is called before the rest of the processing - * for the stage is done - * - * @param int stage to steal control *before* (see constants PARAM_STAGE_*} - * - * @return boolean or string url - */ + * If at any point the caller wants to steal control, + * it can, by returning something that isn't false + * in this function + * The controller will redirect to whatever url + * this function returns. + * Afterwards, you can redirect back to portfolio/add.php?postcontrol=1 + * and {@see post_control} is called before the rest of the processing + * for the stage is done, + * + * @param int $stage to steal control *before* (see constants PARAM_STAGE_*} + * @return bool + */ public function steal_control($stage) { return false; } /** - * after a plugin has elected to steal control, - * and control returns to portfolio/add.php|postcontrol=1, - * this function is called, and passed the stage that was stolen control from - * and the request (get and post but not cookie) parameters - * this is useful for external systems that need to redirect the user back - * with some extra data in the url (like auth tokens etc) - * for an example implementation, see boxnet portfolio plugin. - * - * @param int $stage the stage before control was stolen - * @param array $params a merge of $_GET and $_POST - * - */ - + * After a plugin has elected to steal control, + * and control returns to portfolio/add.php|postcontrol=1, + * this function is called, and passed the stage that was stolen control from + * and the request (get and post but not cookie) parameters. + * This is useful for external systems that need to redirect the user back + * with some extra data in the url (like auth tokens etc) + * for an example implementation, see boxnet portfolio plugin. + * + * @param int $stage the stage before control was stolen + * @param array $params a merge of $_GET and $_POST + */ public function post_control($stage, $params) { } /** - * this function creates a new instance of a plugin - * saves it in the database, saves the config - * and returns it. - * you shouldn't need to override it - * unless you're doing something really funky - * - * @param string $plugin portfolio plugin to create - * @param string $name name of new instance - * @param array $config what the admin config form returned - * - * @return object subclass of portfolio_plugin_base - */ + * This function creates a new instance of a plugin + * saves it in the database, saves the config + * and returns it. + * You shouldn't need to override it + * unless you're doing something really funky + * + * @param string $plugin portfolio plugin to create + * @param string $name name of new instance + * @param array $config what the admin config form returned + * @return object subclass of portfolio_plugin_base + */ public static function create_instance($plugin, $name, $config) { global $DB, $CFG; $new = (object)array( @@ -475,15 +434,14 @@ abstract class portfolio_plugin_base { } /** - * construct a plugin instance - * subclasses should not need to override this unless they're doing something special - * and should call parent::__construct afterwards - * - * @param int $instanceid id of plugin instance to construct - * @param mixed $record stdclass object or named array - use this i you already have the record to avoid another query - * - * @return object subclass of portfolio_plugin_base - */ + * Construct a plugin instance. + * Subclasses should not need to override this unless they're doing something special + * and should call parent::__construct afterwards. + * + * @param int $instanceid id of plugin instance to construct + * @param mixed $record stdclass object or named array - use this if you already have the record to avoid another query + * @return portfolio_plugin_base + */ public function __construct($instanceid, $record=null) { global $DB; if (!$record) { @@ -507,50 +465,50 @@ abstract class portfolio_plugin_base { } /** - * called after __construct - allows plugins to perform initialisation tasks + * Called after __construct - allows plugins to perform initialisation tasks * without having to override the constructor. */ protected function init() { } /** - * a list of fields that can be configured per instance. - * this is used for the save handlers of the config form - * and as checks in set_config and get_config - * - * @return array array of strings (config item names) - */ + * A list of fields that can be configured per instance. + * This is used for the save handlers of the config form + * and as checks in set_config and get_config. + * + * @return array array of strings (config item names) + */ public static function get_allowed_config() { return array(); } /** - * a list of fields that can be configured by the user. - * this is used for the save handlers in the config form - * and as checks in set_user_config and get_user_config. - * - * @return array array of strings (config field names) - */ + * A list of fields that can be configured by the user. + * This is used for the save handlers in the config form + * and as checks in set_user_config and get_user_config. + * + * @return array array of strings (config field names) + */ public function get_allowed_user_config() { return array(); } /** - * a list of fields that can be configured by the user. - * this is used for the save handlers in the config form - * and as checks in set_export_config and get_export_config. - * - * @return array array of strings (config field names) - */ + * A list of fields that can be configured by the user. + * This is used for the save handlers in the config form + * and as checks in set_export_config and get_export_config. + * + * @return array array of strings (config field names) + */ public function get_allowed_export_config() { return array(); } /** - * saves (or updates) the config stored in portfolio_instance_config. - * you shouldn't need to override this unless you're doing something funky. - * - * @param array $config array of config items. - */ + * Saves (or updates) the config stored in portfolio_instance_config. + * You shouldn't need to override this unless you're doing something funky. + * + * @param array $config array of config items. + */ public final function set_config($config) { global $DB; foreach ($config as $key => $value) { @@ -577,12 +535,11 @@ abstract class portfolio_plugin_base { } /** - * gets the value of a particular config item - * - * @param string $key key to fetch - * - * @return string the corresponding value - */ + * Gets the value of a particular config item + * + * @param string $key key to fetch + * @return null|mixed the corresponding value + */ public final function get_config($key) { if (!in_array($key, $this->get_allowed_config())) { $a = (object)array('property' => $key, 'class' => get_class($this)); @@ -595,14 +552,13 @@ abstract class portfolio_plugin_base { } /** - * get the value of a config item for a particular user - * - * @param string $key key to fetch - * @param integer $userid id of user (defaults to current) - * - * @return string the corresponding value - * - */ + * Get the value of a config item for a particular user. + * + * @param string $key key to fetch + * @param int $userid id of user (defaults to current) + * @return string the corresponding value + * + */ public final function get_user_config($key, $userid=0) { global $DB; @@ -630,13 +586,12 @@ abstract class portfolio_plugin_base { } /** - * - * sets config options for a given user - * - * @param mixed $config array or stdclass containing key/value pairs to set - * @param integer $userid userid to set config for (defaults to current) - * - */ + * Sets config options for a given user. + * + * @param array $config array containing key/value pairs to set + * @param int $userid userid to set config for (defaults to current) + * + */ public final function set_user_config($config, $userid=0) { global $DB; @@ -665,11 +620,13 @@ abstract class portfolio_plugin_base { } /** - * generic getter for properties belonging to this instance - * outside the subclasses - * like name, visible etc. - * - */ + * Generic getter for properties belonging to this instance + * outside the subclasses + * like name, visible etc. + * + * @param string $field property name + * @return array|string|int|boolean value of the field + */ public final function get($field) { if (property_exists($this, $field)) { return $this->{$field}; @@ -679,11 +636,14 @@ abstract class portfolio_plugin_base { } /** - * generic setter for properties belonging to this instance - * outside the subclass - * like name, visible, etc. - * - */ + * Generic setter for properties belonging to this instance + * outside the subclass + * like name, visible, etc. + * + * @param string $field property's name + * @param string $value property's value + * @return bool + */ public final function set($field, $value) { if (property_exists($this, $field)) { $this->{$field} =& $value; @@ -699,11 +659,13 @@ abstract class portfolio_plugin_base { } /** - * saves stuff that's been stored in the object to the database - * you shouldn't need to override this - * unless you're doing something really funky. - * and if so, call parent::save when you're done. - */ + * Saves stuff that's been stored in the object to the database. + * You shouldn't need to override this + * unless you're doing something really funky. + * and if so, call parent::save when you're done. + * + * @return bool + */ public function save() { global $DB; if (!$this->dirty) { @@ -719,10 +681,12 @@ abstract class portfolio_plugin_base { } /** - * deletes everything from the database about this plugin instance. - * you shouldn't need to override this unless you're storing stuff - * in your own tables. and if so, call parent::delete when you're done. - */ + * Deletes everything from the database about this plugin instance. + * You shouldn't need to override this unless you're storing stuff + * in your own tables. and if so, call parent::delete when you're done. + * + * @return bool + */ public function delete() { global $DB; $DB->delete_records('portfolio_instance_config', array('instance' => $this->get('id'))); @@ -734,91 +698,114 @@ abstract class portfolio_plugin_base { } /** - * perform any required cleanup functions - */ + * Perform any required cleanup functions + * + * @return bool + */ public function cleanup() { return true; } /** - * whether this plugin supports multiple exports in the same session + * Whether this plugin supports multiple exports in the same session * most plugins should handle this, but some that require a redirect for authentication * and then don't support dynamically constructed urls to return to (eg box.net) * need to override this to return false. - * this means that moodle will prevent multiple exports of this *type* of plugin + * This means that moodle will prevent multiple exports of this *type* of plugin * occurring in the same session. * - * @return boolean + * @return bool */ public static function allows_multiple_exports() { return true; } /** - * return a string to put at the header summarising this export - * by default, just the plugin instance name - * - * @return string - */ + * Return a string to put at the header summarising this export + * by default, just the plugin instance name + * + * @return string + */ public function heading_summary() { return get_string('exportingcontentto', 'portfolio', $this->name); } } /** -* class to inherit from for 'push' type plugins -* eg those that send the file via a HTTP post or whatever -*/ + * Class to inherit from for 'push' type plugins + * Eg: those that send the file via a HTTP post or whatever + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ abstract class portfolio_plugin_push_base extends portfolio_plugin_base { + /** + * Get the capability to push + * + * @return bool + */ public function is_push() { return true; } } /** -* class to inherit from for 'pull' type plugins -* eg those that write a file and wait for the remote system to request it -* from portfolio/file.php -* if you're using this you must do $this->set('file', $file) so that it can be served. -*/ + * Class to inherit from for 'pull' type plugins. + * Eg: those that write a file and wait for the remote system to request it + * from portfolio/file.php. + * If you're using this you must do $this->set('file', $file) so that it can be served. + * + * @package core_portfolio + * @category portfolio + * @copyright 2008 Penny Leach + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ abstract class portfolio_plugin_pull_base extends portfolio_plugin_base { + /** @var stdclass single file */ protected $file; + /** + * return the enablelity to push + * + * @return bool + */ public function is_push() { return false; } /** - * the base part of the download file url to pull files from - * your plugin might need to add &foo=bar on the end - * {@see verify_file_request_params} - * - * @return string the url - */ + * The base part of the download file url to pull files from + * your plugin might need to add &foo=bar on the end + * {@see verify_file_request_params} + * + * @return string the url + */ public function get_base_file_url() { global $CFG; return $CFG->wwwroot . '/portfolio/file.php?id=' . $this->exporter->get('id'); } /** - * before sending the file when the pull is requested, verify the request parameters - * these might include a token of some sort of whatever - * - * @param array request parameters (POST wins over GET) - */ + * Before sending the file when the pull is requested, verify the request parameters. + * These might include a token of some sort of whatever + * + * @param array $params request parameters (POST wins over GET) + */ public abstract function verify_file_request_params($params); /** - * called from portfolio/file.php - * this function sends the stored file out to the browser - * the default is to just use send_stored_file, - * but other implementations might do something different - * for example, send back the file base64 encoded and encrypted - * mahara does this but in the response to an xmlrpc request - * rather than through file.php - */ + * Called from portfolio/file.php. + * This function sends the stored file out to the browser. + * The default is to just use send_stored_file, + * but other implementations might do something different, + * for example, send back the file base64 encoded and encrypted + * mahara does this but in the response to an xmlrpc request + * rather than through file.php + */ public function send_file() { $file = $this->get('file'); if (!($file instanceof stored_file)) { diff --git a/lib/portfoliolib.php b/lib/portfoliolib.php index 22f4544c4f4..dbb849830b5 100644 --- a/lib/portfoliolib.php +++ b/lib/portfoliolib.php @@ -16,17 +16,18 @@ // along with Moodle. If not, see . /** - * This file contains all global functions to do with manipulating portfolios - * everything else that is logically namespaced by class is in its own file + * This file contains all global functions to do with manipulating portfolios. + * + * Everything else that is logically namespaced by class is in its own file * in lib/portfolio/ directory. * * Major Contributors * - Penny Leach * - * @package core - * @subpackage portfolio + * @package core_portfolio + * @category portfolio * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ defined('MOODLE_INTERNAL') || die(); @@ -52,54 +53,63 @@ require_once($CFG->libdir . '/portfolio/caller.php'); /** - * use this to add a portfolio button or icon or form to a page - * + * Use this to add a portfolio button or icon or form to a page. * These class methods do not check permissions. the caller must check permissions first. * Later, during the export process, the caller class is instantiated and the check_permissions method is called * If you are exporting a single file, you should always call set_format_by_file($file) - * * This class can be used like this: * * $button = new portfolio_add_button(); * $button->set_callback_options('name_of_caller_class', array('id' => 6), '/your/mod/lib.php'); * $button->render(PORTFOLIO_ADD_FULL_FORM, get_string('addeverythingtoportfolio', 'yourmodule')); * - * * or like this: * * $button = new portfolio_add_button(array('callbackclass' => 'name_of_caller_class', 'callbackargs' => array('id' => 6), 'callbackfile' => '/your/mod/lib.php')); * $somehtml .= $button->to_html(PORTFOLIO_ADD_TEXT_LINK); * + *{@link http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page} for more information * - * See {@link http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page} for more information - * - * @package moodlecore - * @subpackage portfolio + * @package core_portfolio + * @category portfolio * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later -*/ + */ class portfolio_add_button { + /** @var string the name of the callback functions */ private $callbackclass; + + /** @var array can be an array of arguments to pass back to the callback functions (passed by reference)*/ private $callbackargs; + + /** @var string caller file */ private $callbackfile; + + /** @var array array of more specific formats (eg based on mime detection) */ private $formats; + + /** @var array array of portfolio instances */ private $instances; - private $file; // for single-file exports - private $intendedmimetype; // for writing specific types of files + + /** @var stored_file for single-file exports */ + private $file; + + /** @var string for writing specific types of files*/ + private $intendedmimetype; /** - * constructor. either pass the options here or set them using the helper methods. - * generally the code will be clearer if you use the helper methods. - * - * @param array $options keyed array of options: - * key 'callbackclass': name of the caller class (eg forum_portfolio_caller') - * key 'callbackargs': the array of callback arguments your caller class wants passed to it in the constructor - * key 'callbackfile': the file containing the class definition of your caller class. - * See set_callback_options for more information on these three. - * key 'formats': an array of PORTFOLIO_FORMATS this caller will support - * See set_formats or set_format_by_file for more information on this. - */ + * Constructor. Either pass the options here or set them using the helper methods. + * Generally the code will be clearer if you use the helper methods. + * + * @param array $options keyed array of options: + * key 'callbackclass': name of the caller class (eg forum_portfolio_caller') + * key 'callbackargs': the array of callback arguments your caller class wants passed to it in the constructor + * key 'callbackfile': the file containing the class definition of your caller class. + * See set_callback_options for more information on these three. + * key 'formats': an array of PORTFOLIO_FORMATS this caller will support + * See set_formats or set_format_by_file for more information on this. + */ public function __construct($options=null) { global $SESSION, $CFG; @@ -120,19 +130,21 @@ class portfolio_add_button { } } - /* - * @param string $class name of the class containing the callback functions - * activity modules should ALWAYS use their name_portfolio_caller - * other locations must use something unique - * @param mixed $argarray this can be an array or hash of arguments to pass - * back to the callback functions (passed by reference) - * these MUST be primatives to be added as hidden form fields. - * and the values get cleaned to PARAM_ALPHAEXT or PARAM_NUMBER or PARAM_PATH - * @param string $file this can be autodetected if it's in the same file as your caller, - * but often, the caller is a script.php and the class in a lib.php - * so you can pass it here if necessary. - * this path should be relative (ie, not include) dirroot, eg '/mod/forum/lib.php' - */ + /** + * Function to set the callback options + * + * @param string $class Name of the class containing the callback functions + * activity modules should ALWAYS use their name_portfolio_caller + * other locations must use something unique + * @param array $argarray This can be an array or hash of arguments to pass + * back to the callback functions (passed by reference) + * these MUST be primatives to be added as hidden form fields. + * and the values get cleaned to PARAM_ALPHAEXT or PARAM_NUMBER or PARAM_PATH + * @param string $file This can be autodetected if it's in the same file as your caller, + * but often, the caller is a script.php and the class in a lib.php + * so you can pass it here if necessary. + * This path should be relative (ie, not include) dirroot, eg '/mod/forum/lib.php' + */ public function set_callback_options($class, array $argarray, $file=null) { global $CFG; if (empty($file)) { @@ -161,19 +173,19 @@ class portfolio_add_button { $this->callbackargs = $argarray; } - /* - * sets the available export formats for this content - * this function will also poll the static function in the caller class - * and make sure we're not overriding a format that has nothing to do with mimetypes - * eg if you pass IMAGE here but the caller can export LEAP2A it will keep LEAP2A as well. - * see portfolio_most_specific_formats for more information - * - * @param array $formats if the calling code knows better than the static method on the calling class (base_supported_formats) - * eg, if it's going to be a single file, or if you know it's HTML, you can pass it here instead - * this is almost always the case so you should always use this. - * {@see portfolio_format_from_mimetype} for how to get the appropriate formats to pass here for uploaded files. - * or just call set_format_by_file instead - */ + /** + * Sets the available export formats for this content. + * This function will also poll the static function in the caller class + * and make sure we're not overriding a format that has nothing to do with mimetypes. + * Eg: if you pass IMAGE here but the caller can export LEAP2A it will keep LEAP2A as well. + * {@see portfolio_most_specific_formats for more information} + * + * @param array $formats if the calling code knows better than the static method on the calling class (base_supported_formats). + * Eg: if it's going to be a single file, or if you know it's HTML, you can pass it here instead. + * This is almost always the case so it should be use all the times + * {@see portfolio_format_from_mimetype} for how to get the appropriate formats to pass here for uploaded files. + * or just call set_format_by_file instead + */ public function set_formats($formats=null) { if (is_string($formats)) { $formats = array($formats); @@ -189,7 +201,7 @@ class portfolio_add_button { } /** - * reset formats to the default + * Reset formats to the default, * which is usually what base_supported_formats returns */ public function reset_formats() { @@ -198,13 +210,13 @@ class portfolio_add_button { /** - * if we already know we have exactly one file, + * If we already know we have exactly one file, * bypass set_formats and just pass the file * so we can detect the formats by mimetype. * - * @param stored_file $file file to set the format from - * @param mixed $extraformats any additional formats other than by mimetype - * eg leap2a etc + * @param stored_file $file file to set the format from + * @param array $extraformats any additional formats other than by mimetype + * eg leap2a etc */ public function set_format_by_file(stored_file $file, $extraformats=null) { $this->file = $file; @@ -218,12 +230,12 @@ class portfolio_add_button { } /** - * correllary to set_format_by_file, but this is used when we don't yet have a stored_file + * Correllary this is use to set_format_by_file, but it is also used when there is no stored_file and * when we're writing out a new type of file (like csv or pdf) * * @param string $extn the file extension we intend to generate - * @param mixed $extraformats any additional formats other than by mimetype - * eg leap2a etc + * @param array $extraformats any additional formats other than by mimetype + * eg leap2a etc */ public function set_format_by_intended_file($extn, $extraformats=null) { $mimetype = mimeinfo('type', 'something. ' . $extn); @@ -237,28 +249,29 @@ class portfolio_add_button { $this->set_formats(array_merge(array($fileformat), $extraformats)); } - /* - * echo the form/button/icon/text link to the page - * - * @param int $format format to display the button or form or icon or link. - * See constants PORTFOLIO_ADD_XXX for more info. - * optional, defaults to PORTFOLIO_ADD_FULL_FORM - * @param str $addstr string to use for the button or icon alt text or link text. - * this is whole string, not key. optional, defaults to 'Export to portfolio'; - */ + /** + * Echo the form/button/icon/text link to the page + * + * @param int $format format to display the button or form or icon or link. + * See constants PORTFOLIO_ADD_XXX for more info. + * optional, defaults to PORTFOLIO_ADD_FULL_FORM + * @param string $addstr string to use for the button or icon alt text or link text. + * this is whole string, not key. optional, defaults to 'Export to portfolio'; + */ public function render($format=null, $addstr=null) { echo $this->to_html($format, $addstr); } - /* - * returns the form/button/icon/text link as html - * - * @param int $format format to display the button or form or icon or link. - * See constants PORTFOLIO_ADD_XXX for more info. - * optional, defaults to PORTFOLIO_ADD_FULL_FORM - * @param str $addstr string to use for the button or icon alt text or link text. - * this is whole string, not key. optional, defaults to 'Add to portfolio'; - */ + /** + * Returns the form/button/icon/text link as html + * + * @param int $format format to display the button or form or icon or link. + * See constants PORTFOLIO_ADD_XXX for more info. + * Optional, defaults to PORTFOLIO_ADD_FULL_FORM + * @param string $addstr string to use for the button or icon alt text or link text. + * This is whole string, not key. optional, defaults to 'Add to portfolio'; + * @return void|string + */ public function to_html($format=null, $addstr=null) { global $CFG, $COURSE, $OUTPUT, $USER; if (!$this->is_renderable()) { @@ -366,10 +379,12 @@ class portfolio_add_button { } /** - * does some internal checks - * these are not errors, just situations - * where it's not appropriate to add the button - */ + * Perform some internal checks. + * These are not errors, just situations + * where it's not appropriate to add the button + * + * @return bool + */ private function is_renderable() { global $CFG; if (empty($CFG->enableportfolios)) { @@ -388,6 +403,7 @@ class portfolio_add_button { /** * Getter for $format property + * * @return array */ public function get_formats() { @@ -396,6 +412,7 @@ class portfolio_add_button { /** * Getter for $callbackargs property + * * @return array */ public function get_callbackargs() { @@ -404,7 +421,8 @@ class portfolio_add_button { /** * Getter for $callbackfile property - * @return array + * + * @return string */ public function get_callbackfile() { return $this->callbackfile; @@ -412,7 +430,8 @@ class portfolio_add_button { /** * Getter for $callbackclass property - * @return array + * + * @return string */ public function get_callbackclass() { return $this->callbackclass; @@ -420,18 +439,17 @@ class portfolio_add_button { } /** -* returns a drop menu with a list of available instances. -* -* @param array $instances array of portfolio plugin instance objects - the instances to put in the menu -* @param array $callerformats array of PORTFOLIO_FORMAT_XXX constants - the formats the caller supports (this is used to filter plugins) -* @param array $callbackclass the callback class name - used for debugging only for when there are no common formats -* @param mimetype $mimetype if we already know we have exactly one file, or are going to write one, pass it here to do mime filtering. -* @param string $selectname the name of the select element. Optional, defaults to instance. -* @param boolean $return whether to print or return the output. Optional, defaults to print. -* @param booealn $returnarray if returning, whether to return the HTML or the array of options. Optional, defaults to HTML. -* -* @return string the html, from inclusive. -*/ + * Returns a drop menu with a list of available instances. + * + * @param array $instances array of portfolio plugin instance objects - the instances to put in the menu + * @param array $callerformats array of PORTFOLIO_FORMAT_XXX constants - the formats the caller supports (this is used to filter plugins) + * @param string $callbackclass the callback class name - used for debugging only for when there are no common formats + * @param string $mimetype if we already know we have exactly one file, or are going to write one, pass it here to do mime filtering. + * @param string $selectname the name of the select element. Optional, defaults to instance. + * @param bool $return whether to print or return the output. Optional, defaults to print. + * @param bool $returnarray if returning, whether to return the HTML or the array of options. Optional, defaults to HTML. + * @return void|array|string the html, from inclusive. + */ function portfolio_instance_select($instances, $callerformats, $callbackclass, $mimetype=null, $selectname='instance', $return=false, $returnarray=false) { global $CFG, $USER; @@ -489,15 +507,13 @@ function portfolio_instance_select($instances, $callerformats, $callbackclass, $ } /** -* return all portfolio instances -* -* @todo check capabilities here - see MDL-15768 -* -* @param boolean visibleonly Don't include hidden instances. Defaults to true and will be overridden to true if the next parameter is true -* @param boolean useronly Check the visibility preferences and permissions of the logged in user. Defaults to true. -* -* @return array of portfolio instances (full objects, not just database records) -*/ + * Return all portfolio instances + * + * @todo MDL-15768 - check capabilities here + * @param bool $visibleonly Don't include hidden instances. Defaults to true and will be overridden to true if the next parameter is true + * @param bool $useronly Check the visibility preferences and permissions of the logged in user. Defaults to true. + * @return array of portfolio instances (full objects, not just database records) + */ function portfolio_instances($visibleonly=true, $useronly=true) { global $DB, $USER; @@ -526,14 +542,13 @@ function portfolio_instances($visibleonly=true, $useronly=true) { } /** -* Supported formats currently in use. -* -* Canonical place for a list of all formats -* that portfolio plugins and callers -* can use for exporting content -* -* @return keyed array of all the available export formats (constant => classname) -*/ + * Supported formats currently in use. + * Canonical place for a list of all formats + * that portfolio plugins and callers + * can use for exporting content + * + * @return array keyed array of all the available export formats (constant => classname) + */ function portfolio_supported_formats() { return array( PORTFOLIO_FORMAT_FILE => 'portfolio_format_file', @@ -553,19 +568,17 @@ function portfolio_supported_formats() { } /** -* Deduce export format from file mimetype -* -* This function returns the revelant portfolio export format -* which is used to determine which portfolio plugins can be used -* for exporting this content -* according to the given mime type -* this only works when exporting exactly one file, or generating a new one -* (like a pdf or csv export) -* -* @param string $mimetype (usually $file->get_mimetype()) -* -* @return string the format constant (see PORTFOLIO_FORMAT_XXX constants) -*/ + * Deduce export format from file mimetype + * This function returns the revelant portfolio export format + * which is used to determine which portfolio plugins can be used + * for exporting this content + * according to the given mime type + * this only works when exporting exactly one file, or generating a new one + * (like a pdf or csv export) + * + * @param string $mimetype (usually $file->get_mimetype()) + * @return string the format constant (see PORTFOLIO_FORMAT_XXX constants) + */ function portfolio_format_from_mimetype($mimetype) { global $CFG; static $alreadymatched; @@ -593,15 +606,15 @@ function portfolio_format_from_mimetype($mimetype) { } /** -* Intersection of plugin formats and caller formats -* -* Walks both the caller formats and portfolio plugin formats -* and looks for matches (walking the hierarchy as well) -* and returns the intersection -* -* @param array $callerformats formats the caller supports -* @param array $pluginformats formats the portfolio plugin supports -*/ + * Intersection of plugin formats and caller formats. + * Walks both the caller formats and portfolio plugin formats + * and looks for matches (walking the hierarchy as well) + * and returns the intersection + * + * @param array $callerformats formats the caller supports + * @param array $pluginformats formats the portfolio plugin supports + * @return array + */ function portfolio_supported_formats_intersect($callerformats, $pluginformats) { global $CFG; $allformats = portfolio_supported_formats(); @@ -632,10 +645,9 @@ function portfolio_supported_formats_intersect($callerformats, $pluginformats) { } /** - * tiny helper to figure out whether a portfolio format is abstract + * Tiny helper to figure out whether a portfolio format is abstract * * @param string $format the format to test - * * @retun bool */ function portfolio_format_is_abstract($format) { @@ -657,17 +669,16 @@ function portfolio_format_is_abstract($format) { } /** -* return the combination of the two arrays of formats with duplicates in terms of specificity removed -* and also removes conflicting formats -* use case: a module is exporting a single file, so the general formats would be FILE and MBKP -* while the specific formats would be the specific subclass of FILE based on mime (say IMAGE) -* and this function would return IMAGE and MBKP -* -* @param array $specificformats array of more specific formats (eg based on mime detection) -* @param array $generalformats array of more general formats (usually more supported) -* -* @return array merged formats with dups removed -*/ + * Return the combination of the two arrays of formats with duplicates in terms of specificity removed + * and also removes conflicting formats. + * Use case: a module is exporting a single file, so the general formats would be FILE and MBKP + * while the specific formats would be the specific subclass of FILE based on mime (say IMAGE) + * and this function would return IMAGE and MBKP + * + * @param array $specificformats array of more specific formats (eg based on mime detection) + * @param array $generalformats array of more general formats (usually more supported) + * @return array merged formats with dups removed + */ function portfolio_most_specific_formats($specificformats, $generalformats) { global $CFG; $allformats = portfolio_supported_formats(); @@ -729,12 +740,11 @@ function portfolio_most_specific_formats($specificformats, $generalformats) { } /** -* helper function to return a format object from the constant -* -* @param string $name the constant PORTFOLIO_FORMAT_XXX -* -* @return portfolio_format object -*/ + * Helper function to return a format object from the constant + * + * @param string $name the constant PORTFOLIO_FORMAT_XXX + * @return portfolio_format + */ function portfolio_format_object($name) { global $CFG; require_once($CFG->libdir . '/portfolio/formats.php'); @@ -743,15 +753,14 @@ function portfolio_format_object($name) { } /** -* helper function to return an instance of a plugin (with config loaded) -* -* @param int $instance id of instance -* @param array $record database row that corresponds to this instance -* this is passed to avoid unnecessary lookups -* Optional, and the record will be retrieved if null. -* -* @return subclass of portfolio_plugin_base -*/ + * Helper function to return an instance of a plugin (with config loaded) + * + * @param int $instanceid id of instance + * @param object $record database row that corresponds to this instance + * this is passed to avoid unnecessary lookups + * Optional, and the record will be retrieved if null. + * @return object of portfolio_plugin_XXX + */ function portfolio_instance($instanceid, $record=null) { global $DB, $CFG; @@ -769,15 +778,15 @@ function portfolio_instance($instanceid, $record=null) { } /** -* Helper function to call a static function on a portfolio plugin class -* -* This will figure out the classname and require the right file and call the function. -* you can send a variable number of arguments to this function after the first two -* and they will be passed on to the function you wish to call. -* -* @param string $plugin name of plugin -* @param string $function function to call -*/ + * Helper function to call a static function on a portfolio plugin class. + * This will figure out the classname and require the right file and call the function. + * You can send a variable number of arguments to this function after the first two + * and they will be passed on to the function you wish to call. + * + * @param string $plugin name of plugin + * @param string $function function to call + * @return mixed + */ function portfolio_static_function($plugin, $function) { global $CFG; @@ -804,13 +813,11 @@ function portfolio_static_function($plugin, $function) { } /** -* helper function to check all the plugins for sanity and set any insane ones to invisible. -* -* @param array $plugins to check (if null, defaults to all) -* one string will work too for a single plugin. -* -* @return array array of insane instances (keys= id, values = reasons (keys for plugin lang) -*/ + * Helper function to check all the plugins for sanity and set any insane ones to invisible. + * + * @param array $plugins array of supported plugin types + * @return array array of insane instances (keys= id, values = reasons (keys for plugin lang) + */ function portfolio_plugin_sanity_check($plugins=null) { global $DB; if (is_string($plugins)) { @@ -836,13 +843,11 @@ function portfolio_plugin_sanity_check($plugins=null) { } /** -* helper function to check all the instances for sanity and set any insane ones to invisible. -* -* @param array $instances to check (if null, defaults to all) -* one instance or id will work too -* -* @return array array of insane instances (keys= id, values = reasons (keys for plugin lang) -*/ + * Helper function to check all the instances for sanity and set any insane ones to invisible. + * + * @param array $instances array of plugin instances + * @return array array of insane instances (keys= id, values = reasons (keys for plugin lang) + */ function portfolio_instance_sanity_check($instances=null) { global $DB; if (empty($instances)) { @@ -877,12 +882,13 @@ function portfolio_instance_sanity_check($instances=null) { } /** -* helper function to display a table of plugins (or instances) and reasons for disabling -* -* @param array $insane array of insane plugins (key = plugin (or instance id), value = reason) -* @param array $instances if reporting instances rather than whole plugins, pass the array (key = id, value = object) here -* -*/ + * Helper function to display a table of plugins (or instances) and reasons for disabling + * + * @param array $insane array of portfolio plugin + * @param array $instances if reporting instances rather than whole plugins, pass the array (key = id, value = object) here + * @param bool $return option to deliver the report in html format or print it out directly to the page. + * @return void|string of portfolio report in html table format + */ function portfolio_report_insane($insane, $instances=false, $return=false) { global $OUTPUT; if (empty($insane)) { @@ -924,8 +930,11 @@ function portfolio_report_insane($insane, $instances=false, $return=false) { /** -* event handler for the portfolio_send event -*/ + * Event handler for the portfolio_send event + * + * @param int $eventdata event id + * @return bool + */ function portfolio_handle_event($eventdata) { global $CFG; @@ -939,11 +948,11 @@ function portfolio_handle_event($eventdata) { } /** -* main portfolio cronjob -* currently just cleans up expired transfer records. -* -* @todo add hooks in the plugins - either per instance or per plugin -*/ + * Main portfolio cronjob. + * Currently just cleans up expired transfer records. + * + * @todo - MDL-15997 - Add hooks in the plugins - either per instance or per plugin + */ function portfolio_cron() { global $DB, $CFG; @@ -961,29 +970,24 @@ function portfolio_cron() { } /** - * helper function to rethrow a caught portfolio_exception as an export exception - * - * used because when a portfolio_export exception is thrown the export is cancelled - * + * Helper function to rethrow a caught portfolio_exception as an export exception. + * Used because when a portfolio_export exception is thrown the export is cancelled * throws portfolio_export_exceptiog * * @param portfolio_exporter $exporter current exporter object - * @param exception $exception exception to rethrow - * - * @return void + * @param object $exception exception to rethrow */ function portfolio_export_rethrow_exception($exporter, $exception) { throw new portfolio_export_exception($exporter, $exception->errorcode, $exception->module, $exception->link, $exception->a); } /** -* try and determine expected_time for purely file based exports -* or exports that might include large file attachments. -* - * @global object -* @param mixed $totest - either an array of stored_file objects or a single stored_file object -* @return constant PORTFOLIO_TIME_XXX -*/ + * Try and determine expected_time for purely file based exports + * or exports that might include large file attachments. + * + * @param stored_file|array $totest - either an array of stored_file objects or a single stored_file object + * @return string PORTFOLIO_TIME_XXX + */ function portfolio_expected_time_file($totest) { global $CFG; if ($totest instanceof stored_file) { @@ -1023,9 +1027,11 @@ function portfolio_expected_time_file($totest) { /** -* the default filesizes and threshold information for file based transfers -* this shouldn't need to be used outside the admin pages and the portfolio code -*/ + * The default filesizes and threshold information for file based transfers. + * This shouldn't need to be used outside the admin pages and the portfolio code + * + * @return array + */ function portfolio_filesize_info() { $filesizes = array(); $sizelist = array(10240, 51200, 102400, 512000, 1048576, 2097152, 5242880, 10485760, 20971520, 52428800); @@ -1040,13 +1046,12 @@ function portfolio_filesize_info() { } /** -* try and determine expected_time for purely database based exports -* or exports that might include large parts of a database -* - * @global object -* @param integer $recordcount - number of records trying to export -* @return constant PORTFOLIO_TIME_XXX -*/ + * Try and determine expected_time for purely database based exports + * or exports that might include large parts of a database. + * + * @param int $recordcount number of records trying to export + * @return string PORTFOLIO_TIME_XXX + */ function portfolio_expected_time_db($recordcount) { global $CFG; @@ -1065,7 +1070,10 @@ function portfolio_expected_time_db($recordcount) { } /** - * @global object + * Function to send portfolio report to admins + * + * @param array $insane array of insane plugins + * @param array $instances (optional) if reporting instances rather than whole plugins */ function portfolio_insane_notify_admins($insane, $instances=false) { @@ -1121,6 +1129,12 @@ function portfolio_insane_notify_admins($insane, $instances=false) { } } +/** + * Setup page export + * + * @param moodle_page $PAGE global variable from page object + * @param portfolio_caller_base $caller plugin type caller + */ function portfolio_export_pagesetup($PAGE, $caller) { // set up the context so that build_navigation works nice $caller->set_context($PAGE); @@ -1136,6 +1150,13 @@ function portfolio_export_pagesetup($PAGE, $caller) { $PAGE->navbar->add(get_string('exporting', 'portfolio')); } +/** + * Get export type id + * + * @param string $type plugin type + * @param int $userid the user to check for + * @return mixed|bool + */ function portfolio_export_type_to_id($type, $userid) { global $DB; $sql = 'SELECT t.id FROM {portfolio_tempdata} t JOIN {portfolio_instance} i ON t.instance = i.id WHERE t.userid = ? AND i.plugin = ?'; @@ -1143,14 +1164,13 @@ function portfolio_export_type_to_id($type, $userid) { } /** - * return a list of current exports for the given user - * this will not go through and call rewaken_object, because it's heavy - * it's really just used to figure out what exports are currently happening. - * this is useful for plugins that don't support multiple exports per session + * Return a list of current exports for the given user. + * This will not go through and call rewaken_object, because it's heavy. + * It's really just used to figure out what exports are currently happening. + * This is useful for plugins that don't support multiple exports per session * - * @param int $userid the user to check for + * @param int $userid the user to check for * @param string $type (optional) the portfolio plugin to filter by - * * @return array */ function portfolio_existing_exports($userid, $type=null) { @@ -1168,6 +1188,9 @@ function portfolio_existing_exports($userid, $type=null) { * Return an array of existing exports by type for a given user. * This is much more lightweight than {@see existing_exports} because it only returns the types, rather than the whole serialised data * so can be used for checking availability of multiple plugins at the same time. + * + * @param int $userid the user to check for + * @return array */ function portfolio_existing_exports_by_plugin($userid) { global $DB; @@ -1177,8 +1200,7 @@ function portfolio_existing_exports_by_plugin($userid) { } /** - * Return default common options for {@link format_text()} when preparing a content to be exported - * + * Return default common options for {@link format_text()} when preparing a content to be exported. * It is important not to apply filters and not to clean the HTML in format_text() * * @return stdClass @@ -1198,6 +1220,15 @@ function portfolio_format_text_options() { /** * callback function from {@link portfolio_rewrite_pluginfile_urls} * looks through preg_replace matches and replaces content with whatever the active portfolio export format says + * + * @param int $contextid module context id + * @param string $component module name (eg:mod_assignment) + * @param string $filearea normal file_area arguments + * @param int $itemid component item id + * @param portfolio_format $format exporter format type + * @param array $options extra options to pass through to the file_output function in the format (optional) + * @param array $matches internal matching + * @return object|array|string */ function portfolio_rewrite_pluginfile_url_callback($contextid, $component, $filearea, $itemid, $format, $options, $matches) { $matches = $matches[0]; // no internal matching @@ -1239,19 +1270,18 @@ function portfolio_rewrite_pluginfile_url_callback($contextid, $component, $file /** - * go through all the @@PLUGINFILE@@ matches in some text, + * Go through all the @@PLUGINFILE@@ matches in some text, * extract the file information and pass it back to the portfolio export format * to regenerate the html to output * - * @param string $text the text to search through - * @param int $contextid normal file_area arguments - * @param string $component - * @param string $filearea normal file_area arguments - * @param int $itemid normal file_area arguments - * @param portfolio_format $format the portfolio export format - * @param array $options extra options to pass through to the file_output function in the format (optional) - * - * @return string + * @param string $text the text to search through + * @param int $contextid normal file_area arguments + * @param string $component module name + * @param string $filearea normal file_area arguments + * @param int $itemid normal file_area arguments + * @param portfolio_format $format the portfolio export format + * @param array $options additional options to be included in the plugin file url (optional) + * @return mixed */ function portfolio_rewrite_pluginfile_urls($text, $contextid, $component, $filearea, $itemid, $format, $options=null) { $pattern = '/(<[^<]*?="@@PLUGINFILE@@\/[^>]*?(?:\/>|>.*?<\/[^>]*?>))/'; diff --git a/portfolio/add.php b/portfolio/add.php index 696c32afa2d..b3c3982df0a 100644 --- a/portfolio/add.php +++ b/portfolio/add.php @@ -1,29 +1,26 @@ . + /** - * Moodle - Modular Object-Oriented Dynamic Learning Environment - * http://moodle.org - * Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program. If not, see . - * - * @package moodle - * @subpackage portfolio - * @author Penny Leach - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL - * @copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * * This file is the main controller to do with the portfolio export wizard. + * + * @package core_portfolio + * @copyright 2008 Penny Leach , + * Martin Dougiamas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL */ require_once(dirname(dirname(__FILE__)) . '/config.php'); diff --git a/portfolio/file.php b/portfolio/file.php index b9dbd5e93c7..dc805854db9 100644 --- a/portfolio/file.php +++ b/portfolio/file.php @@ -1,31 +1,28 @@ . + /** - * Moodle - Modular Object-Oriented Dynamic Learning Environment - * http://moodle.org - * Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program. If not, see . - * - * @package moodle - * @subpackage portfolio - * @author Penny Leach - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL - * @copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com - * * For portfolio plugins that are 'pull' - ie, send the request and then wait * for the remote system to request the file for moodle, * this is the script that serves up the export file to them. + * + * @package core_portfolio + * @copyright 2008 Penny Leach , + * Martin Dougiamas + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ require_once(dirname(dirname(__FILE__)) . '/config.php');