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