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