Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.0.x will end 8 May 2023 (12 months).
  • Bug fixes for security issues in 4.0.x will end 13 November 2023 (18 months).
  • PHP version: minimum PHP 7.3.0 Note: the minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is also supported.

Differences Between: [Versions 400 and 402] [Versions 400 and 403]

   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/>.
  16  
  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   */
  28  
  29  defined('MOODLE_INTERNAL') || die();
  30  
  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 {
  44  
  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      }
  53  
  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      }
  64  
  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      }
  82  
  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          }
 100  
 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          }
 109  
 110          foreach ($attributes as $key => $value) {
 111              $elem->setAttribute($key, $value);
 112          }
 113          $dom->appendChild($elem);
 114          return $dom->saveXML($elem);
 115      }
 116  
 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      }
 137  }
 138  
 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 {
 148  
 149      /**
 150       * Array of mimetypes this format supports
 151       *
 152       * @return array
 153       */
 154      public static function mimetypes() {
 155          return array();
 156      }
 157  
 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      }
 168  
 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      }
 184  }
 185  
 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 file_get_typegroup('type', 'image');
 202      }
 203  
 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      }
 225  }
 226  
 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 {
 238  
 239      /**
 240       * Return html mimetype
 241       *
 242       * @return array
 243       */
 244      public static function mimetypes() {
 245          return array('text/html');
 246      }
 247  
 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      }
 269  }
 270  
 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 {
 282  
 283       /**
 284        * Return video mimetypes
 285        *
 286        * @return array
 287        */
 288      public static function mimetypes() {
 289          return file_get_typegroup('type', 'video');
 290      }
 291  }
 292  
 293  /**
 294   * Class for plain text format.
 295   *
 296   * Not sure why we would need this yet,
 297   * but since resource module wants to export it... we can
 298   *
 299   * @package core_portfolio
 300   * @category portfolio
 301   * @copyright 2008 Penny Leach
 302   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 303   */
 304  class portfolio_format_text extends portfolio_format_file {
 305  
 306      /**
 307       * Return plain text mimetypes
 308       *
 309       * @return array
 310       */
 311      public static function mimetypes() {
 312          return array('text/plain');
 313      }
 314  
 315      /**
 316       * Whether this format conflicts with the given format.
 317       * This is used for the case where an export location
 318       * "generally" supports something like FORMAT_PLAINHTML
 319       * but then in a specific export case, must add attachments,
 320       * which means that FORMAT_RICHHTML is supported in that case,
 321       * which implies removing support for FORMAT_PLAINHTML.
 322       * Note that conflicts don't have to be bi-directional
 323       * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
 324       * but not the other way around) and things within the class hierarchy
 325       * are resolved automatically anyway.
 326       * This is really just between subclasses of format_rich
 327       * and subclasses of format_file.
 328       *
 329       * @param string $format one of the FORMAT_XX constants
 330       * @return bool
 331       */
 332      public static function conflicts($format ) {
 333          return ($format == PORTFOLIO_FORMAT_PLAINHTML
 334              || $format == PORTFOLIO_FORMAT_RICHHTML);
 335      }
 336  }
 337  
 338  /**
 339   * Base class for rich formats.
 340   *
 341   * These are multipart - eg things with attachments
 342   *
 343   * @package core_portfolio
 344   * @category portfolio
 345   * @copyright 2009 Penny Leach
 346   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 347   */
 348  abstract class portfolio_format_rich extends portfolio_format {
 349  
 350      /**
 351       * Return rich text mimetypes
 352       *
 353       * @return array
 354       */
 355      public static function mimetypes() {
 356          return array();
 357      }
 358  
 359  }
 360  
 361  /**
 362   * Richhtml - html with attachments.
 363   *
 364   * The most commonly used rich format
 365   * eg inline images
 366   *
 367   * @package core_portfolio
 368   * @category portfolio
 369   * @copyright 2009 Penny Leach
 370   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 371   */
 372  class portfolio_format_richhtml extends portfolio_format_rich {
 373  
 374      /**
 375       * For multipart formats, eg html with attachments,
 376       * we need to have a directory to place associated files from
 377       * inside the zip file. this is the name of that directory
 378       *
 379       * @return string
 380       */
 381      public static function get_file_directory() {
 382          return 'site_files/';
 383      }
 384  
 385      /**
 386       * Given a file, return a snippet of markup in whatever format
 387       * to link to that file.
 388       * Usually involves the path given by get_file_directory.
 389       * This is not supported in subclasses of portfolio_format_file
 390       * since they're all just single files.
 391       * @see get_file_directory
 392       *
 393       * @param stored_file $file information for existing file
 394       * @param array $options array of options to pass. can contain:
 395       *              attributes => hash of existing html attributes (eg title, height, width, etc)
 396       * @return string
 397       */
 398      public static function file_output($file, $options=null) {
 399          $path = self::get_file_directory() . $file->get_filename();
 400          $attributes = array();
 401          if (!empty($options['attributes']) && is_array($options['attributes'])) {
 402              $attributes = $options['attributes'];
 403          }
 404          return self::make_tag($file, $path, $attributes);
 405      }
 406  
 407      /**
 408       * Whether this format conflicts with the given format.
 409       * This is used for the case where an export location
 410       * "generally" supports something like FORMAT_PLAINHTML
 411       * but then in a specific export case, must add attachments,
 412       * which means that FORMAT_RICHHTML is supported in that case,
 413       * which implies removing support for FORMAT_PLAINHTML.
 414       * Note that conflicts don't have to be bi-directional
 415       * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
 416       * but not the other way around) and things within the class hierarchy
 417       * are resolved automatically anyway.
 418       * This is really just between subclasses of format_rich
 419       * and subclasses of format_file.
 420       *
 421       * @todo MDL-31305 - revisit the conflict with file, since we zip here
 422       * @param string $format one of the FORMAT_XX constants
 423       * @return bool
 424       */
 425      public static function conflicts($format) { // TODO revisit the conflict with file, since we zip here
 426          return ($format == PORTFOLIO_FORMAT_PLAINHTML || $format == PORTFOLIO_FORMAT_FILE);
 427      }
 428  
 429  }
 430  
 431  /**
 432   * Class used for leap2a format
 433   *
 434   * @package core_portfolio
 435   * @category portfolio
 436   * @copyright 2009 Penny Leach
 437   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 438   */
 439  class portfolio_format_leap2a extends portfolio_format_rich {
 440  
 441      /**
 442       * For multipart formats, eg html with attachments,
 443       * we need to have a directory to place associated files from
 444       * inside the zip file. this is the name of that directory
 445       *
 446       * @return string
 447       */
 448      public static function get_file_directory() {
 449          return 'files/';
 450      }
 451  
 452      /**
 453       * Return the file prefix
 454       *
 455       * @return string
 456       */
 457      public static function file_id_prefix() {
 458          return 'storedfile';
 459      }
 460  
 461      /**
 462       * Return the link to a file
 463       *
 464       * @param stored_file $file information for existing file
 465       * @param array $options array of options to pass. can contain:
 466       *              attributes => hash of existing html attributes (eg title, height, width, etc)
 467       * @return string
 468       */
 469      public static function file_output($file, $options=null) {
 470          $id = '';
 471          if (!is_array($options)) {
 472              $options = array();
 473          }
 474          if (!array_key_exists('entry', $options)) {
 475              $options['entry'] = true;
 476          }
 477          if (!empty($options['entry'])) {
 478              $path = 'portfolio:' . self::file_id_prefix() . $file->get_id();
 479          } else {
 480              $path = self::get_file_directory() . $file->get_filename();
 481          }
 482          $attributes = array();
 483          if (!empty($options['attributes']) && is_array($options['attributes'])) {
 484              $attributes = $options['attributes'];
 485          }
 486          $attributes['rel']    = 'enclosure';
 487          return self::make_tag($file, $path, $attributes);
 488      }
 489  
 490      /**
 491       * Generate portfolio_format_leap2a
 492       *
 493       * @param stdclass $user user information object
 494       * @return portfolio_format_leap2a_writer
 495       */
 496      public static function leap2a_writer(stdclass $user=null) {
 497          global $CFG;
 498          if (empty($user)) {
 499              global $USER;
 500              $user = $USER;
 501          }
 502          require_once($CFG->libdir . '/portfolio/formats/leap2a/lib.php');
 503          return new portfolio_format_leap2a_writer($user);
 504      }
 505  
 506      /**
 507       * Return the manifest name
 508       *
 509       * @return string
 510       */
 511      public static function manifest_name() {
 512          return 'leap2a.xml';
 513      }
 514  }
 515  
 516  
 517  // later.... a moodle plugin might support this.
 518  // it's commented out in portfolio_supported_formats so cannot currently be used.
 519  //class portfolio_format_mbkp extends portfolio_format_rich {}
 520  
 521  /**
 522   * 'PDF format', subtype of file.
 523   *
 524   * For portfolio plugins that support PDFs specifically.
 525   *
 526   * @package core_portfolio
 527   * @category portfolio
 528   * @copyright 2009 Dan Poltawski
 529   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 530   */
 531  class portfolio_format_pdf extends portfolio_format_file {
 532  
 533      /**
 534       * Return pdf mimetypes
 535       *
 536       * @return array
 537       */
 538      public static function mimetypes() {
 539          return array('application/pdf');
 540      }
 541  }
 542  
 543  /**
 544   * 'Document format', subtype of file.
 545   *
 546   * For portfolio plugins that support documents specifically.
 547   *
 548   * @package core_portfolio
 549   * @category portfolio
 550   * @copyright 2009 Dan Poltawski
 551   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 552   */
 553  class portfolio_format_document extends portfolio_format_file {
 554  
 555      /**
 556       * Return documents mimetypes
 557       *
 558       * @return array of documents mimetypes
 559       */
 560      public static function mimetypes() {
 561          return file_get_typegroup('type', 'document');
 562      }
 563  }
 564  
 565  /**
 566   * 'Spreadsheet format', subtype of file.
 567   *
 568   * For portfolio plugins that support spreadsheets specifically.
 569   *
 570   * @package core_portfolio
 571   * @category portfolio
 572   * @copyright 2009 Dan Poltawski
 573   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 574   */
 575  class portfolio_format_spreadsheet extends portfolio_format_file {
 576  
 577      /**
 578       * Return spreadsheet spreadsheet mimetypes
 579       *
 580       * @return array of documents mimetypes
 581       */
 582      public static function mimetypes() {
 583          return file_get_typegroup('type', 'spreadsheet');
 584      }
 585  }
 586  
 587  /**
 588   * 'Presentation format', subtype of file.
 589   *
 590   * For portfolio plugins that support presentation specifically.
 591   *
 592   * @package core_portfolio
 593   * @category portfolio
 594   * @copyright 2009 Dan Poltawski
 595   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 596   */
 597  class portfolio_format_presentation extends portfolio_format_file {
 598  
 599      /**
 600       * Return presentation documents mimetypes
 601       *
 602       * @return array presentation document mimetypes
 603       */
 604      public static function mimetypes() {
 605          return file_get_typegroup('type', 'presentation');
 606      }
 607  }