MDL-15911: support in odslib to write the file out rather than just send it
[moodle.git] / lib / portfoliolib.php
CommitLineData
67a87e7d 1<?php
67a87e7d 2/**
3* this file contains:
4* {@link portfolio_add_button} -entry point for callers
5* {@link class portfolio_plugin_base} - class plugins extend
6* {@link class portfolio_caller_base} - class callers extend
7* {@link class portfolio_admin_form} - base moodleform class for plugin administration
8* {@link class portfolio_user_form} - base moodleform class for plugin instance user config
9* {@link class portfolio_export_form} - base moodleform class for during-export configuration (eg metadata)
10* {@link class portfolio_exporter} - class used during export process
11*
12* and some helper functions:
13* {@link portfolio_instances - returns an array of all configured instances
14* {@link portfolio_instance - returns an instance of the right class given an id
15* {@link portfolio_instance_select} - returns a drop menu of available instances
16* {@link portfolio_static_function - requires the file, and calls a static function on the given class
17" {@link portfolio_plugin_sanity_check - polls given (or all) portfolio_plugins for sanity and disables insane ones
18" {@link portfolio_instance_sanity_check - polls given (or all) portfolio instances for sanity and disables insane ones
19* {@link portfolio_report_instane} - returns a table of insane plugins and the reasons (used for plugins or instances thereof)
20* {@link portfolio_supported_formats - returns array of all available formats for plugins and callers to use
21* {@link portfolio_handle_event} - event handler for queued transfers that get triggered on cron
22*
23*/
24require_once ($CFG->libdir.'/formslib.php');
25
26// **** EXPORT STAGE CONSTANTS **** //
27
28/**
29* display a form to the user
30* this one might not be used if neither
31* the plugin, or the caller has any config.
32*/
33define('PORTFOLIO_STAGE_CONFIG', 1);
34
35/**
36* summarise the form and ask for confirmation
37* if we skipped PORTFOLIO_STAGE_CONFIG,
38* just confirm the send.
39*/
40define('PORTFOLIO_STAGE_CONFIRM', 2);
41
42/**
43* either queue the event and skip to PORTFOLIO_STAGE_FINISHED
44* or continue to PORTFOLIO_STAGE_PACKAGE
45*/
46
47define('PORTFOLIO_STAGE_QUEUEORWAIT', 3);
48
49/**
50* package up the various bits
51* during this stage both the caller
52* and the plugin get their package methods called
53*/
54define('PORTFOLIO_STAGE_PACKAGE', 4);
55
56/*
57* the portfolio plugin must send the file
58*/
59define('PORTFOLIO_STAGE_SEND', 5);
60
61/**
62* cleanup the temporary area
63*/
64define('PORTFOLIO_STAGE_CLEANUP', 6);
65
66/**
67* display the "finished notification"
68*/
69define('PORTFOLIO_STAGE_FINISHED', 7);
70
71
72
73// **** EXPORT FORMAT CONSTANTS **** //
74// these should always correspond to a string
75// in the portfolio module, called format_{$value}
76// **** **** //
77
67a87e7d 78
79/**
80* file - the most basic fallback format.
81* this should always be supported
82* in remote system.s
83*/
84define('PORTFOLIO_FORMAT_FILE', 'file');
85
86/**
87* moodle backup - the plugin needs to be able to write a complete backup
88* the caller need to be able to export the particular XML bits to insert
89* into moodle.xml (?and the file bits if necessary)
90*/
91define('PORTFOLIO_FORMAT_MBKP', 'mbkp');
92
93
94// **** EXPORT TIME LEVELS **** //
95// these should correspond to a string
96// in the portfolio module, called time_{$value}
97
98/**
99* no delay. don't even offer the user the option
100* of not waiting for the transfer
101*/
102define('PORTFOLIO_TIME_LOW', 'low');
103
104/**
105* a small delay. user can still easily opt to
106* watch this transfer and wait.
107*/
108define('PORTFOLIO_TIME_MODERATE', 'moderate');
109
110/**
111* slow. the user really should not be given the option
112* to choose this.
113*/
114define('PORTFOLIO_TIME_HIGH', 'high');
115
116
117/**
118* entry point to add an 'add to portfolio' button somewhere in moodle
119* this function does not check permissions. the caller must check permissions first.
120* later, during the export process, the caller class is instantiated and the check_permissions method is called
121* but not in this function.
122*
123* @param string $callbackclass name of the class containing the callback functions
124* activity modules should ALWAYS use their name_portfolio_caller
125* other locations must use something unique
126* @param mixed $callbackargs this can be an array or hash of arguments to pass
127* back to the callback functions (passed by reference)
128* these MUST be primatives to be added as hidden form fields.
129* and the values get cleaned to PARAM_ALPHAEXT or PARAM_NUMBER or PARAM_PATH
ed1fcf79 130* @param string $callbackfile this can be autodetected if it's in the same file as your caller,
131* but more often, the caller is a script.php and the class in a lib.php
132* so you can pass it here if necessary.
133* this path should be relative (ie, not include) dirroot
67a87e7d 134* @param boolean $fullform either display the fullform with the dropmenu of available instances
135* or just a small icon (which will trigger instance selection in a new screen)
136* optional, defaults to true.
137* @param boolean $return whether to echo or return content (optional defaults to false (echo)
138*/
ed1fcf79 139function portfolio_add_button($callbackclass, $callbackargs, $callbackfile=null, $fullform=true, $return=false) {
67a87e7d 140
141 global $SESSION, $CFG, $COURSE, $USER;
142
a239f01e 143 if (empty($CFG->portfolioenabled)) {
144 return;
145 }
146
67a87e7d 147 if (!$instances = portfolio_instances()) {
148 return;
149 }
150
ed1fcf79 151 if (empty($callbackfile)) {
152 $backtrace = debug_backtrace();
153 if (!array_key_exists(0, $backtrace) || !array_key_exists('file', $backtrace[0]) || !is_readable($backtrace[0]['file'])) {
154 debugging(get_string('nocallbackfile', 'portfolio'));
155 return;
156 }
157
158 $callbackfile = substr($backtrace[0]['file'], strlen($CFG->dirroot));
159 } else {
160 if (!is_readable($CFG->dirroot . $callbackfile)) {
161 debugging(get_string('nocallbackfile', 'portfolio'));
162 return;
163 }
67a87e7d 164 }
165
67a87e7d 166 require_once($CFG->dirroot . $callbackfile);
167
168 $callersupports = call_user_func(array($callbackclass, 'supported_formats'));
169
170 if (isset($SESSION->portfolio)) {
171 return portfolio_exporter::raise_error('alreadyexporting', 'portfolio');
172 }
173
174 $output = '<form method="post" action="' . $CFG->wwwroot . '/portfolio/add.php" id="portfolio-add-button">' . "\n";
175 foreach ($callbackargs as $key => $value) {
176 if (!empty($value) && !is_string($value) && !is_numeric($value)) {
177 $a->key = $key;
178 $a->value = print_r($value, true);
179 debugging(get_string('nonprimative', 'portfolio', $a));
180 return;
181 }
182 $output .= "\n" . '<input type="hidden" name="ca_' . $key . '" value="' . $value . '" />';
183 }
184 $output .= "\n" . '<input type="hidden" name="callbackfile" value="' . $callbackfile . '" />';
185 $output .= "\n" . '<input type="hidden" name="callbackclass" value="' . $callbackclass . '" />';
186 $output .= "\n" . '<input type="hidden" name="course" value="' . (!empty($COURSE) ? $COURSE->id : 0) . '" />';
187 $selectoutput = '';
188 if (count($instances) == 1) {
189 $instance = array_shift($instances);
190 if (count(array_intersect($callersupports, $instance->supported_formats())) == 0) {
191 // bail. no common formats.
192 debugging(get_string('nocommonformats', 'portfolio', $callbackclass));
193 return;
194 }
195 if ($error = portfolio_instance_sanity_check($instance)) {
196 // bail, plugin is misconfigured
197 debugging(get_string('instancemisconfigured', 'portfolio', get_string($error[$instance->get('id')], 'portfolio_' . $instance->get('plugin'))));
198 return;
199 }
200 $output .= "\n" . '<input type="hidden" name="instance" value="' . $instance->get('id') . '" />';
201 }
202 else {
203 $selectoutput = portfolio_instance_select($instances, $callersupports, $callbackclass);
204 }
205
206 if ($fullform) {
207 $output .= $selectoutput;
208 $output .= "\n" . '<input type="submit" value="' . get_string('addtoportfolio', 'portfolio') .'" />';
209 } else {
210 $output .= "\n" . '<input type="image" src="' . $CFG->pixpath . '/t/portfolio.gif" alt=' . get_string('addtoportfolio', 'portfolio') .'" />';
211 //@todo replace this with a little icon
212 }
213
214 $output .= "\n" . '</form>';
215
216 if ($return) {
217 return $output;
218 } else {
219 echo $output;
220 }
221 return true;
222}
223
224/**
225* returns a drop menu with a list of available instances.
226*
227* @param array $instances the instances to put in the menu
228* @param array $callerformats the formats the caller supports
229 (this is used to filter plugins)
230* @param array $callbackclass the callback class name
231*
232* @return string the html, from <select> to </select> inclusive.
233*/
234function portfolio_instance_select($instances, $callerformats, $callbackclass) {
235 $insane = portfolio_instance_sanity_check();
236 $count = 0;
237 $selectoutput = "\n" . '<select name="instance">' . "\n";
238 foreach ($instances as $instance) {
239 if (count(array_intersect($callerformats, $instance->supported_formats())) == 0) {
240 // bail. no common formats.
241 continue;
242 }
243 if (array_key_exists($instance->get('id'), $insane)) {
244 // bail, plugin is misconfigured
245 debugging(get_string('instancemisconfigured', 'portfolio', get_string($insane[$instance->get('id')], 'portfolio_' . $instance->get('plugin'))));
246 continue;
247 }
248 $count++;
249 $selectoutput .= "\n" . '<option value="' . $instance->get('id') . '">' . $instance->get('name') . '</a>' . "\n";
250 }
251 if (empty($count)) {
252 // bail. no common formats.
253 debugging(get_string('nocommonformats', 'portfolio', $callbackclass));
254 return;
255 }
256 $selectoutput .= "\n" . "</select>\n";
257 return $selectoutput;
258}
259
260/**
261* return all portfolio instances
262*
263* @param boolean visibleonly don't include hidden instances (defaults to true and will be overridden to true if the next parameter is true)
264* @param boolean useronly check the visibility preferences and permissions of the logged in user
265* @return array of portfolio instances (full objects, not just database records)
266*/
267function portfolio_instances($visibleonly=true, $useronly=true) {
268
269 global $DB, $USER;
270
271 $values = array();
272 $sql = 'SELECT * FROM {portfolio_instance}';
273
274 if ($visibleonly || $useronly) {
275 $values[] = 1;
276 $sql .= ' WHERE visible = ?';
277 }
278 if ($useronly) {
279 $sql .= ' AND id NOT IN (
280 SELECT instance FROM {portfolio_instance_user}
281 WHERE userid = ? AND name = ? AND value = ?
282 )';
283 $values = array_merge($values, array($USER->id, 'visible', 0));
284 }
285 $sql .= ' ORDER BY name';
286
287 $instances = array();
288 foreach ($DB->get_records_sql($sql, $values) as $instance) {
a50ef3d3 289 $instances[$instance->id] = portfolio_instance($instance->id, $instance);
67a87e7d 290 }
291 // @todo check capabilities here - see MDL-15768
292 return $instances;
293}
294
295/**
296* supported formats that portfolio plugins and callers
297* can use for exporting content
298*
299* @return array of all the available export formats
300*/
301function portfolio_supported_formats() {
302 return array(
303 PORTFOLIO_FORMAT_FILE,
5071079c 304 /*PORTFOLIO_FORMAT_MBKP, */ // later
305 /*PORTFOLIO_FORMAT_PIOP, */ // also later
67a87e7d 306 );
307}
308
309/**
310* helper function to return an instance of a plugin (with config loaded)
311*
312* @param int $instance id of instance
313* @param array $record database row that corresponds to this instance
314* this is passed to avoid unnecessary lookups
315*
316* @return subclass of portfolio_plugin_base
317*/
318function portfolio_instance($instanceid, $record=null) {
319 global $DB, $CFG;
320
321 if ($record) {
322 $instance = $record;
323 } else {
324 if (!$instance = $DB->get_record('portfolio_instance', array('id' => $instanceid))) {
325 return false; // @todo throw exception?
326 }
327 }
328 require_once($CFG->dirroot . '/portfolio/type/'. $instance->plugin . '/lib.php');
329 $classname = 'portfolio_plugin_' . $instance->plugin;
330 return new $classname($instanceid, $instance);
331}
332
333/**
334* helper function to call a static function on a portfolio plugin class
335* this will figure out the classname and require the right file and call the function.
336* you can send a variable number of arguments to this function after the first two
337* and they will be passed on to the function you wish to call.
338*
339* @param string $plugin name of plugin
340* @param string $function function to call
341*/
342function portfolio_static_function($plugin, $function) {
343 global $CFG;
344
345 $pname = null;
346 if (is_object($plugin) || is_array($plugin)) {
347 $plugin = (object)$plugin;
348 $pname = $plugin->name;
349 } else {
350 $pname = $plugin;
351 }
352
353 $args = func_get_args();
354 if (count($args) <= 2) {
355 $args = array();
356 }
357 else {
358 array_shift($args);
359 array_shift($args);
360 }
361
362 require_once($CFG->dirroot . '/portfolio/type/' . $plugin . '/lib.php');
363 return call_user_func_array(array('portfolio_plugin_' . $plugin, $function), $args);
364}
365
366/**
367* helper function to check all the plugins for sanity and set any insane ones to invisible.
368*
369* @param array $plugins to check (if null, defaults to all)
370* one string will work too for a single plugin.
371*
372* @return array array of insane instances (keys= id, values = reasons (keys for plugin lang)
373*/
374function portfolio_plugin_sanity_check($plugins=null) {
375 global $DB;
376 if (is_string($plugins)) {
377 $plugins = array($plugins);
378 } else if (empty($plugins)) {
379 $plugins = get_list_of_plugins('portfolio/type');
380 }
381
382 $insane = array();
383 foreach ($plugins as $plugin) {
384 if ($result = portfolio_static_function($plugin, 'plugin_sanity_check')) {
385 $insane[$plugin] = $result;
386 }
387 }
388 if (empty($insane)) {
389 return array();
390 }
391 list($where, $params) = $DB->get_in_or_equal(array_keys($insane));
392 $where = ' plugin ' . $where;
393 $DB->set_field_select('portfolio_instance', 'visible', 0, $where, $params);
394 return $insane;
395}
396
397/**
398* helper function to check all the instances for sanity and set any insane ones to invisible.
399*
400* @param array $instances to check (if null, defaults to all)
401* one instance or id will work too
402*
403* @return array array of insane instances (keys= id, values = reasons (keys for plugin lang)
404*/
405function portfolio_instance_sanity_check($instances=null) {
406 global $DB;
407 if (empty($instances)) {
408 $instances = portfolio_instances(false);
409 } else if (!is_array($instances)) {
410 $instances = array($instances);
411 }
412
413 $insane = array();
414 foreach ($instances as $instance) {
415 if (is_object($instance) && !($instance instanceof portfolio_plugin_base)) {
416 $instance = portfolio_instance($instance->id, $instance);
417 } else if (is_numeric($instance)) {
418 $instance = portfolio_instance($instance);
419 }
420 if (!($instance instanceof portfolio_plugin_base)) {
421 debugging('something weird passed to portfolio_instance_sanity_check, not subclass or id');
422 continue;
423 }
424 if ($result = $instance->instance_sanity_check()) {
425 $insane[$instance->get('id')] = $result;
426 }
427 }
428 if (empty($insane)) {
429 return array();
430 }
431 list ($where, $params) = $DB->get_in_or_equal(array_keys($insane));
432 $where = ' id ' . $where;
433 $DB->set_field_select('portfolio_instance', 'visible', 0, $where, $params);
434 return $insane;
435}
436
437/**
438* helper function to display a table of plugins (or instances) and reasons for disabling
439*
440* @param array $insane array of insane plugins (key = plugin (or instance id), value = reason)
441* @param array $instances if reporting instances rather than whole plugins, pass the array (key = id, value = object) here
442*
443*/
a50ef3d3 444function portfolio_report_insane($insane, $instances=false, $return=false) {
67a87e7d 445 if (empty($insane)) {
446 return;
447 }
448
449 static $pluginstr;
450 if (empty($pluginstr)) {
451 $pluginstr = get_string('plugin', 'portfolio');
452 }
453 if ($instances) {
454 $headerstr = get_string('someinstancesdisabled', 'portfolio');
455 } else {
456 $headerstr = get_string('somepluginsdisabled', 'portfolio');
457 }
458
a50ef3d3 459 $output = notify($headerstr, 'notifyproblem', 'center', true);
67a87e7d 460 $table = new StdClass;
461 $table->head = array($pluginstr, '');
462 $table->data = array();
463 foreach ($insane as $plugin => $reason) {
464 if ($instances) {
465 // @todo this isn't working
466 // because it seems the new recordset object
467 // doesn't implement the key correctly.
0082ed89 468 // see MDL-15798
67a87e7d 469 $instance = $instances[$plugin];
470 $plugin = $instance->get('plugin');
471 $name = $instance->get('name');
472 } else {
473 $name = $plugin;
474 }
475 $table->data[] = array($name, get_string($reason, 'portfolio_' . $plugin));
476 }
a50ef3d3 477 $output .= print_table($table, true);
478 $output .= '<br /><br /><br />';
479
480 if ($return) {
481 return $output;
482 }
483 echo $output;
67a87e7d 484}
485
486/**
487* temporary functions until the File API settles
488* to do with moving files around
489*/
490function temp_portfolio_working_directory($unique) {
491 return make_upload_directory('temp/portfolio/export/' . $unique);
492}
493
494function temp_portfolio_usertemp_directory($userid) {
495 return make_upload_directory('userdata/' . $userid . '/temp');
496}
497
498/**
499*cleans up the working directory
500*/
501function temp_portfolio_cleanup($unique) {
502 $workdir = temp_portfolio_working_directory($unique);
503 return remove_dir($workdir);
504}
505
506
507/**
508* base class for the caller
509* places in moodle that want to display
510* the add form should subclass this for their callback.
511*/
512abstract class portfolio_caller_base {
513
514 /**
515 * stdclass object
516 * course that was active during the caller
517 */
518 protected $course;
519
520 /**
521 * named array of export config
522 * use{@link set_export_config} and {@link get_export_config} to access
523 */
524 protected $exportconfig;
525
526 /**
527 * stdclass object
528 * user currently exporting content
529 */
530 protected $user;
531
532 /**
533 * if this caller wants any additional config items
534 * they should be defined here.
535 *
536 * @param array $mform moodleform object (passed by reference) to add elements to
537 * @param object $instance subclass of portfolio_plugin_base
538 * @param integer $userid id of user exporting content
539 */
540 public function export_config_form(&$mform, $instance) {}
541
542
543 /**
544 * whether this caller wants any additional
545 * config during export (eg options or metadata)
546 *
547 * @return boolean
548 */
549 public function has_export_config() {
550 return false;
551 }
552
553 /**
554 * just like the moodle form validation function
555 * this is passed in the data array from the form
556 * and if a non empty array is returned, form processing will stop.
557 *
558 * @param array $data data from form.
559 * @return array keyvalue pairs - form element => error string
560 */
561 public function export_config_validation($data) {}
562
563 /**
564 * how long does this reasonably expect to take..
565 * should we offer the user the option to wait..
566 * this is deliberately nonstatic so it can take filesize into account
567 * the portfolio plugin can override this.
568 * (so for exmaple even if a huge file is being sent,
569 * the download portfolio plugin doesn't care )
570 *
571 * @return string (see PORTFOLIO_TIME_* constants)
572 */
573 public abstract function expected_time();
574
575 /**
576 * used for displaying the navigation during the export screens.
577 *
578 * this function must be implemented, but can really return anything.
579 * an Exporting.. string will be added on the end.
580 * @return array of $extranav and $cm
581 *
582 * to pass to build_navigation
583 *
584 */
585 public abstract function get_navigation();
586
ffcfd8a7 587 /**
588 *
589 */
590 public abstract function get_sha1();
591
67a87e7d 592 /*
593 * generic getter for properties belonging to this instance
594 * <b>outside</b> the subclasses
595 * like name, visible etc.
596 *
597 * @todo determine what to return in the error case
598 */
599 public final function get($field) {
600 if (property_exists($this, $field)) {
601 return $this->{$field};
602 }
603 return false; // @todo throw exception?
604 }
605
606 /**
607 * generic setter for properties belonging to this instance
608 * <b>outside</b> the subclass
609 * like name, visible, etc.
610 *
611 * @todo determine what to return in the error case
612 */
613 public final function set($field, $value) {
614 if (property_exists($this, $field)) {
615 $this->{$field} = $value;
616 $this->dirty = true;
617 return true;
618 }
619 return false; // @todo throw exception?
620
621 }
622
623 /**
624 * stores the config generated at export time.
625 * subclasses can retrieve values using
626 * {@link get_export_config}
627 *
628 * @param array $config formdata
629 */
630 public final function set_export_config($config) {
631 $allowed = array_merge(
ffcfd8a7 632 array('wait', 'hidewait', 'format', 'hideformat'),
67a87e7d 633 $this->get_allowed_export_config()
634 );
635 foreach ($config as $key => $value) {
636 if (!in_array($key, $allowed)) {
637 continue; // @ todo throw exception
638 }
639 $this->exportconfig[$key] = $value;
640 }
641 }
642
643 /**
644 * returns a particular export config value.
645 * subclasses shouldn't need to override this
646 *
647 * @param string key the config item to fetch
648 * @todo figure out the error cases (item not found or not allowed)
649 */
650 public final function get_export_config($key) {
651 $allowed = array_merge(
ffcfd8a7 652 array('wait', 'hidewait', 'format', 'hideformat'),
67a87e7d 653 $this->get_allowed_export_config()
654 );
655 if (!in_array($key, $allowed)) {
656 return false; // @todo throw exception?
657 }
658 if (!array_key_exists($key, $this->exportconfig)) {
659 return null; // @todo what to return|
660 }
661 return $this->exportconfig[$key];
662 }
663
664 /**
665 * Similar to the other allowed_config functions
666 * if you need export config, you must provide
667 * a list of what the fields are.
668 *
669 * even if you want to store stuff during export
670 * without displaying a form to the user,
671 * you can use this.
672 *
673 * @return array array of allowed keys
674 */
675 public function get_allowed_export_config() {
676 return array();
677 }
678
679 /**
680 * after the user submits their config
681 * they're given a confirm screen
682 * summarising what they've chosen.
683 *
684 * this function should return a table of nice strings => values
685 * of what they've chosen
686 * to be displayed in a table.
687 *
688 * @return array array of config items.
689 */
690 public function get_export_summary() {
691 return false;
692 }
693
694 /**
695 * called before the portfolio plugin gets control
696 * this function should copy all the files it wants to
697 * the temporary directory.
698 *
699 * @param string $tempdir path to tempdir to put files in
700 */
701 public abstract function prepare_package($tempdir);
702
703 /**
704 * array of formats this caller supports
705 * the intersection of what this function returns
706 * and what the selected portfolio plugin supports
707 * will be used
708 * use the constants PORTFOLIO_FORMAT_*
709 *
710 * @return array list of formats
711 */
bb63fc3e 712 public static function supported_formats() {
713 return array(PORTFOLIO_FORMAT_FILE);
714 }
67a87e7d 715
716 /**
717 * this is the "return to where you were" url
718 *
719 * @return string url
720 */
721 public abstract function get_return_url();
722
723 /**
724 * callback to do whatever capability checks required
725 * in the caller (called during the export process
726 */
727 public abstract function check_permissions();
ffcfd8a7 728
729 /**
730 * nice name to display to the user about this caller location
731 */
732 public abstract static function display_name();
67a87e7d 733}
734
5071079c 735abstract class portfolio_module_caller_base extends portfolio_caller_base {
736
737 protected $cm;
738
739 public function get_navigation() {
740 $extranav = array('name' => $this->cm->name, 'link' => $this->get_return_url());
741 return array($extranav, $this->cm);
742 }
743
744 public function get_return_url() {
745 global $CFG;
746 return $CFG->wwwroot . '/mod/' . $this->cm->modname . '/view.php?id=' . $this->cm->id;
747 }
748}
749
67a87e7d 750/**
751* the base class for portfolio plguins
752* all plugins must subclass this.
753*/
754abstract class portfolio_plugin_base {
755
756 /**
757 * boolean
758 * whether this object needs writing out to the database
759 */
760 protected $dirty;
761
762 /**
763 * integer
764 * id of instance
765 */
766 protected $id;
767
768 /**
769 * string
770 * name of instance
771 */
772 protected $name;
773
774 /**
775 * string
776 * plugin this instance belongs to
777 */
778 protected $plugin;
779
780 /**
781 * boolean
782 * whether this instance is visible or not
783 */
784 protected $visible;
785
786 /**
787 * named array
788 * admin configured config
789 * use {@link set_config} and {@get_config} to access
790 */
791 protected $config;
792
793 /**
794 *
795 * user config cache
796 * named array of named arrays
797 * keyed on userid and then on config field => value
798 * use {@link get_user_config} and {@link set_user_config} to access.
799 */
800 protected $userconfig;
801
802 /**
803 * named array
804 * export config during export
805 * use {@link get_export_config} and {@link set export_config} to access.
806 */
807 protected $exportconfig;
808
809 /**
810 * stdclass object
811 * user currently exporting data
812 */
813 protected $user;
814
815
816 /**
817 * array of formats this portfolio supports
818 * the intersection of what this function returns
819 * and what the caller supports will be used
820 * use the constants PORTFOLIO_FORMAT_*
821 *
822 * @return array list of formats
823 */
bb63fc3e 824 public static function supported_formats() {
825 return array(PORTFOLIO_FORMAT_FILE);
826 }
67a87e7d 827
828
829 /**
830 * how long does this reasonably expect to take..
831 * should we offer the user the option to wait..
832 * this is deliberately nonstatic so it can take filesize into account
833 *
834 * @param string $callertime - what the caller thinks
835 * the portfolio plugin instance
836 * is given the final say
837 * because it might be (for example) download.
838 * @return string (see PORTFOLIO_TIME_* constants)
839 */
840 public abstract function expected_time($callertime);
841
842 /**
843 * check sanity of plugin
844 * if this function returns something non empty, ALL instances of your plugin
845 * will be set to invisble and not be able to be set back until it's fixed
846 *
847 * @return mixed - string = error string KEY (must be inside plugin_$yourplugin) or 0/false if you're ok
848 */
849 public static function plugin_sanity_check() {
850 return 0;
851 }
852
853 /**
854 * check sanity of instances
855 * if this function returns something non empty, the instance will be
856 * set to invislbe and not be able to be set back until it's fixed.
857 *
858 * @return mixed - string = error string KEY (must be inside plugin_$yourplugin) or 0/false if you're ok
859 */
860 public function instance_sanity_check() {
861 return 0;
862 }
863
864 /**
865 * does this plugin need any configuration by the administrator?
866 *
867 * if you override this to return true,
868 * you <b>must</b> implement {@link} admin_config_form
869 */
870 public static function has_admin_config() {
871 return false;
872 }
873
874 /**
875 * can this plugin be configured by the user in their profile?
876 *
877 * if you override this to return true,
878 * you <b>must</b> implement {@link user_config_form
879 */
880 public function has_user_config() {
881 return false;
882 }
883
884 /**
885 * does this plugin need configuration during export time?
886 *
887 * if you override this to return true,
888 * you <b>must</b> implement {@link export_config_form}
889 */
890 public function has_export_config() {
891 return false;
892 }
893
894 /**
895 * just like the moodle form validation function
896 * this is passed in the data array from the form
897 * and if a non empty array is returned, form processing will stop.
898 *
899 * @param array $data data from form.
900 * @return array keyvalue pairs - form element => error string
901 */
902 public function export_config_validation() {}
903
904 /**
905 * just like the moodle form validation function
906 * this is passed in the data array from the form
907 * and if a non empty array is returned, form processing will stop.
908 *
909 * @param array $data data from form.
910 * @return array keyvalue pairs - form element => error string
911 */
912 public function user_config_validation() {}
913
914 /**
915 * sets the export time config from the moodle form.
916 * you can also use this to set export config that
917 * isn't actually controlled by the user
918 * eg things that your subclasses want to keep in state
919 * across the export.
920 * keys must be in {@link get_allowed_export_config}
921 *
922 * this is deliberately not final (see boxnet plugin)
923 *
924 * @param array $config named array of config items to set.
925 */
926 public function set_export_config($config) {
927 $allowed = array_merge(
ffcfd8a7 928 array('wait', 'hidewait', 'format', 'hideformat'),
67a87e7d 929 $this->get_allowed_export_config()
930 );
931 foreach ($config as $key => $value) {
932 if (!in_array($key, $allowed)) {
933 continue; // @ todo throw exception
934 }
935 $this->exportconfig[$key] = $value;
936 }
937 }
938
939 /**
940 * gets an export time config value.
941 * subclasses should not override this.
942 *
943 * @param string key field to fetch
944 *
945 * @return string config value
946 *
947 * @todo figure out the error cases
948 */
949 public final function get_export_config($key) {
950 $allowed = array_merge(
ffcfd8a7 951 array('hidewait', 'wait', 'format', 'hideformat'),
67a87e7d 952 $this->get_allowed_export_config()
953 );
954 if (!in_array($key, $allowed)) {
955 return false; // @todo throw exception?
956 }
957 if (!array_key_exists($key, $this->exportconfig)) {
958 return null; // @todo what to return|
959 }
960 return $this->exportconfig[$key];
961 }
962
963 /**
964 * after the user submits their config
965 * they're given a confirm screen
966 * summarising what they've chosen.
967 *
968 * this function should return a table of nice strings => values
969 * of what they've chosen
970 * to be displayed in a table.
971 *
972 * @return array array of config items.
973 */
974 public function get_export_summary() {
975 return false;
976 }
977
978 /**
979 * called before the portfolio plugin gets control
980 * this function should copy all the files it wants to
981 * the temporary directory.
982 *
983 * @param string $tempdir path to temporary directory
984 */
985 public abstract function prepare_package($tempdir);
986
987 /**
988 * this is the function that is responsible for sending
989 * the package to the remote system,
990 * or whatever request is necessary to initiate the transfer.
991 *
992 * @return boolean success
993 */
994 public abstract function send_package();
995
996
997 /**
998 * once everything is done and the user
999 * has the finish page displayed to them
1000 * the base class takes care of printing them
1001 * "return to where you are" or "continue to portfolio" links
1002 * this function allows for exta finish options from the plugin
1003 *
1004 * @return array named array of links => titles
1005 */
1006 public function get_extra_finish_options() {
1007 return false;
1008 }
1009
1010 /**
1011 * the url for the user to continue to their portfolio
1012 *
1013 * @return string url or false.
1014 */
1015 public abstract function get_continue_url();
1016
1017 /**
1018 * mform to display to the user in their profile
1019 * if your plugin can't be configured by the user,
1020 * (see {@link has_user_config})
1021 * don't bother overriding this function
1022 *
1023 * @param moodleform $mform passed by reference, add elements to it
1024 */
1025 public function user_config_form(&$mform) {}
1026
1027 /**
1028 * mform to display to the admin configuring the plugin.
1029 * if your plugin can't be configured by the admin,
1030 * (see {@link} has_admin_config)
1031 * don't bother overriding this function
1032 *
1033 * this function can be called statically or non statically,
1034 * depending on whether it's creating a new instance (statically),
1035 * or editing an existing one (non statically)
1036 *
1037 * @param moodleform $mform passed by reference, add elements to it.
1038 * @return mixed - if a string is returned, it means the plugin cannot create an instance
1039 * and the string is an error code
1040 */
1041 public function admin_config_form(&$mform) {}
1042
1043 /**
1044 * just like the moodle form validation function
1045 * this is passed in the data array from the form
1046 * and if a non empty array is returned, form processing will stop.
1047 *
1048 * @param array $data data from form.
1049 * @return array keyvalue pairs - form element => error string
1050 */
1051 public static function admin_config_validation($data) {}
1052 /**
1053 * mform to display to the user exporting data using this plugin.
1054 * if your plugin doesn't need user input at this time,
1055 * (see {@link has_export_config}
1056 * don't bother overrideing this function
1057 *
1058 * @param moodleform $mform passed by reference, add elements to it.
1059 */
1060 public function export_config_form(&$mform) {}
1061
1062 /**
1063 * override this if your plugin doesn't allow multiple instances
1064 *
1065 * @return boolean
1066 */
1067 public static function allows_multiple() {
1068 return true;
1069 }
1070
1071 /**
1072 *
1073 * If at any point the caller wants to steal control
1074 * it can, by returning something that isn't false
1075 * in this function
1076 * The controller will redirect to whatever url
1077 * this function returns.
1078 * Afterwards, you can redirect back to portfolio/add.php?postcontrol=1
1079 * and {@link post_control} is called before the rest of the processing
1080 * for the stage is done
1081 *
1082 * @param int stage to steal control *before* (see constants PARAM_STAGE_*}
1083 *
1084 * @return boolean or string url
1085 */
1086 public function steal_control($stage) {
1087 return false;
1088 }
1089
1090 /**
1091 * after a plugin has elected to steal control,
1092 * and control returns to portfolio/add.php|postcontrol=1,
1093 * this function is called, and passed the stage that was stolen control from
1094 * and the request (get and post but not cookie) parameters
1095 * this is useful for external systems that need to redirect the user back
1096 * with some extra data in the url (like auth tokens etc)
1097 * for an example implementation, see boxnet portfolio plugin.
1098 *
1099 * @param int $stage the stage before control was stolen
1100 * @param array $params a merge of $_GET and $_POST
1101 *
1102 */
1103
1104 public function post_control($stage, $params) { }
1105
1106 /**
1107 * this function creates a new instance of a plugin
1108 * saves it in the database, saves the config
1109 * and returns it.
1110 * you shouldn't need to override it
1111 * unless you're doing something really funky
1112 *
1113 * @return object subclass of portfolio_plugin_base
1114 */
1115 public static function create_instance($plugin, $name, $config) {
1116 global $DB, $CFG;
1117 $new = (object)array(
1118 'plugin' => $plugin,
1119 'name' => $name,
1120 );
1121 $newid = $DB->insert_record('portfolio_instance', $new);
1122 require_once($CFG->dirroot . '/portfolio/type/' . $plugin . '/lib.php');
1123 $classname = 'portfolio_plugin_' . $plugin;
1124 $obj = new $classname($newid);
1125 $obj->set_config($config);
1126 return $obj;
1127 }
1128
1129 /**
1130 * construct a plugin instance
1131 * subclasses should not need to override this unless they're doing something special
1132 * and should call parent::__construct afterwards
1133 *
1134 * @param int $instanceid id of plugin instance to construct
1135 * @param mixed $record stdclass object or named array - use this is you already have the record to avoid another query
1136 *
1137 * @return object subclass of portfolio_plugin_base
1138 */
1139 public function __construct($instanceid, $record=null) {
1140 global $DB;
1141 if (!$record) {
1142 if (!$record = $DB->get_record('portfolio_instance', array('id' => $instanceid))) {
1143 return false; // @todo throw exception?
1144 }
1145 }
1146 foreach ((array)$record as $key =>$value) {
1147 if (property_exists($this, $key)) {
1148 $this->{$key} = $value;
1149 }
1150 }
1151 $this->config = new StdClass;
1152 $this->userconfig = array();
1153 $this->exportconfig = array();
1154 foreach ($DB->get_records('portfolio_instance_config', array('instance' => $instanceid)) as $config) {
1155 $this->config->{$config->name} = $config->value;
1156 }
1157 return $this;
1158 }
1159
1160 /**
1161 * a list of fields that can be configured per instance.
1162 * this is used for the save handlers of the config form
1163 * and as checks in set_config and get_config
1164 *
1165 * @return array array of strings (config item names)
1166 */
1167 public static function get_allowed_config() {
1168 return array();
1169 }
1170
1171 /**
1172 * a list of fields that can be configured by the user.
1173 * this is used for the save handlers in the config form
1174 * and as checks in set_user_config and get_user_config.
1175 *
1176 * @return array array of strings (config field names)
1177 */
1178 public function get_allowed_user_config() {
1179 return array();
1180 }
1181
1182 /**
1183 * a list of fields that can be configured by the user.
1184 * this is used for the save handlers in the config form
1185 * and as checks in set_export_config and get_export_config.
1186 *
1187 * @return array array of strings (config field names)
1188 */
1189 public function get_allowed_export_config() {
1190 return array();
1191 }
1192
1193 /**
1194 * saves (or updates) the config stored in portfolio_instance_config.
1195 * you shouldn't need to override this unless you're doing something funky.
1196 *
1197 * @param array $config array of config items.
1198 */
1199 public final function set_config($config) {
1200 global $DB;
1201 foreach ($config as $key => $value) {
1202 // try set it in $this first
1203 if ($this->set($key, $value)) {
1204 continue;
1205 }
1206 if (!in_array($key, $this->get_allowed_config())) {
1207 continue; // @todo throw exception?
1208 }
1209 if (!isset($this->config->{$key})) {
1210 $DB->insert_record('portfolio_instance_config', (object)array(
1211 'instance' => $this->id,
1212 'name' => $key,
1213 'value' => $value,
1214 ));
1215 } else if ($this->config->{$key} != $value) {
1216 $DB->set_field('portfolio_instance_config', 'value', $value, array('name' => $key, 'instance' => $this->id));
1217 }
1218 $this->config->{$key} = $value;
1219 }
1220 return true; // @todo - if we're going to change here to throw exceptions, this can change
1221 }
1222
1223 /**
1224 * gets the value of a particular config item
1225 *
1226 * @param string $key key to fetch
1227 *
1228 * @return string the corresponding value
1229 *
1230 * @todo determine what to return in the error case.
1231 */
1232 public final function get_config($key) {
1233 if (!in_array($key, $this->get_allowed_config())) {
1234 return false; // @todo throw exception?
1235 }
1236 if (isset($this->config->{$key})) {
1237 return $this->config->{$key};
1238 }
1239 return false; // @todo null?
1240 }
1241
1242 /**
1243 * get the value of a config item for a particular user
1244 *
1245 * @param string $key key to fetch
1246 * @param integer $userid id of user (defaults to current)
1247 *
1248 * @return string the corresponding value
1249 *
1250 * @todo determine what to return in the error case
1251 */
1252 public final function get_user_config($key, $userid=0) {
1253 global $DB;
1254
1255 if (empty($userid)) {
1256 $userid = $this->user->id;
1257 }
1258
1259 if ($key != 'visible') { // handled by the parent class
1260 if (!in_array($key, $this->get_allowed_user_config())) {
1261 return false; // @todo throw exception?
1262 }
1263 }
1264 if (!array_key_exists($userid, $this->userconfig)) {
1265 $this->userconfig[$userid] = (object)array_fill_keys(array_merge(array('visible'), $this->get_allowed_user_config()), null);
1266 foreach ($DB->get_records('portfolio_instance_user', array('instance' => $this->id, 'userid' => $userid)) as $config) {
1267 $this->userconfig[$userid]->{$config->name} = $config->value;
1268 }
1269 }
1270 if ($this->userconfig[$userid]->visible === null) {
1271 $this->set_user_config(array('visible' => 1), $userid);
1272 }
1273 return $this->userconfig[$userid]->{$key};
1274
1275 }
1276
1277 /**
1278 *
1279 * sets config options for a given user
1280 *
1281 * @param mixed $config array or stdclass containing key/value pairs to set
1282 * @param integer $userid userid to set config for (defaults to current)
1283 *
1284 * @todo determine what to return in the error case
1285 */
1286 public final function set_user_config($config, $userid=0) {
1287 global $DB;
1288
1289 if (empty($userid)) {
1290 $userid = $this->user->id;
1291 }
1292
1293 foreach ($config as $key => $value) {
1294 if ($key != 'visible' && !in_array($key, $this->get_allowed_user_config())) {
1295 continue; // @todo throw exception?
1296 }
1297 if (!$existing = $DB->get_record('portfolio_instance_user', array('instance'=> $this->id, 'userid' => $userid, 'name' => $key))) {
1298 $DB->insert_record('portfolio_instance_user', (object)array(
1299 'instance' => $this->id,
1300 'name' => $key,
1301 'value' => $value,
1302 'userid' => $userid,
1303 ));
1304 } else if ($existing->value != $value) {
1305 $DB->set_field('portfolio_instance_user', 'value', $value, array('name' => $key, 'instance' => $this->id, 'userid' => $userid));
1306 }
1307 $this->userconfig[$userid]->{$key} = $value;
1308 }
1309 return true; // @todo
1310
1311 }
1312
1313 /**
1314 * generic getter for properties belonging to this instance
1315 * <b>outside</b> the subclasses
1316 * like name, visible etc.
1317 *
1318 * @todo determine what to return in the error case
1319 */
1320 public final function get($field) {
1321 if (property_exists($this, $field)) {
1322 return $this->{$field};
1323 }
1324 return false; // @todo throw exception?
1325 }
1326
1327 /**
1328 * generic setter for properties belonging to this instance
1329 * <b>outside</b> the subclass
1330 * like name, visible, etc.
1331 *
1332 * @todo determine what to return in the error case
1333 */
1334 public final function set($field, $value) {
1335 if (property_exists($this, $field)) {
1336 $this->{$field} = $value;
1337 $this->dirty = true;
1338 return true;
1339 }
1340 return false; // @todo throw exception?
1341
1342 }
1343
1344 /**
1345 * saves stuff that's been stored in the object to the database
1346 * you shouldn't need to override this
1347 * unless you're doing something really funky.
1348 * and if so, call parent::save when you're done.
1349 */
1350 public function save() {
1351 global $DB;
1352 if (!$this->dirty) {
1353 return true;
1354 }
1355 $fordb = new StdClass();
1356 foreach (array('id', 'name', 'plugin', 'visible') as $field) {
1357 $fordb->{$field} = $this->{$field};
1358 }
1359 $DB->update_record('portfolio_instance', $fordb);
1360 $this->dirty = false;
1361 return true;
1362 }
1363
1364 /**
1365 * deletes everything from the database about this plugin instance.
1366 * you shouldn't need to override this unless you're storing stuff
1367 * in your own tables. and if so, call parent::delete when you're done.
1368 */
1369 public function delete() {
1370 global $DB;
1371 $DB->delete_records('portfolio_instance_config', array('instance' => $this->get('id')));
1372 $DB->delete_records('portfolio_instance_user', array('instance' => $this->get('id')));
1373 $DB->delete_records('portfolio_instance', array('id' => $this->get('id')));
1374 $this->dirty = false;
1375 return true;
1376 }
1377}
1378
1379/**
1380* this is the form that is actually used while exporting.
1381* plugins and callers don't get to define their own class
1382* as we have to handle form elements from both places
1383* see the docs for portfolio_plugin_base and portfolio_caller for more information
1384*/
1385final class portfolio_export_form extends moodleform {
1386
1387 public function definition() {
1388
1389 $mform =& $this->_form;
1390 $mform->addElement('hidden', 'stage', PORTFOLIO_STAGE_CONFIG);
1391 $mform->addElement('hidden', 'instance', $this->_customdata['instance']->get('id'));
1392
1393 if (array_key_exists('formats', $this->_customdata) && is_array($this->_customdata['formats'])) {
1394 if (count($this->_customdata['formats']) > 1) {
1395 $options = array();
1396 foreach ($this->_customdata['formats'] as $key) {
1397 $options[$key] = get_string('format_' . $key, 'portfolio');
1398 }
1399 $mform->addElement('select', 'format', get_string('availableformats', 'portfolio'), $options);
1400 } else {
1401 $f = array_shift($this->_customdata['formats']);
1402 $mform->addElement('hidden', 'format', $f);
1403 }
1404 }
1405
1406 if (array_key_exists('expectedtime', $this->_customdata) && $this->_customdata['expectedtime'] != PORTFOLIO_TIME_LOW) {
1407 //$mform->addElement('select', 'wait', get_string('waitlevel_' . $this->_customdata['expectedtime'], 'portfolio'), $options);
1408
1409
1410 $radioarray = array();
1411 $radioarray[] = &MoodleQuickForm::createElement('radio', 'wait', '', get_string('wait', 'portfolio'), 1);
1412 $radioarray[] = &MoodleQuickForm::createElement('radio', 'wait', '', get_string('dontwait', 'portfolio'), 0);
1413 $mform->addGroup($radioarray, 'radioar', get_string('wanttowait_' . $this->_customdata['expectedtime'], 'portfolio') , array(' '), false);
1414
1415 $mform->setDefault('wait', 0);
1416 }
1417 else {
1418 $mform->addElement('hidden', 'wait', 1);
1419 }
1420
1421 if (array_key_exists('plugin', $this->_customdata) && is_object($this->_customdata['plugin'])) {
1422 $this->_customdata['plugin']->export_config_form($mform, $this->_customdata['userid']);
1423 }
1424
1425 if (array_key_exists('caller', $this->_customdata) && is_object($this->_customdata['caller'])) {
1426 $this->_customdata['caller']->export_config_form($mform, $this->_customdata['instance'], $this->_customdata['userid']);
1427 }
1428
1429 $this->add_action_buttons(true, get_string('next'));
1430 }
1431
1432 public function validation($data) {
1433
1434 $errors = array();
1435
1436 if (array_key_exists('plugin', $this->_customdata) && is_object($this->_customdata['plugin'])) {
1437 $pluginerrors = $this->_customdata['plugin']->export_config_validation($data);
1438 if (is_array($pluginerrors)) {
1439 $errors = $pluginerrors;
1440 }
1441 }
1442 if (array_key_exists('caller', $this->_customdata) && is_object($this->_customdata['caller'])) {
1443 $callererrors = $this->_customdata['caller']->export_config_validation($data);
1444 if (is_array($callererrors)) {
1445 $errors = array_merge($errors, $callererrors);
1446 }
1447 }
1448 return $errors;
1449 }
1450}
1451
1452/**
1453* this form is extendable by plugins
1454* who want the admin to be able to configure
1455* more than just the name of the instance.
1456* this is NOT done by subclassing this class,
1457* see the docs for portfolio_plugin_base for more information
1458*/
1459final class portfolio_admin_form extends moodleform {
1460
1461 protected $instance;
1462 protected $plugin;
1463
1464 public function definition() {
1465 global $CFG;
1466 $this->plugin = $this->_customdata['plugin'];
1467 $this->instance = (isset($this->_customdata['instance'])
1468 && is_subclass_of($this->_customdata['instance'], 'portfolio_plugin_base'))
1469 ? $this->_customdata['instance'] : null;
1470
1471 $mform =& $this->_form;
1472 $strrequired = get_string('required');
1473
1474 $mform->addElement('hidden', 'edit', ($this->instance) ? $this->instance->get('id') : 0);
1475 $mform->addElement('hidden', 'new', $this->plugin);
1476 $mform->addElement('hidden', 'plugin', $this->plugin);
1477
1478 $mform->addElement('text', 'name', get_string('name'), 'maxlength="100" size="30"');
1479 $mform->addRule('name', $strrequired, 'required', null, 'client');
1480
1481 // let the plugin add the fields they want (either statically or not)
1482 if (portfolio_static_function($this->plugin, 'has_admin_config')) {
1483 if (!$this->instance) {
1484 $result = portfolio_static_function($this->plugin, 'admin_config_form', $mform);
1485 } else {
1486 $result = $this->instance->admin_config_form($mform);
1487 }
1488 }
1489
1490 if (isset($result) && is_string($result)) { // something went wrong, stop
1491 return $this->raise_error($result, 'portfolio_' . $this->plugin, $CFG->wwwroot . '/' . $CFG->admin . '/portfolio.php');
1492 }
1493
1494 // and set the data if we have some.
1495 if ($this->instance) {
1496 $data = array('name' => $this->instance->get('name'));
1497 foreach ($this->instance->get_allowed_config() as $config) {
1498 $data[$config] = $this->instance->get_config($config);
1499 }
1500 $this->set_data($data);
1501 }
1502 $this->add_action_buttons(true, get_string('save', 'portfolio'));
1503 }
1504
1505 public function validation($data) {
1506 global $DB;
1507
1508 $errors = array();
1509 if ($DB->count_records('portfolio_instance', array('name' => $data['name'], 'plugin' => $data['plugin'])) > 1) {
1510 $errors = array('name' => get_string('err_uniquename', 'portfolio'));
1511 }
1512
1513 $pluginerrors = array();
1514 if ($this->instance) {
1515 $pluginerrors = $this->instance->admin_config_validation($data);
1516 }
1517 else {
1518 $pluginerrors = portfolio_static_function($this->plugin, 'admin_config_validation', $data);
1519 }
1520 if (is_array($pluginerrors)) {
1521 $errors = array_merge($errors, $pluginerrors);
1522 }
1523 return $errors;
1524 }
1525}
1526
1527/**
1528* this is the form for letting the user configure an instance of a plugin.
1529* in order to extend this, you don't subclass this in the plugin..
1530* see the docs in portfolio_plugin_base for more information
1531*/
1532final class portfolio_user_form extends moodleform {
1533
1534 protected $instance;
1535 protected $userid;
1536
1537 public function definition() {
1538 $this->instance = $this->_customdata['instance'];
1539 $this->userid = $this->_customdata['userid'];
1540
1541 $this->_form->addElement('hidden', 'config', $this->instance->get('id'));
1542
1543 $this->instance->user_config_form($this->_form, $this->userid);
1544
1545 $data = array();
1546 foreach ($this->instance->get_allowed_user_config() as $config) {
1547 $data[$config] = $this->instance->get_user_config($config, $this->userid);
1548 }
1549 $this->set_data($data);
1550 $this->add_action_buttons(true, get_string('save', 'portfolio'));
1551 }
1552
1553 public function validation($data) {
1554
1555 $errors = $this->instance->user_config_validation($data);
1556
1557 }
1558}
1559
1560/**
1561*
1562* Class that handles the various stages of the actual export
1563*/
1564final class portfolio_exporter {
1565
1566 private $currentstage;
1567 private $caller;
1568 private $instance;
1569 private $noconfig;
1570 private $navigation;
1571 private $uniquekey;
1572 private $tempdir;
1573 private $user;
1574
1575 public $instancefile;
1576 public $callerfile;
1577
1578 /**
1579 * construct a new exporter for use
1580 *
1581 * @param portfolio_plugin_base subclass $instance portfolio instance (passed by reference)
1582 * @param portfolio_caller_base subclass $caller portfolio caller (passed by reference)
1583 * @param string $navigation result of build_navigation (passed to print_header)
1584 */
1585 public function __construct(&$instance, &$caller, $callerfile, $navigation) {
1586 $this->instance =& $instance;
1587 $this->caller =& $caller;
1588 if ($instance) {
1589 $this->instancefile = 'portfolio/type/' . $instance->get('plugin') . '/lib.php';
1590 }
1591 $this->callerfile = $callerfile;
1592 $this->stage = PORTFOLIO_STAGE_CONFIG;
1593 $this->navigation = $navigation;
1594 }
1595
1596 /*
1597 * generic getter for properties belonging to this instance
1598 * <b>outside</b> the subclasses
1599 * like name, visible etc.
1600 *
1601 * @todo determine what to return in the error case
1602 */
1603 public function get($field) {
1604 if (property_exists($this, $field)) {
1605 return $this->{$field};
1606 }
1607 return false; // @todo throw exception?
1608 }
1609
1610 /**
1611 * generic setter for properties belonging to this instance
1612 * <b>outside</b> the subclass
1613 * like name, visible, etc.
1614 *
1615 * @todo determine what to return in the error case
1616 */
1617
1618 public function set($field, $value) {
1619 if (property_exists($this, $field)) {
1620 $this->{$field} = $value;
1621 if ($field == 'instance') {
1622 $this->instancefile = 'portfolio/type/' . $this->instance->get('plugin') . '/lib.php';
1623 }
1624 $this->dirty = true;
1625 return true;
1626 }
1627 return false; // @todo throw exception?
1628
1629 }
1630 /**
1631 * process the given stage calling whatever functions are necessary
1632 *
1633 * @param int $stage (see PORTFOLIO_STAGE_* constants)
1634 * @param boolean $alreadystolen used to avoid letting plugins steal control twice.
1635 *
1636 * @return boolean whether or not to process the next stage. this is important as the function is called recursively.
1637 */
1638 public function process_stage($stage, $alreadystolen=false) {
1639 global $SESSION;
1640 if (!$alreadystolen && $url = $this->instance->steal_control($stage)) {
1641 $SESSION->portfolio->stagepresteal = $stage;
1642 redirect($url);
1643 break;
1644 }
1645
1646 $waiting = $this->instance->get_export_config('wait');
1647 if ($stage > PORTFOLIO_STAGE_QUEUEORWAIT && empty($waiting)) {
1648 $stage = PORTFOLIO_STAGE_FINISHED;
1649 }
1650 $functionmap = array(
1651 PORTFOLIO_STAGE_CONFIG => 'config',
1652 PORTFOLIO_STAGE_CONFIRM => 'confirm',
1653 PORTFOLIO_STAGE_QUEUEORWAIT => 'queueorwait',
1654 PORTFOLIO_STAGE_PACKAGE => 'package',
1655 PORTFOLIO_STAGE_CLEANUP => 'cleanup',
1656 PORTFOLIO_STAGE_SEND => 'send',
1657 PORTFOLIO_STAGE_FINISHED => 'finished'
1658 );
1659
1660 $function = 'process_stage_' . $functionmap[$stage];
1661 if ($this->$function()) {
1662 // if we get through here it means control was returned
1663 // as opposed to wanting to stop processing
1664 // eg to wait for user input.
1665 $stage++;
1666 return $this->process_stage($stage);
1667 }
1668 return false;
1669 }
1670
1671 /**
1672 * helper function to return the portfolio instance
1673 *
1674 * @return portfolio_plugin_base subclass
1675 */
1676 public function instance() {
1677 return $this->instance;
1678 }
1679
1680 /**
1681 * helper function to return the caller object
1682 *
1683 * @return portfolio_caller_base subclass
1684 */
1685 public function caller() {
1686 return $this->caller;
1687 }
1688
1689 /**
1690 * processes the 'config' stage of the export
1691 *
1692 * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
1693 */
1694 public function process_stage_config() {
1695
1696 global $SESSION;
1697
1698 $pluginobj = $callerobj = null;
1699 if ($this->instance->has_export_config()) {
1700 $pluginobj = $this->instance;
1701 }
1702 if ($this->caller->has_export_config()) {
1703 $callerobj = $this->caller;
1704 }
1705 $formats = array_intersect($this->instance->supported_formats(), $this->caller->supported_formats());
5071079c 1706 $allsupported = portfolio_supported_formats();
1707 foreach ($formats as $key => $format) {
1708 if (!in_array($format, $allsupported)) {
1709 debugging(get_string('invalidformat', 'portfolio', $format));
1710 unset($formats[$key]);
1711 }
1712 }
67a87e7d 1713 $expectedtime = $this->instance->expected_time($this->caller->expected_time());
1714 if (count($formats) == 0) {
1715 // something went wrong, we should not have gotten this far.
1716 return $this->raise_error('nocommonformats', 'portfolio', get_class($caller));
1717 }
1718 // even if neither plugin or caller wants any config, we have to let the user choose their format, and decide to wait.
1719 if ($pluginobj || $callerobj || count($formats) > 1 || $expectedtime != PORTFOLIO_TIME_LOW) {
1720 $customdata = array(
1721 'instance' => $this->instance,
1722 'plugin' => $pluginobj,
1723 'caller' => $callerobj,
1724 'userid' => $this->user->id,
1725 'formats' => $formats,
1726 'expectedtime' => $expectedtime,
1727 );
1728 $mform = new portfolio_export_form('', $customdata);
1729 if ($mform->is_cancelled()){
1730 unset($SESSION->portfolio);
1731 redirect($this->caller->get_return_url());
1732 exit;
1733 } else if ($fromform = $mform->get_data()){
1734 if (!confirm_sesskey()) {
1735 return $this->raise_error('confirmsesskeybad', '', $caller->get_return_url());
1736 }
1737 $pluginbits = array();
1738 $callerbits = array();
1739 foreach ($fromform as $key => $value) {
1740 if (strpos($key, 'plugin_') === 0) {
1741 $pluginbits[substr($key, 7)] = $value;
1742 } else if (strpos($key, 'caller_') === 0) {
1743 $callerbits[substr($key, 7)] = $value;
1744 }
1745 }
1746 $callerbits['format'] = $pluginbits['format'] = $fromform->format;
1747 $pluginbits['wait'] = $fromform->wait;
1748 if ($expectedtime = PORTFOLIO_TIME_LOW) {
1749 $pluginbits['wait'] = 1;
1750 $pluginbits['hidewait'] = 1;
1751 }
ffcfd8a7 1752 $callerbits['hideformat'] = $pluginbits['hideformat'] = (count($formats) == 1);
67a87e7d 1753 $this->caller->set_export_config($callerbits);
1754 $this->instance->set_export_config($pluginbits);
1755 return true;
1756 } else {
1757 $this->print_header();
1758 print_heading(get_string('configexport' ,'portfolio'));
1759 print_simple_box_start();
1760 $mform->display();
1761 print_simple_box_end();
1762 print_footer();
1763 return false;;
1764 }
1765 } else {
1766 $this->noexportconfig = true;
ffcfd8a7 1767 $format = array_shift($formats);
1768 $this->instance->set_export_config(array('hidewait' => 1, 'wait' => 1, 'format' => $format, 'hideformat' => 1));
1769 $this->caller->set_export_config(array('format' => $format, 'hideformat' => 1));
67a87e7d 1770 return true;
1771 // do not break - fall through to confirm
1772 }
1773 }
1774
67a87e7d 1775 /**
1776 * processes the 'confirm' stage of the export
1777 *
1778 * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
1779 */
1780 public function process_stage_confirm() {
ffcfd8a7 1781 global $CFG, $DB;
1782
1783 $previous = $DB->get_records(
1784 'portfolio_log',
1785 array(
1786 'userid' => $this->user->id,
1787 'portfolio' => $this->instance->get('id'),
1788 'caller_sha1' => $this->caller->get_sha1(),
1789 )
1790 );
1791 if (isset($this->noexportconfig) && empty($previous)) {
67a87e7d 1792 return true;
1793 }
1794 $strconfirm = get_string('confirmexport', 'portfolio');
1795 $yesurl = $CFG->wwwroot . '/portfolio/add.php?stage=' . PORTFOLIO_STAGE_QUEUEORWAIT;
ffcfd8a7 1796 $nourl = $CFG->wwwroot . '/portfolio/add.php?cancel=1';
67a87e7d 1797 $this->print_header();
1798 print_heading($strconfirm);
1799 print_simple_box_start();
1800 print_heading(get_string('confirmsummary', 'portfolio'), '', 4);
ffcfd8a7 1801 $mainsummary = array();
1802 if (!$this->instance->get_export_config('hideformat')) {
1803 $mainsummary[get_string('selectedformat', 'portfolio')] = get_string('format_' . $this->instance->get_export_config('format'), 'portfolio');
1804 }
67a87e7d 1805 if (!$this->instance->get_export_config('hidewait')) {
ffcfd8a7 1806 $mainsummary[get_string('selectedwait', 'portfolio')] = get_string(($this->instance->get_export_config('wait') ? 'yes' : 'no'));
1807 }
1808 if ($previous) {
1809 $previousstr = '';
1810 foreach ($previous as $row) {
1811 $previousstr .= userdate($row->time);
1812 if ($row->caller_class != get_class($this->caller)) {
1813 require_once($CFG->dirroot . '/' . $row->caller_file);
1814 $previousstr .= ' (' . call_user_func(array($row->caller_class, 'display_name')) . ')';
1815 }
1816 $previousstr .= '<br />';
1817 }
1818 $mainsummary[get_string('exportedpreviously', 'portfolio')] = $previousstr;
67a87e7d 1819 }
1820 if (!$csummary = $this->caller->get_export_summary()) {
1821 $csummary = array();
1822 }
1823 if (!$isummary = $this->instance->get_export_summary()) {
1824 $isummary = array();
1825 }
1826 $mainsummary = array_merge($mainsummary, $csummary, $isummary);
ffcfd8a7 1827 $table = new StdClass;
1828 $table->data = array();
67a87e7d 1829 foreach ($mainsummary as $string => $value) {
ffcfd8a7 1830 $table->data[] = array($string, $value);
67a87e7d 1831 }
ffcfd8a7 1832 print_table($table);
67a87e7d 1833 notice_yesno($strconfirm, $yesurl, $nourl);
1834 print_simple_box_end();
1835 print_footer();
1836 return false;
1837 }
1838
1839 /**
1840 * processes the 'queueornext' stage of the export
1841 *
1842 * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
1843 */
1844 public function process_stage_queueorwait() {
1845 global $SESSION;
1846 $wait = $this->instance->get_export_config('wait');
1847 if (empty($wait)) {
1848 error_log(print_r(serialize($this), true));
1849 events_trigger('portfolio_send', $this);
1850 unset($SESSION->portfolio);
1851 return $this->process_stage_finished();
1852 }
1853 return true;
1854 }
1855
1856 /**
1857 * processes the 'package' stage of the export
1858 *
1859 * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
1860 */
1861 public function process_stage_package() {
1862 // now we've agreed on a format,
1863 // the caller is given control to package it up however it wants
1864 // and then the portfolio plugin is given control to do whatever it wants.
1865 $unique = $this->user->id . '-' . time();
1866 $tempdir = temp_portfolio_working_directory($unique);
1867 $this->uniquekey = $unique;
1868 $this->tempdir = $tempdir;
1869 if (!$this->caller->prepare_package($tempdir)) {
3f871282 1870 return $this->raise_error('callercouldnotpackage', 'portfolio', $this->caller->get_return_url());
67a87e7d 1871 }
1872 if (!$package = $this->instance->prepare_package($tempdir)) {
3f871282 1873 return $this->raise_error('plugincouldnotpackage', 'portfolio', $this->caller->get_return_url());
67a87e7d 1874 }
1875 return true;
1876 }
1877
1878 /**
1879 * processes the 'cleanup' stage of the export
1880 *
1881 * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
1882 */
1883 public function process_stage_cleanup() {
1884 global $CFG;
1885 // @todo this is unpleasant. fix it.
1886 require_once($CFG->dirroot . '/backup/lib.php');
1887 delete_dir_contents($this->tempdir);
1888 // @todo maybe add a hook in the plugin(s)
1889 return true;
1890 }
1891
1892 /**
1893 * processes the 'send' stage of the export
1894 *
1895 * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
1896 */
1897 public function process_stage_send() {
1898 // send the file
1899 if (!$this->instance->send_package()) {
1900 return $this->raise_error('failedtosendpackage', 'portfolio');
1901 }
ffcfd8a7 1902 // log the transfer
1903 global $DB;
1904 $l = array(
1905 'userid' => $this->user->id,
1906 'portfolio' => $this->instance->get('id'),
1907 'caller_file' => $this->callerfile,
1908 'caller_sha1' => $this->caller->get_sha1(),
1909 'caller_class' => get_class($this->caller),
1910 'time' => time(),
1911 );
1912 $DB->insert_record('portfolio_log', $l);
67a87e7d 1913 return true;
1914 }
1915
1916 /**
1917 * processes the 'finish' stage of the export
1918 *
1919 * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
1920 */
1921 public function process_stage_finished() {
1922 global $SESSION;
1923 $returnurl = $this->caller->get_return_url();
1924 $continueurl = $this->instance->get_continue_url();
1925 $extras = $this->instance->get_extra_finish_options();
1926
1927 $this->print_header();
1928 //@todo do something different here if we're queueing.
1929 print_heading(get_string('exportcomplete', 'portfolio'));
1930 if ($returnurl) {
1931 echo '<a href="' . $returnurl . '">' . get_string('returntowhereyouwere', 'portfolio') . '</a><br />';
1932 }
1933 if ($continueurl) {
1934 echo '<a href="' . $continueurl . '">' . get_string('continuetoportfolio', 'portfolio') . '</a><br />';
1935 }
1936 if (is_array($extras)) {
1937 foreach ($extras as $link => $string) {
1938 echo '<a href="' . $link . '">' . $string . '</a><br />';
1939 }
1940 }
1941 print_footer();
1942 unset($SESSION->portfolio);
1943 return false;
1944 }
1945
1946
1947 /**
1948 * local print header function to be reused across the export
1949 *
1950 * @param string $titlestring key for a portfolio language string
1951 * @param string $headerstring key for a portfolio language string
1952 */
1953 public function print_header($titlestr='exporting', $headerstr='exporting') {
1954 $titlestr = get_string($titlestr, 'portfolio');
1955 $headerstr = get_string($headerstr, 'portfolio');
1956
1957 print_header($titlestr, $headerstr, $this->navigation);
1958 }
1959
1960 /**
1961 * error handler - decides whether we're running interactively or not
1962 * and behaves accordingly
1963 */
1964 public static function raise_error($string, $module, $continue=null) {
1965 if (defined('FULLME') && FULLME == 'cron') {
1966 debugging(get_string($string, $module));
1967 return false;
1968 }
1969 global $SESSION;
1970 unset($SESSION->portfolio);
1971 print_error($string, $module, $continue);
1972 }
1973}
1974
1975/**
1976* event handler for the portfolio_send event
1977*/
1978function portfolio_handle_event($eventdata) {
1979 global $CFG;
1980 require_once($CFG->dirroot . '/' . $eventdata->instancefile);
1981 require_once($CFG->dirroot . '/' . $eventdata->callerfile);
1982 $exporter = unserialize(serialize($eventdata));
1983 $exporter->process_stage_package();
1984 $exporter->process_stage_send();
1985 $exporter->process_stage_cleanup();
1986 return true;
1987}
1988
1989?>