57e8a89337e8f2cfa1d63d9a4a77db91ae9d0d1a
[moodle.git] / lib / portfolio / formats / leap2a / lib.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 the LEAP2a writer used by portfolio_format_leap2a
19  *
20  * @package core_portfolio
21  * @copyright 2009 Penny Leach (penny@liip.ch), Martin Dougiamas
22  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  *
24  */
26 defined('MOODLE_INTERNAL') || die();
28 /**
29  * Object to encapsulate the writing of leap2a.
30  * Should be used like:
31  * $writer = portfolio_format_leap2a::leap2a_writer($USER);
32  * $entry = new portfolio_format_leap2a_entry('forumpost6', $title, 'leap2', 'somecontent')
33  * $entry->add_link('something', 'has_part')->add_link('somethingelse', 'has_part');
34  * .. etc
35  * $writer->add_entry($entry);
36  * $xmlstr = $writer->to_xml();
37  *
38  * @todo MDL-31287 - find a way to ensure that all referenced files are included
39  * @package core_portfolio
40  * @category portfolio
41  * @copyright 2009 Penny Leach
42  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
43  */
44 class portfolio_format_leap2a_writer {
46     /** @var DomDocument the domdocument object used to create elements */
47     private $dom;
49     /** @var DOMElement the top level feed element */
50     private $feed;
52     /** @var stdClass the user exporting data */
53     private $user;
55     /** @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 */
56     private $id;
58     /** @var array the entries for the feed - keyed on id */
59     private $entries = array();
61     /**
62      * Constructor - usually generated from portfolio_format_leap2a::leap2a_writer($USER);
63      *
64      * @todo MDL-31302 - add exporter and format
65      * @param stdclass $user the user exporting (almost always $USER)
66      */
67     public function __construct(stdclass $user) { // todo something else - exporter, format, etc
68         global $CFG;
69         $this->user = $user;
70         $this->exporttime = time();
71         $this->id = $CFG->wwwroot . '/portfolio/export/leap2a/' . $this->user->id . '/' . $this->exporttime;
73         $this->dom = new DomDocument('1.0', 'utf-8');
75         $this->feed = $this->dom->createElement('feed');
76         $this->feed->setAttribute('xmlns', 'http://www.w3.org/2005/Atom');
77         $this->feed->setAttribute('xmlns:rdf', 'http://www.w3.org/1999/02/22-rdf-syntax-ns#');
78         $this->feed->setAttribute('xmlns:leap2', 'http://terms.leapspecs.org/');
79         $this->feed->setAttribute('xmlns:categories', 'http://wiki.leapspecs.org/2A/categories');
80         $this->feed->setAttribute('xmlns:portfolio', $this->id); // this is just a ns for ids of elements for convenience
82         $this->dom->appendChild($this->feed);
84         $this->feed->appendChild($this->dom->createElement('id', $this->id));
85         $this->feed->appendChild($this->dom->createElement('title', get_string('leap2a_feedtitle', 'portfolio', fullname($this->user))));
86         $this->feed->appendChild($this->dom->createElement('leap2:version', 'http://www.leapspecs.org/2010-07/2A/'));
89         $generator = $this->dom->createElement('generator', 'Moodle');
90         $generator->setAttribute('uri', $CFG->wwwroot);
91         $generator->setAttribute('version', $CFG->version);
93         $this->feed->appendChild($generator);
95         $author = $this->dom->createElement('author');
96         $author->appendChild($this->dom->createElement('name', fullname($this->user)));
97         $author->appendChild($this->dom->createElement('email', $this->user->email));
98         $author->appendChild($this->dom->CreateElement('uri', $CFG->wwwroot . '/user/view.php?id=' . $this->user->id));
100         $this->feed->appendChild($author);
101         // header done, we can start appending entry elements now
102     }
104     /**
105      * Adds a entry to the feed ready to be exported
106      *
107      * @param portfolio_format_leap2a_entry $entry new feed entry to add
108      * @return portfolio_format_leap2a_entry
109      */
110     public function add_entry(portfolio_format_leap2a_entry $entry) {
111         if (array_key_exists($entry->id, $this->entries)) {
112             if (!($entry instanceof portfolio_format_leap2a_file)) {
113                 throw new portfolio_format_leap2a_exception('leap2a_entryalreadyexists', 'portfolio', '', $entry->id);
114             }
115         }
116         $this->entries[$entry->id] =  $entry;
117         return $entry;
118     }
120     /**
121      * Select an entry that has previously been added into the feed
122      *
123      * @param portfolio_format_leap2a_entry|string $selectionentry the entry to make a selection (id or entry object)
124      * @param array $ids array of ids this selection includes
125      * @param string $selectiontype for selection type, see: http://wiki.cetis.ac.uk/2009-03/LEAP2A_categories/selection_type
126      */
127     public function make_selection($selectionentry, $ids, $selectiontype) {
128         $selectionid = null;
129         if ($selectionentry instanceof portfolio_format_leap2a_entry) {
130             $selectionid = $selectionentry->id;
131         } else if (is_string($selectionentry)) {
132             $selectionid = $selectionentry;
133         }
134         if (!array_key_exists($selectionid, $this->entries)) {
135             throw new portfolio_format_leap2a_exception('leap2a_invalidentryid', 'portfolio', '', $selectionid);
136         }
137         foreach ($ids as $entryid) {
138             if (!array_key_exists($entryid, $this->entries)) {
139                 throw new portfolio_format_leap2a_exception('leap2a_invalidentryid', 'portfolio', '', $entryid);
140             }
141             $this->entries[$selectionid]->add_link($entryid, 'has_part');
142             $this->entries[$entryid]->add_link($selectionid, 'is_part_of');
143         }
144         $this->entries[$selectionid]->add_category($selectiontype, 'selection_type');
145         if ($this->entries[$selectionid]->type != 'selection') {
146             debugging(get_string('leap2a_overwritingselection', 'portfolio', $this->entries[$selectionid]->type));
147             $this->entries[$selectionid]->type = 'selection';
148         }
149     }
151     /**
152      * Helper function to link some stored_files into the feed and link them to a particular entry
153      *
154      * @param portfolio_format_leap2a_entry $entry feed object
155      * @param array $files array of stored_files to link
156      */
157     public function link_files($entry, $files) {
158         foreach ($files as $file) {
159             $fileentry = new portfolio_format_leap2a_file($file->get_filename(), $file);
160             $this->add_entry($fileentry);
161             $entry->add_link($fileentry, 'related');
162             $fileentry->add_link($entry, 'related');
163         }
164     }
166     /**
167      * Validate the feed and all entries
168      */
169     private function validate() {
170         foreach ($this->entries as $entry) {
171             // first call the entry's own validation method
172             // which will throw an exception if there's anything wrong
173             $entry->validate();
174             // now make sure that all links are in place
175             foreach ($entry->links as $linkedid => $rel) {
176                 // the linked to entry exists
177                 if (!array_key_exists($linkedid, $this->entries)) {
178                     $a = (object)array('rel' => $rel->type, 'to' => $linkedid, 'from' => $entry->id);
179                     throw new portfolio_format_leap2a_exception('leap2a_nonexistantlink', 'portfolio', '', $a);
180                 }
181                 // and contains a link back to us
182                 if (!array_key_exists($entry->id, $this->entries[$linkedid]->links)) {
184                 }
185                 // we could later check that the reltypes were properly inverse, but nevermind for now.
186             }
187         }
188     }
190     /**
191      * Return the entire feed as a string.
192      * Then, it calls for validation
193      *
194      * @return string feeds' content in xml
195      */
196     public function to_xml() {
197         $this->validate();
198         foreach ($this->entries as $entry) {
199             $entry->id = 'portfolio:' . $entry->id;
200             $this->feed->appendChild($entry->to_dom($this->dom, $this->user));
201         }
202         return $this->dom->saveXML();
203     }
206 /**
207  * This class represents a single leap2a entry.
208  * You can create these directly and then add them to the main leap feed object
209  *
210  * @package core_portfolio
211  * @category portfolio
212  * @copyright 2009 Penny Leach
213  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
214  */
215 class portfolio_format_leap2a_entry {
217     /** @var string entry id  - something like forumpost6, must be unique to the feed */
218     public $id;
220     /** @var string title of the entry */
221     public $title;
223     /** @var string leap2a entry type */
224     public $type;
226     /** @var string optional author (only if different to feed author) */
227     public $author;
229     /** @var string summary - for split long content */
230     public $summary;
232     /** @var mixed main content of the entry. can be html,text,or xhtml. for a stored_file, use portfolio_format_leap2a_file **/
233     public $content;
235     /** @var int updated date - unix timestamp */
236     public $updated;
238     /** @var int published date (ctime) - unix timestamp */
239     public $published;
241     /** @var array the required fields for a leap2a entry */
242     private $requiredfields = array( 'id', 'title', 'type');
244     /** @var array extra fields which usually should be set (except author) but are not required */
245     private $optionalfields = array('author', 'updated', 'published', 'content', 'summary');
247     /** @var array links from this entry to other entries */
248     public $links       = array();
250     /** @var array attachments to this entry */
251     public $attachments = array();
253     /** @var array categories for this entry */
254     private $categories = array();
256     /**
257      * Constructor.  All arguments are required (and will be validated)
258      * http://wiki.cetis.ac.uk/2009-03/LEAP2A_types
259      *
260      * @param string $id unique id of this entry.
261      *                   could be something like forumpost6 for example.
262      *                   This <b>must</b> be unique to the entire feed.
263      * @param string $title title of the entry. This is pure atom.
264      * @param string $type the leap type of this entry.
265      * @param mixed $content the content of the entry. string (xhtml/html/text)
266      */
267     public function __construct($id, $title, $type, $content=null) {
268         $this->id    = $id;
269         $this->title = $title;
270         $this->type  = $type;
271         $this->content = $this->__set('content', $content);
273     }
275     /**
276      * Override __set to do proper dispatching for different things.
277      * Only allows the optional and required leap2a entry fields to be set
278      *
279      * @param string $field property's name
280      * @param mixed $value property's value
281      * @return mixed
282      */
283     public function __set($field, $value) {
284         // detect the case where content is being set to be a file directly
285         if ($field == 'content' && $value instanceof stored_file) {
286             throw new portfolio_format_leap2a_exception('leap2a_filecontent', 'portfolio');
287         }
288         if (in_array($field, $this->requiredfields) || in_array($field, $this->optionalfields)) {
289             return $this->{$field} = $value;
290         }
291         throw new portfolio_format_leap2a_exception('leap2a_invalidentryfield', 'portfolio', '', $field);
292     }
295     /**
296      * Validate this entry.
297      * At the moment this just makes sure required fields exist
298      * but it could also check things against a list, for example
299      *
300      * @todo MDL-31303 - add category with a scheme 'selection_type'
301      */
302     public function validate() {
303         foreach ($this->requiredfields as $key) {
304             if (empty($this->{$key})) {
305                 throw new portfolio_format_leap2a_exception('leap2a_missingfield', 'portfolio', '', $key);
306             }
307         }
308         if ($this->type == 'selection') {
309             if (count($this->links) == 0) {
310                 throw new portfolio_format_leap2a_exception('leap2a_emptyselection', 'portfolio');
311             }
312             //TODO make sure we have a category with a scheme 'selection_type'
313         }
314     }
316     /**
317      * Add a link from this entry to another one.
318      * These will be collated at the end of the export (during to_xml)
319      * and validated at that point. This function does no validation
320      * {@link http://wiki.cetis.ac.uk/2009-03/LEAP2A_relationships}
321      *
322      * @param portfolio_format_leap2a_entry|string $otherentry portfolio_format_leap2a_entry or its id
323      * @param string $reltype (no leap2: ns required)
324      * @param string $displayorder (optional)
325      * @return portfolio_format_leap2a_entry the current entry object. This is so that these calls can be chained
326      *                                       eg $entry->add_link('something6', 'has_part')->add_link('something7',
327      *                                       'has_part');
328      */
329     public function add_link($otherentry, $reltype, $displayorder=null) {
330         if ($otherentry instanceof portfolio_format_leap2a_entry) {
331             $otherentry = $otherentry->id;
332         }
333         if ($otherentry == $this->id) {
334             throw new portfolio_format_leap2a_exception('leap2a_selflink', 'portfolio', '', (object)array('rel' => $reltype, 'id' => $this->id));
335         }
336         // add on the leap2: ns if required
337         if (!in_array($reltype, array('related', 'alternate', 'enclosure'))) {
338             $reltype = 'leap2:' . $reltype;
339         }
341         $this->links[$otherentry] = (object)array('rel' => $reltype, 'order' => $displayorder);
343         return $this;
344     }
346     /**
347      * Add a category to this entry
348      * {@link http://wiki.cetis.ac.uk/2009-03/LEAP2A_categories}
349      * "tags" should just pass a term here and no scheme or label.
350      * They will be automatically normalised if they have spaces.
351      *
352      * @param string $term eg 'Offline'
353      * @param string $scheme (optional) eg resource_type
354      * @param string $label (optional) eg File
355      */
356     public function add_category($term, $scheme=null, $label=null) {
357         // "normalise" terms and set their label if they have spaces
358         // see http://wiki.cetis.ac.uk/2009-03/LEAP2A_categories#Plain_tags for more information
359         if (empty($scheme) && strpos($term, ' ') !== false) {
360             $label = $term;
361             $term = str_replace(' ', '-', $term);
362         }
363         $this->categories[] = (object)array(
364             'term'   => $term,
365             'scheme' => $scheme,
366             'label'  => $label,
367         );
368     }
370     /**
371      * Create an entry element and append all the children
372      * And return it rather than adding it to the dom.
373      * This is handled by the main writer object.
374      *
375      * @param DomDocument $dom use this to create elements
376      * @param stdClass $feedauthor object of author(user) info
377      * @return DOMDocument
378      */
379     public function to_dom(DomDocument $dom, $feedauthor) {
380         $entry = $dom->createElement('entry');
381         $entry->appendChild($dom->createElement('id', $this->id));
382         $entry->appendChild($dom->createElement('title', $this->title));
383         if ($this->author && $this->author->id != $feedauthor->id) {
384             $author = $dom->createElement('author');
385             $author->appendChild($dom->createElement('name', fullname($this->author)));
386             $entry->appendChild($author);
387         }
388         // selectively add uncomplicated optional elements
389         foreach (array('updated', 'published') as $field) {
390             if ($this->{$field}) {
391                 $date = date(DATE_ATOM, $this->{$field});
392                 $entry->appendChild($dom->createElement($field, $date));
393             }
394         }
395         if (empty($this->content)) {
396             $entry->appendChild($dom->createElement('content'));
397         } else {
398             $content = $this->create_xhtmlish_element($dom, 'content', $this->content);
399             $entry->appendChild($content);
400         }
402         if (!empty($this->summary)) {
403             $summary = $this->create_xhtmlish_element($dom, 'summary', $this->summary);
404             $entry->appendChild($summary);
405         }
407         $type = $dom->createElement('rdf:type');
408         $type->setAttribute('rdf:resource', 'leap2:' . $this->type);
409         $entry->appendChild($type);
411         foreach ($this->links as $otherentry => $l) {
412             $link = $dom->createElement('link');
413             $link->setAttribute('rel',  $l->rel);
414             $link->setAttribute('href', 'portfolio:' . $otherentry);
415             if ($l->order) {
416                 $link->setAttribute('leap2:display_order', $l->order);
417             }
418             $entry->appendChild($link);
419         }
421         $this->add_extra_links($dom, $entry); // hook for subclass
423         foreach ($this->categories as $category) {
424             $cat = $dom->createElement('category');
425             $cat->setAttribute('term', $category->term);
426             if ($category->scheme) {
427                 $cat->setAttribute('scheme', 'categories:' .$category->scheme . '#');
428             }
429             if ($category->label && $category->label != $category->term) {
430                 $cat->setAttribute('label', $category->label);
431             }
432             $entry->appendChild($cat);
433         }
434         return $entry;
435     }
437     /**
438      * Try to load whatever is in $content into xhtml and add it to the dom.
439      * Failing that, load the html, escape it, and set it as the body of the tag.
440      * Either way it sets the type attribute of the top level element.
441      * Moodle should always provide xhtml content, but user-defined content can't be trusted
442      *
443      * @todo MDL-31304 - convert <html><body> </body></html> to xml
444      * @param DomDocument $dom the dom doc to use
445      * @param string $tagname usually 'content' or 'summary'
446      * @param string $content the content to use, either xhtml or html.
447      * @return DomDocument
448      */
449     private function create_xhtmlish_element(DomDocument $dom, $tagname, $content) {
450         $topel = $dom->createElement($tagname);
451         $maybexml = true;
452         if (strpos($content, '<') === false && strpos($content, '>') === false) {
453             $maybexml = false;
454         }
455         // try to load content as xml
456         $tmp = new DomDocument();
457         if ($maybexml && @$tmp->loadXML('<div>' . $content . '</div>')) {
458             $topel->setAttribute('type', 'xhtml');
459             $content = $dom->importNode($tmp->documentElement, true);
460             $content->setAttribute('xmlns', 'http://www.w3.org/1999/xhtml');
461             $topel->appendChild($content);
462         // if that fails, it could still be html
463         } else if ($maybexml && @$tmp->loadHTML($content)) {
464             $topel->setAttribute('type', 'html');
465             $topel->nodeValue = $content;
466             // TODO figure out how to convert this to xml
467             // TODO because we end up with <html><body> </body></html> wrapped around it
468             // which is annoying
469         // either we already know it's text from the first check
470         // or nothing else has worked anyway
471         } else {
472             $topel->nodeValue = $content;
473             $topel->setAttribute('type', 'text');
474             return $topel;
475         }
476         return $topel;
477     }
479     /**
480      * Hook function for subclasses to add extra links (like for files)
481      */
482     protected function add_extra_links() {}
485 /**
486  * Subclass of entry, purely for dealing with files
487  *
488  * @package core_portfolio
489  * @category portfolio
490  * @copyright 2009 Penny Leach
491  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
492  */
493 class portfolio_format_leap2a_file extends portfolio_format_leap2a_entry {
495     /** @var file_stored for the dealing file */
496     protected $referencedfile;
498     /**
499      * Overridden constructor to set up the file.
500      *
501      * @param string $title title of the entry
502      * @param stored_file $file file storage instance
503      */
504     public function __construct($title, stored_file $file) {
505         $id = portfolio_format_leap2a::file_id_prefix() . $file->get_id();
506         parent::__construct($id, $title, 'resource');
507         $this->referencedfile = $file;
508         $this->published = $this->referencedfile->get_timecreated();
509         $this->updated = $this->referencedfile->get_timemodified();
510         $this->add_category('offline', 'resource_type');
511     }
513     /**
514      * Implement the hook to add extra links to attach the file in an enclosure
515      *
516      * @param DomDocument $dom feed object
517      * @param DomDocument $entry feed added link
518      */
519     protected function add_extra_links($dom, $entry) {
520         $link = $dom->createElement('link');
521         $link->setAttribute('rel',  'enclosure');
522         $link->setAttribute('href', portfolio_format_leap2a::get_file_directory() . $this->referencedfile->get_filename());
523         $link->setAttribute('length', $this->referencedfile->get_filesize());
524         $link->setAttribute('type', $this->referencedfile->get_mimetype());
525         $entry->appendChild($link);
526     }