MDL-30989 portfolio: Fixed up phpdocs
[moodle.git] / lib / portfolio / formats.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * This file contains all the class definitions of the export formats.
19  *
20  * They are implemented in php classes rather than just a simpler hash
21  * Because it provides an easy way to do subtyping using php inheritance.
22  *
23  * @package core_portfolio
24  * @copyright 2008 Penny Leach <penny@catalyst.net.nz>,
25  *                 Martin Dougiamas <http://dougiamas.com>
26  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27  */
29 defined('MOODLE_INTERNAL') || die();
31 /**
32  * Base class to inherit from.
33  *
34  * Do not use this anywhere in supported_formats
35  *
36  * @package core_portfolio
37  * @category portfolio
38  * @copyright 2008 Penny Leach <penny@catalyst.net.nz>,
39  *                 Martin Dougiamas <http://dougiamas.com>
40  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
41  *
42  */
43 abstract class portfolio_format {
45     /**
46      * Array of mimetypes this format supports
47      *
48      * @throws coding_exception
49      */
50     public static function mimetypes() {
51         throw new coding_exception('mimetypes() method needs to be overridden in each subclass of portfolio_format');
52     }
54     /**
55      * For multipart formats, eg html with attachments,
56      * we need to have a directory to place associated files from
57      * inside the zip file. This is the name of that directory
58      *
59      * @throws coding_exception
60      */
61     public static function get_file_directory() {
62         throw new coding_exception('get_file_directory() method needs to be overridden in each subclass of portfolio_format');
63     }
65     /**
66      * Given a file, return a snippet of markup in whatever format
67      * to link to that file.
68      * Usually involves the path given by get_file_directory.
69      * This is not supported in subclasses of portfolio_format_file
70      * since they're all just single files.
71      * @see get_file_directory
72      *
73      * @param stored_file $file file information object
74      * @param array $options array of options to pass. can contain:
75      *              attributes => hash of existing html attributes (eg title, height, width, etc)
76      *
77      * @throws coding_exception
78      */
79     public static function file_output($file, $options=null) {
80         throw new coding_exception('file_output() method needs to be overridden in each subclass of portfolio_format');
81     }
83     /**
84      * Create portfolio tag
85      *
86      * @param stored_file $file file information object
87      * @param string $path file path
88      * @param array $attributes portfolio attributes
89      * @return string
90      */
91     public static function make_tag($file, $path, $attributes) {
92         $srcattr = 'href';
93         $tag     = 'a';
94         $content = $file->get_filename();
95         if (in_array($file->get_mimetype(), portfolio_format_image::mimetypes())) {
96             $srcattr = 'src';
97             $tag     = 'img';
98             $content = '';
99         }
101         $attributes[$srcattr] = $path; // this will override anything we might have been passed (which is good)
102         $dom = new DomDocument();
103         $elem = null;
104         if ($content) {
105             $elem = $dom->createElement($tag, $content);
106         } else {
107             $elem = $dom->createElement($tag);
108         }
110         foreach ($attributes as $key => $value) {
111             $elem->setAttribute($key, $value);
112         }
113         $dom->appendChild($elem);
114         return $dom->saveXML($elem);
115     }
117     /**
118      * Whether this format conflicts with the given format.
119      * This is used for the case where an export location
120      * "generally" supports something like FORMAT_PLAINHTML
121      * but then in a specific export case, must add attachments,
122      * which means that FORMAT_RICHHTML is supported in that case,
123      * which implies removing support for FORMAT_PLAINHTML.
124      * Note that conflicts don't have to be bi-directional
125      * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
126      * but not the other way around) and things within the class hierarchy
127      * are resolved automatically anyway.
128      * This is really just between subclasses of format_rich
129      * and subclasses of format_file.
130      *
131      * @param string $format one of the FORMAT_XX constants
132      * @return bool
133      */
134     public static function conflicts($format) {
135         return false;
136     }
139 /**
140  * The most basic type - pretty much everything is a subtype
141  *
142  * @package core_portfolio
143  * @category portfolio
144  * @copyright 2009 Penny Leach <penny@catalyst.net.nz>, Martin Dougiamas
145  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
146  */
147 class portfolio_format_file extends portfolio_format {
149     /**
150      * Array of mimetypes this format supports
151      *
152      * @return array
153      */
154     public static function mimetypes() {
155         return array();
156     }
158     /**
159      * For multipart formats, eg html with attachments,
160      * we need to have a directory to place associated files from
161      * inside the zip file. This is the name of that directory
162      *
163      * @return bool
164      */
165     public static function get_file_directory() {
166         return false;
167     }
169     /**
170      * Given a file, return a snippet of markup in whatever format
171      * to link to that file.
172      * Usually involves the path given by get_file_directory.
173      * This is not supported in subclasses of portfolio_format_file
174      * since they're all just single files.
175      * @see get_file_directory
176      *
177      * @param stored_file $file informations object
178      * @param array $options array of options to pass. can contain:
179      *              attributes => hash of existing html attributes (eg title, height, width, etc)
180      */
181     public static function file_output($file, $options=null) {
182         throw new portfolio_exception('fileoutputnotsupported', 'portfolio');
183     }
186 /**
187  * Image format, subtype of file.
188  *
189  * @package core_portfolio
190  * @category portfolio
191  * @copyright 2009 Penny Leach
192  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
193  */
194 class portfolio_format_image extends portfolio_format_file {
195     /**
196      * Return all mimetypes that use image.gif (eg all images)
197      *
198      * @return string
199      */
200     public static function mimetypes() {
201         return mimeinfo_from_icon('type', 'image', true);
202     }
204     /**
205      * Whether this format conflicts with the given format.
206      * This is used for the case where an export location
207      * "generally" supports something like FORMAT_PLAINHTML
208      * but then in a specific export case, must add attachments,
209      * which means that FORMAT_RICHHTML is supported in that case,
210      * which implies removing support for FORMAT_PLAINHTML.
211      * Note that conflicts don't have to be bi-directional
212      * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
213      * but not the other way around) and things within the class hierarchy
214      * are resolved automatically anyway.
215      * This is really just between subclasses of format_rich
216      * and subclasses of format_file.
217      *
218      * @param string $format one of the FORMAT_XX constants
219      * @return bool
220      */
221     public static function conflicts($format) {
222         return ($format == PORTFOLIO_FORMAT_RICHHTML
223             || $format == PORTFOLIO_FORMAT_PLAINHTML);
224     }
227 /**
228  * HTML format
229  *
230  * Could be used for an external cms or something in case we want to be really specific.
231  *
232  * @package core_portfolio
233  * @category portfolio
234  * @copyright 2008 Penny Leach
235  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
236  */
237 class portfolio_format_plainhtml extends portfolio_format_file {
239     /**
240      * Return html mimetype
241      *
242      * @return array
243      */
244     public static function mimetypes() {
245         return array('text/html');
246     }
248     /**
249      * Whether this format conflicts with the given format.
250      * This is used for the case where an export location
251      * "generally" supports something like FORMAT_PLAINHTML
252      * but then in a specific export case, must add attachments,
253      * which means that FORMAT_RICHHTML is supported in that case,
254      * which implies removing support for FORMAT_PLAINHTML.
255      * Note that conflicts don't have to be bi-directional
256      * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
257      * but not the other way around) and things within the class hierarchy
258      * are resolved automatically anyway.
259      * This is really just between subclasses of format_rich
260      * and subclasses of format_file.
261      *
262      * @param string $format one of the FORMAT_XX constants
263      * @return bool
264      */
265     public static function conflicts($format) {
266         return ($format == PORTFOLIO_FORMAT_RICHHTML
267             || $format == PORTFOLIO_FORMAT_FILE);
268     }
271 /**
272  * Video format
273  *
274  * For portfolio plugins that support videos specifically
275  *
276  * @package core_portfolio
277  * @category portfolio
278  * @copyright 2008 Penny Leach
279  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
280  */
281 class portfolio_format_video extends portfolio_format_file {
283      /**
284       * Return video mimetypes
285       *
286       * @return array
287       */
288     public static function mimetypes() {
289         return array_merge(
290             mimeinfo_from_icon('type', 'video', true),
291             mimeinfo_from_icon('type', 'avi', true)
292         );
293     }
296 /**
297  * Class for plain text format.
298  *
299  * Not sure why we would need this yet,
300  * but since resource module wants to export it... we can
301  *
302  * @package core_portfolio
303  * @category portfolio
304  * @copyright 2008 Penny Leach
305  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
306  */
307 class portfolio_format_text extends portfolio_format_file {
309     /**
310      * Return plain text mimetypes
311      *
312      * @return array
313      */
314     public static function mimetypes() {
315         return array('text/plain');
316     }
318     /**
319      * Whether this format conflicts with the given format.
320      * This is used for the case where an export location
321      * "generally" supports something like FORMAT_PLAINHTML
322      * but then in a specific export case, must add attachments,
323      * which means that FORMAT_RICHHTML is supported in that case,
324      * which implies removing support for FORMAT_PLAINHTML.
325      * Note that conflicts don't have to be bi-directional
326      * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
327      * but not the other way around) and things within the class hierarchy
328      * are resolved automatically anyway.
329      * This is really just between subclasses of format_rich
330      * and subclasses of format_file.
331      *
332      * @param string $format one of the FORMAT_XX constants
333      * @return bool
334      */
335     public static function conflicts($format ) {
336         return ($format == PORTFOLIO_FORMAT_PLAINHTML
337             || $format == PORTFOLIO_FORMAT_RICHHTML);
338     }
341 /**
342  * Base class for rich formats.
343  *
344  * These are multipart - eg things with attachments
345  *
346  * @package core_portfolio
347  * @category portfolio
348  * @copyright 2009 Penny Leach
349  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
350  */
351 abstract class portfolio_format_rich extends portfolio_format {
353     /**
354      * Return rich text mimetypes
355      *
356      * @return array
357      */
358     public static function mimetypes() {
359         return array();
360     }
364 /**
365  * Richhtml - html with attachments.
366  *
367  * The most commonly used rich format
368  * eg inline images
369  *
370  * @package core_portfolio
371  * @category portfolio
372  * @copyright 2009 Penny Leach
373  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
374  */
375 class portfolio_format_richhtml extends portfolio_format_rich {
377     /**
378      * For multipart formats, eg html with attachments,
379      * we need to have a directory to place associated files from
380      * inside the zip file. this is the name of that directory
381      *
382      * @return string
383      */
384     public static function get_file_directory() {
385         return 'site_files/';
386     }
388     /**
389      * Given a file, return a snippet of markup in whatever format
390      * to link to that file.
391      * Usually involves the path given by get_file_directory.
392      * This is not supported in subclasses of portfolio_format_file
393      * since they're all just single files.
394      * @see get_file_directory
395      *
396      * @param stored_file $file information for existing file
397      * @param array $options array of options to pass. can contain:
398      *              attributes => hash of existing html attributes (eg title, height, width, etc)
399      * @return string
400      */
401     public static function file_output($file, $options=null) {
402         $path = self::get_file_directory() . $file->get_filename();
403         $attributes = array();
404         if (!empty($options['attributes']) && is_array($options['attributes'])) {
405             $attributes = $options['attributes'];
406         }
407         return self::make_tag($file, $path, $attributes);
408     }
410     /**
411      * Whether this format conflicts with the given format.
412      * This is used for the case where an export location
413      * "generally" supports something like FORMAT_PLAINHTML
414      * but then in a specific export case, must add attachments,
415      * which means that FORMAT_RICHHTML is supported in that case,
416      * which implies removing support for FORMAT_PLAINHTML.
417      * Note that conflicts don't have to be bi-directional
418      * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
419      * but not the other way around) and things within the class hierarchy
420      * are resolved automatically anyway.
421      * This is really just between subclasses of format_rich
422      * and subclasses of format_file.
423      *
424      * @todo MDL-31305 - revisit the conflict with file, since we zip here
425      * @param string $format one of the FORMAT_XX constants
426      * @return bool
427      */
428     public static function conflicts($format) { // TODO revisit the conflict with file, since we zip here
429         return ($format == PORTFOLIO_FORMAT_PLAINHTML || $format == PORTFOLIO_FORMAT_FILE);
430     }
434 /**
435  * Class used for leap2a format
436  *
437  * @package core_portfolio
438  * @category portfolio
439  * @copyright 2009 Penny Leach
440  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
441  */
442 class portfolio_format_leap2a extends portfolio_format_rich {
444     /**
445      * For multipart formats, eg html with attachments,
446      * we need to have a directory to place associated files from
447      * inside the zip file. this is the name of that directory
448      *
449      * @return string
450      */
451     public static function get_file_directory() {
452         return 'files/';
453     }
455     /**
456      * Return the file prefix
457      *
458      * @return string
459      */
460     public static function file_id_prefix() {
461         return 'storedfile';
462     }
464     /**
465      * Return the link to a file
466      *
467      * @param stored_file $file information for existing file
468      * @param array $options array of options to pass. can contain:
469      *              attributes => hash of existing html attributes (eg title, height, width, etc)
470      * @return string
471      */
472     public static function file_output($file, $options=null) {
473         $id = '';
474         if (!is_array($options)) {
475             $options = array();
476         }
477         if (!array_key_exists('entry', $options)) {
478             $options['entry'] = true;
479         }
480         if (!empty($options['entry'])) {
481             $path = 'portfolio:' . self::file_id_prefix() . $file->get_id();
482         } else {
483             $path = self::get_file_directory() . $file->get_filename();
484         }
485         $attributes = array();
486         if (!empty($options['attributes']) && is_array($options['attributes'])) {
487             $attributes = $options['attributes'];
488         }
489         $attributes['rel']    = 'enclosure';
490         return self::make_tag($file, $path, $attributes);
491     }
493     /**
494      * Generate portfolio_format_leap2a
495      *
496      * @param stdclass $user user information object
497      * @return portfolio_format_leap2a_writer
498      */
499     public static function leap2a_writer(stdclass $user=null) {
500         global $CFG;
501         if (empty($user)) {
502             global $USER;
503             $user = $USER;
504         }
505         require_once($CFG->libdir . '/portfolio/formats/leap2a/lib.php');
506         return new portfolio_format_leap2a_writer($user);
507     }
509     /**
510      * Return the manifest name
511      *
512      * @return string
513      */
514     public static function manifest_name() {
515         return 'leap2a.xml';
516     }
520 // later.... a moodle plugin might support this.
521 // it's commented out in portfolio_supported_formats so cannot currently be used.
522 //class portfolio_format_mbkp extends portfolio_format_rich {}
524 /**
525  * 'PDF format', subtype of file.
526  *
527  * For portfolio plugins that support PDFs specifically.
528  *
529  * @package core_portfolio
530  * @category portfolio
531  * @copyright 2009 Dan Poltawski
532  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
533  */
534 class portfolio_format_pdf extends portfolio_format_file {
536     /**
537      * Return pdf mimetypes
538      *
539      * @return array
540      */
541     public static function mimetypes() {
542         return array('application/pdf');
543     }
546 /**
547  * 'Document format', subtype of file.
548  *
549  * For portfolio plugins that support documents specifically.
550  *
551  * @package core_portfolio
552  * @category portfolio
553  * @copyright 2009 Dan Poltawski
554  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
555  */
556 class portfolio_format_document extends portfolio_format_file {
558     /**
559      * Return documents mimetypes
560      *
561      * @return array of documents mimetypes
562      */
563     public static function mimetypes() {
564         return array_merge(
565             array('text/plain', 'text/rtf'),
566             mimeinfo_from_icon('type', 'word', true),
567             mimeinfo_from_icon('type', 'docx', true),
568             mimeinfo_from_icon('type', 'odt', true)
569         );
570     }
573 /**
574  * 'Spreadsheet format', subtype of file.
575  *
576  * For portfolio plugins that support spreadsheets specifically.
577  *
578  * @package core_portfolio
579  * @category portfolio
580  * @copyright 2009 Dan Poltawski
581  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
582  */
583 class portfolio_format_spreadsheet extends portfolio_format_file {
585     /**
586      * Return spreadsheet spreadsheet mimetypes
587      *
588      * @return array of documents mimetypes
589      */
590     public static function mimetypes() {
591         return array_merge(
592             mimeinfo_from_icon('type', 'excel', true),
593             mimeinfo_from_icon('type', 'xlsm', true),
594             mimeinfo_from_icon('type', 'ods', true)
595         );
596     }
599 /**
600  * 'Presentation format', subtype of file.
601  *
602  * For portfolio plugins that support presentation specifically.
603  *
604  * @package core_portfolio
605  * @category portfolio
606  * @copyright 2009 Dan Poltawski
607  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
608  */
609 class portfolio_format_presentation extends portfolio_format_file {
611     /**
612      * Return presentation documents mimetypes
613      *
614      * @return array presentation document mimetypes
615      */
616     public static function mimetypes() {
617         return mimeinfo_from_icon('type', 'powerpoint', true);
618     }