/libraries/joomla/document/document.php
PHP | 1068 lines | 397 code | 117 blank | 554 comment | 36 complexity | 4e084d7ac12e115688702115c088bafa MD5 | raw file
1<?php 2/** 3 * @package Joomla.Platform 4 * @subpackage Document 5 * 6 * @copyright Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved. 7 * @license GNU General Public License version 2 or later; see LICENSE 8 */ 9 10defined('JPATH_PLATFORM') or die; 11 12/** 13 * Document class, provides an easy interface to parse and display a document 14 * 15 * @since 11.1 16 */ 17class JDocument 18{ 19 /** 20 * Document title 21 * 22 * @var string 23 * @since 11.1 24 */ 25 public $title = ''; 26 27 /** 28 * Document description 29 * 30 * @var string 31 * @since 11.1 32 */ 33 public $description = ''; 34 35 /** 36 * Document full URL 37 * 38 * @var string 39 * @since 11.1 40 */ 41 public $link = ''; 42 43 /** 44 * Document base URL 45 * 46 * @var string 47 * @since 11.1 48 */ 49 public $base = ''; 50 51 /** 52 * Contains the document language setting 53 * 54 * @var string 55 * @since 11.1 56 */ 57 public $language = 'en-gb'; 58 59 /** 60 * Contains the document direction setting 61 * 62 * @var string 63 * @since 11.1 64 */ 65 public $direction = 'ltr'; 66 67 /** 68 * Document generator 69 * 70 * @var string 71 */ 72 public $_generator = 'Joomla! - Open Source Content Management'; 73 74 /** 75 * Document modified date 76 * 77 * @var string 78 * @since 11.1 79 */ 80 public $_mdate = ''; 81 82 /** 83 * Tab string 84 * 85 * @var string 86 * @since 11.1 87 */ 88 public $_tab = "\11"; 89 90 /** 91 * Contains the line end string 92 * 93 * @var string 94 * @since 11.1 95 */ 96 public $_lineEnd = "\12"; 97 98 /** 99 * Contains the character encoding string 100 * 101 * @var string 102 * @since 11.1 103 */ 104 public $_charset = 'utf-8'; 105 106 /** 107 * Document mime type 108 * 109 * @var string 110 * @since 11.1 111 */ 112 public $_mime = ''; 113 114 /** 115 * Document namespace 116 * 117 * @var string 118 * @since 11.1 119 */ 120 public $_namespace = ''; 121 122 /** 123 * Document profile 124 * 125 * @var string 126 * @since 11.1 127 */ 128 public $_profile = ''; 129 130 /** 131 * Array of linked scripts 132 * 133 * @var array 134 * @since 11.1 135 */ 136 public $_scripts = array(); 137 138 /** 139 * Array of scripts placed in the header 140 * 141 * @var array 142 * @since 11.1 143 */ 144 public $_script = array(); 145 146 /** 147 * Array of linked style sheets 148 * 149 * @var array 150 * @since 11.1 151 */ 152 public $_styleSheets = array(); 153 154 /** 155 * Array of included style declarations 156 * 157 * @var array 158 * @since 11.1 159 */ 160 public $_style = array(); 161 162 /** 163 * Array of meta tags 164 * 165 * @var array 166 * @since 11.1 167 */ 168 public $_metaTags = array(); 169 170 /** 171 * The rendering engine 172 * 173 * @var object 174 * @since 11.1 175 */ 176 public $_engine = null; 177 178 /** 179 * The document type 180 * 181 * @var string 182 * @since 11.1 183 */ 184 public $_type = null; 185 186 /** 187 * Array of buffered output 188 * 189 * @var mixed (depends on the renderer) 190 * @since 11.1 191 */ 192 public static $_buffer = null; 193 194 /** 195 * JDocument instances container. 196 * 197 * @var array 198 * @since 11.3 199 */ 200 protected static $instances = array(); 201 202 /** 203 * Media version added to assets 204 * 205 * @var string 206 * @since 3.2 207 */ 208 protected $mediaVersion = null; 209 210 /** 211 * Class constructor. 212 * 213 * @param array $options Associative array of options 214 * 215 * @since 11.1 216 */ 217 public function __construct($options = array()) 218 { 219 if (array_key_exists('lineend', $options)) 220 { 221 $this->setLineEnd($options['lineend']); 222 } 223 224 if (array_key_exists('charset', $options)) 225 { 226 $this->setCharset($options['charset']); 227 } 228 229 if (array_key_exists('language', $options)) 230 { 231 $this->setLanguage($options['language']); 232 } 233 234 if (array_key_exists('direction', $options)) 235 { 236 $this->setDirection($options['direction']); 237 } 238 239 if (array_key_exists('tab', $options)) 240 { 241 $this->setTab($options['tab']); 242 } 243 244 if (array_key_exists('link', $options)) 245 { 246 $this->setLink($options['link']); 247 } 248 249 if (array_key_exists('base', $options)) 250 { 251 $this->setBase($options['base']); 252 } 253 254 if (array_key_exists('mediaversion', $options)) 255 { 256 $this->setMediaVersion($options['mediaversion']); 257 } 258 } 259 260 /** 261 * Returns the global JDocument object, only creating it 262 * if it doesn't already exist. 263 * 264 * @param string $type The document type to instantiate 265 * @param array $attributes Array of attributes 266 * 267 * @return object The document object. 268 * 269 * @since 11.1 270 * @throws RuntimeException 271 */ 272 public static function getInstance($type = 'html', $attributes = array()) 273 { 274 $signature = serialize(array($type, $attributes)); 275 276 if (empty(self::$instances[$signature])) 277 { 278 $type = preg_replace('/[^A-Z0-9_\.-]/i', '', $type); 279 $path = __DIR__ . '/' . $type . '/' . $type . '.php'; 280 $rawpath = __DIR__ . '/raw/raw.php'; 281 $ntype = null; 282 283 // Determine the path and class 284 $class = 'JDocument' . $type; 285 286 if (!class_exists($class)) 287 { 288 if (file_exists($path)) 289 { 290 require_once $path; 291 } 292 // Default to the raw format 293 elseif (file_exists($rawpath)) 294 { 295 $ntype = $type; 296 $type = 'raw'; 297 298 $class = 'JDocument' . $type; 299 300 require_once $rawpath; 301 } 302 else 303 { 304 // @codeCoverageIgnoreStart 305 throw new RuntimeException('Invalid JDocument Class', 500); 306 307 // @codeCoverageIgnoreEnd 308 } 309 } 310 311 $instance = new $class($attributes); 312 self::$instances[$signature] = $instance; 313 314 if (!is_null($ntype)) 315 { 316 // Set the type to the Document type originally requested 317 $instance->setType($ntype); 318 } 319 } 320 321 return self::$instances[$signature]; 322 } 323 324 /** 325 * Set the document type 326 * 327 * @param string $type Type document is to set to 328 * 329 * @return JDocument instance of $this to allow chaining 330 * 331 * @since 11.1 332 */ 333 public function setType($type) 334 { 335 $this->_type = $type; 336 337 return $this; 338 } 339 340 /** 341 * Returns the document type 342 * 343 * @return string 344 * 345 * @since 11.1 346 */ 347 public function getType() 348 { 349 return $this->_type; 350 } 351 352 /** 353 * Get the contents of the document buffer 354 * 355 * @return The contents of the document buffer 356 * 357 * @since 11.1 358 */ 359 public function getBuffer() 360 { 361 return self::$_buffer; 362 } 363 364 /** 365 * Set the contents of the document buffer 366 * 367 * @param string $content The content to be set in the buffer. 368 * @param array $options Array of optional elements. 369 * 370 * @return JDocument instance of $this to allow chaining 371 * 372 * @since 11.1 373 */ 374 public function setBuffer($content, $options = array()) 375 { 376 self::$_buffer = $content; 377 378 return $this; 379 } 380 381 /** 382 * Gets a meta tag. 383 * 384 * @param string $name Value of name or http-equiv tag 385 * @param boolean $httpEquiv META type "http-equiv" defaults to null 386 * 387 * @return string 388 * 389 * @since 11.1 390 */ 391 public function getMetaData($name, $httpEquiv = false) 392 { 393 if ($name == 'generator') 394 { 395 $result = $this->getGenerator(); 396 } 397 elseif ($name == 'description') 398 { 399 $result = $this->getDescription(); 400 } 401 else 402 { 403 if ($httpEquiv == true) 404 { 405 $result = @$this->_metaTags['http-equiv'][$name]; 406 } 407 else 408 { 409 $result = @$this->_metaTags['standard'][$name]; 410 } 411 } 412 413 return $result; 414 } 415 416 /** 417 * Sets or alters a meta tag. 418 * 419 * @param string $name Value of name or http-equiv tag 420 * @param string $content Value of the content tag 421 * @param boolean $http_equiv META type "http-equiv" defaults to null 422 * 423 * @return JDocument instance of $this to allow chaining 424 * 425 * @since 11.1 426 */ 427 public function setMetaData($name, $content, $http_equiv = false) 428 { 429 if ($name == 'generator') 430 { 431 $this->setGenerator($content); 432 } 433 elseif ($name == 'description') 434 { 435 $this->setDescription($content); 436 } 437 else 438 { 439 if ($http_equiv == true) 440 { 441 $this->_metaTags['http-equiv'][$name] = $content; 442 } 443 else 444 { 445 $this->_metaTags['standard'][$name] = $content; 446 } 447 } 448 449 return $this; 450 } 451 452 /** 453 * Adds a linked script to the page 454 * 455 * @param string $url URL to the linked script 456 * @param string $type Type of script. Defaults to 'text/javascript' 457 * @param boolean $defer Adds the defer attribute. 458 * @param boolean $async Adds the async attribute. 459 * 460 * @return JDocument instance of $this to allow chaining 461 * 462 * @since 11.1 463 */ 464 public function addScript($url, $type = "text/javascript", $defer = false, $async = false) 465 { 466 $this->_scripts[$url]['mime'] = $type; 467 $this->_scripts[$url]['defer'] = $defer; 468 $this->_scripts[$url]['async'] = $async; 469 470 return $this; 471 } 472 473 /** 474 * Adds a linked script to the page with a version to allow to flush it. Ex: myscript.js54771616b5bceae9df03c6173babf11d 475 * If not specified Joomla! automatically handles versioning 476 * 477 * @param string $url URL to the linked script 478 * @param string $version Version of the script 479 * @param string $type Type of script. Defaults to 'text/javascript' 480 * @param boolean $defer Adds the defer attribute. 481 * @param boolean $async [description] 482 * 483 * @return JDocument instance of $this to allow chaining 484 * 485 * @since 3.2 486 */ 487 public function addScriptVersion($url, $version = null, $type = "text/javascript", $defer = false, $async = false) 488 { 489 // Automatic version 490 if ($version === null) 491 { 492 $version = $this->getMediaVersion(); 493 } 494 495 if (!empty($version) && strpos($url, '?') === false) 496 { 497 $url .= '?' . $version; 498 } 499 500 return $this->addScript($url, $type, $defer, $async); 501 } 502 503 /** 504 * Adds a script to the page 505 * 506 * @param string $content Script 507 * @param string $type Scripting mime (defaults to 'text/javascript') 508 * 509 * @return JDocument instance of $this to allow chaining 510 * 511 * @since 11.1 512 */ 513 public function addScriptDeclaration($content, $type = 'text/javascript') 514 { 515 if (!isset($this->_script[strtolower($type)])) 516 { 517 $this->_script[strtolower($type)] = $content; 518 } 519 else 520 { 521 $this->_script[strtolower($type)] .= chr(13) . $content; 522 } 523 524 return $this; 525 } 526 527 /** 528 * Adds a linked stylesheet to the page 529 * 530 * @param string $url URL to the linked style sheet 531 * @param string $type Mime encoding type 532 * @param string $media Media type that this stylesheet applies to 533 * @param array $attribs Array of attributes 534 * 535 * @return JDocument instance of $this to allow chaining 536 * 537 * @since 11.1 538 */ 539 public function addStyleSheet($url, $type = 'text/css', $media = null, $attribs = array()) 540 { 541 $this->_styleSheets[$url]['mime'] = $type; 542 $this->_styleSheets[$url]['media'] = $media; 543 $this->_styleSheets[$url]['attribs'] = $attribs; 544 545 return $this; 546 } 547 548 /** 549 * Adds a linked stylesheet version to the page. Ex: template.css?54771616b5bceae9df03c6173babf11d 550 * If not specified Joomla! automatically handles versioning 551 * 552 * @param string $url URL to the linked style sheet 553 * @param string $version Version of the stylesheet 554 * @param string $type Mime encoding type 555 * @param string $media Media type that this stylesheet applies to 556 * @param array $attribs Array of attributes 557 * 558 * @return JDocument instance of $this to allow chaining 559 * 560 * @since 3.2 561 */ 562 public function addStyleSheetVersion($url, $version = null, $type = "text/css", $media = null, $attribs = array()) 563 { 564 // Automatic version 565 if ($version === null) 566 { 567 $version = $this->getMediaVersion(); 568 } 569 570 if (!empty($version) && strpos($url, '?') === false) 571 { 572 $url .= '?' . $version; 573 } 574 575 return $this->addStyleSheet($url, $type, $media, $attribs); 576 } 577 578 /** 579 * Adds a stylesheet declaration to the page 580 * 581 * @param string $content Style declarations 582 * @param string $type Type of stylesheet (defaults to 'text/css') 583 * 584 * @return JDocument instance of $this to allow chaining 585 * 586 * @since 11.1 587 */ 588 public function addStyleDeclaration($content, $type = 'text/css') 589 { 590 if (!isset($this->_style[strtolower($type)])) 591 { 592 $this->_style[strtolower($type)] = $content; 593 } 594 else 595 { 596 $this->_style[strtolower($type)] .= chr(13) . $content; 597 } 598 599 return $this; 600 } 601 602 /** 603 * Sets the document charset 604 * 605 * @param string $type Charset encoding string 606 * 607 * @return JDocument instance of $this to allow chaining 608 * 609 * @since 11.1 610 */ 611 public function setCharset($type = 'utf-8') 612 { 613 $this->_charset = $type; 614 615 return $this; 616 } 617 618 /** 619 * Returns the document charset encoding. 620 * 621 * @return string 622 * 623 * @since 11.1 624 */ 625 public function getCharset() 626 { 627 return $this->_charset; 628 } 629 630 /** 631 * Sets the global document language declaration. Default is English (en-gb). 632 * 633 * @param string $lang The language to be set 634 * 635 * @return JDocument instance of $this to allow chaining 636 * 637 * @since 11.1 638 */ 639 public function setLanguage($lang = "en-gb") 640 { 641 $this->language = strtolower($lang); 642 643 return $this; 644 } 645 646 /** 647 * Returns the document language. 648 * 649 * @return string 650 * 651 * @since 11.1 652 */ 653 public function getLanguage() 654 { 655 return $this->language; 656 } 657 658 /** 659 * Sets the global document direction declaration. Default is left-to-right (ltr). 660 * 661 * @param string $dir The language direction to be set 662 * 663 * @return JDocument instance of $this to allow chaining 664 * 665 * @since 11.1 666 */ 667 public function setDirection($dir = "ltr") 668 { 669 $this->direction = strtolower($dir); 670 671 return $this; 672 } 673 674 /** 675 * Returns the document direction declaration. 676 * 677 * @return string 678 * 679 * @since 11.1 680 */ 681 public function getDirection() 682 { 683 return $this->direction; 684 } 685 686 /** 687 * Sets the title of the document 688 * 689 * @param string $title The title to be set 690 * 691 * @return JDocument instance of $this to allow chaining 692 * 693 * @since 11.1 694 */ 695 public function setTitle($title) 696 { 697 $this->title = $title; 698 699 return $this; 700 } 701 702 /** 703 * Return the title of the document. 704 * 705 * @return string 706 * 707 * @since 11.1 708 */ 709 public function getTitle() 710 { 711 return $this->title; 712 } 713 714 /** 715 * Set the assets version 716 * 717 * @param string $mediaVersion Media version to use 718 * 719 * @return JDocument instance of $this to allow chaining 720 * 721 * @since 3.2 722 */ 723 public function setMediaVersion($mediaVersion) 724 { 725 $this->mediaVersion = strtolower($mediaVersion); 726 727 return $this; 728 } 729 730 /** 731 * Return the media version 732 * 733 * @return string 734 * 735 * @since 3.2 736 */ 737 public function getMediaVersion() 738 { 739 return $this->mediaVersion; 740 } 741 742 /** 743 * Sets the base URI of the document 744 * 745 * @param string $base The base URI to be set 746 * 747 * @return JDocument instance of $this to allow chaining 748 * 749 * @since 11.1 750 */ 751 public function setBase($base) 752 { 753 $this->base = $base; 754 755 return $this; 756 } 757 758 /** 759 * Return the base URI of the document. 760 * 761 * @return string 762 * 763 * @since 11.1 764 */ 765 public function getBase() 766 { 767 return $this->base; 768 } 769 770 /** 771 * Sets the description of the document 772 * 773 * @param string $description The description to set 774 * 775 * @return JDocument instance of $this to allow chaining 776 * 777 * @since 11.1 778 */ 779 public function setDescription($description) 780 { 781 $this->description = $description; 782 783 return $this; 784 } 785 786 /** 787 * Return the title of the page. 788 * 789 * @return string 790 * 791 * @since 11.1 792 */ 793 public function getDescription() 794 { 795 return $this->description; 796 } 797 798 /** 799 * Sets the document link 800 * 801 * @param string $url A url 802 * 803 * @return JDocument instance of $this to allow chaining 804 * 805 * @since 11.1 806 */ 807 public function setLink($url) 808 { 809 $this->link = $url; 810 811 return $this; 812 } 813 814 /** 815 * Returns the document base url 816 * 817 * @return string 818 * 819 * @since 11.1 820 */ 821 public function getLink() 822 { 823 return $this->link; 824 } 825 826 /** 827 * Sets the document generator 828 * 829 * @param string $generator The generator to be set 830 * 831 * @return JDocument instance of $this to allow chaining 832 * 833 * @since 11.1 834 */ 835 public function setGenerator($generator) 836 { 837 $this->_generator = $generator; 838 839 return $this; 840 } 841 842 /** 843 * Returns the document generator 844 * 845 * @return string 846 * 847 * @since 11.1 848 */ 849 public function getGenerator() 850 { 851 return $this->_generator; 852 } 853 854 /** 855 * Sets the document modified date 856 * 857 * @param string $date The date to be set 858 * 859 * @return JDocument instance of $this to allow chaining 860 * 861 * @since 11.1 862 */ 863 public function setModifiedDate($date) 864 { 865 $this->_mdate = $date; 866 867 return $this; 868 } 869 870 /** 871 * Returns the document modified date 872 * 873 * @return string 874 * 875 * @since 11.1 876 */ 877 public function getModifiedDate() 878 { 879 return $this->_mdate; 880 } 881 882 /** 883 * Sets the document MIME encoding that is sent to the browser. 884 * 885 * This usually will be text/html because most browsers cannot yet 886 * accept the proper mime settings for XHTML: application/xhtml+xml 887 * and to a lesser extent application/xml and text/xml. See the W3C note 888 * ({@link http://www.w3.org/TR/xhtml-media-types/ 889 * http://www.w3.org/TR/xhtml-media-types/}) for more details. 890 * 891 * @param string $type The document type to be sent 892 * @param boolean $sync Should the type be synced with HTML? 893 * 894 * @return JDocument instance of $this to allow chaining 895 * 896 * @since 11.1 897 * 898 * @link http://www.w3.org/TR/xhtml-media-types 899 */ 900 public function setMimeEncoding($type = 'text/html', $sync = true) 901 { 902 $this->_mime = strtolower($type); 903 904 // Syncing with meta-data 905 if ($sync) 906 { 907 $this->setMetaData('content-type', $type . '; charset=' . $this->_charset, true); 908 } 909 910 return $this; 911 } 912 913 /** 914 * Return the document MIME encoding that is sent to the browser. 915 * 916 * @return string 917 * 918 * @since 11.1 919 */ 920 public function getMimeEncoding() 921 { 922 return $this->_mime; 923 } 924 925 /** 926 * Sets the line end style to Windows, Mac, Unix or a custom string. 927 * 928 * @param string $style "win", "mac", "unix" or custom string. 929 * 930 * @return JDocument instance of $this to allow chaining 931 * 932 * @since 11.1 933 */ 934 public function setLineEnd($style) 935 { 936 switch ($style) 937 { 938 case 'win': 939 $this->_lineEnd = "\15\12"; 940 break; 941 case 'unix': 942 $this->_lineEnd = "\12"; 943 break; 944 case 'mac': 945 $this->_lineEnd = "\15"; 946 break; 947 default: 948 $this->_lineEnd = $style; 949 } 950 951 return $this; 952 } 953 954 /** 955 * Returns the lineEnd 956 * 957 * @return string 958 * 959 * @since 11.1 960 */ 961 public function _getLineEnd() 962 { 963 return $this->_lineEnd; 964 } 965 966 /** 967 * Sets the string used to indent HTML 968 * 969 * @param string $string String used to indent ("\11", "\t", ' ', etc.). 970 * 971 * @return JDocument instance of $this to allow chaining 972 * 973 * @since 11.1 974 */ 975 public function setTab($string) 976 { 977 $this->_tab = $string; 978 979 return $this; 980 } 981 982 /** 983 * Returns a string containing the unit for indenting HTML 984 * 985 * @return string 986 * 987 * @since 11.1 988 */ 989 public function _getTab() 990 { 991 return $this->_tab; 992 } 993 994 /** 995 * Load a renderer 996 * 997 * @param string $type The renderer type 998 * 999 * @return JDocumentRenderer Object or null if class does not exist 1000 * 1001 * @since 11.1 1002 * @throws RuntimeException 1003 */ 1004 public function loadRenderer($type) 1005 { 1006 $class = 'JDocumentRenderer' . $type; 1007 1008 if (!class_exists($class)) 1009 { 1010 $path = __DIR__ . '/' . $this->_type . '/renderer/' . $type . '.php'; 1011 1012 if (file_exists($path)) 1013 { 1014 require_once $path; 1015 } 1016 else 1017 { 1018 throw new RuntimeException('Unable to load renderer class', 500); 1019 } 1020 } 1021 1022 if (!class_exists($class)) 1023 { 1024 return null; 1025 } 1026 1027 $instance = new $class($this); 1028 1029 return $instance; 1030 } 1031 1032 /** 1033 * Parses the document and prepares the buffers 1034 * 1035 * @param array $params The array of parameters 1036 * 1037 * @return JDocument instance of $this to allow chaining 1038 * 1039 * @since 11.1 1040 */ 1041 public function parse($params = array()) 1042 { 1043 return $this; 1044 } 1045 1046 /** 1047 * Outputs the document 1048 * 1049 * @param boolean $cache If true, cache the output 1050 * @param array $params Associative array of attributes 1051 * 1052 * @return The rendered data 1053 * 1054 * @since 11.1 1055 */ 1056 public function render($cache = false, $params = array()) 1057 { 1058 $app = JFactory::getApplication(); 1059 1060 if ($mdate = $this->getModifiedDate()) 1061 { 1062 $app->modifiedDate = $mdate; 1063 } 1064 1065 $app->mimeType = $this->_mime; 1066 $app->charSet = $this->_charset; 1067 } 1068}