typo3/classes/class.typo3ajax.php

   1 <?php
   2 /***************************************************************
   3 *  Copyright notice
   4 *
   5 *  (c) 2008 Benjamin Mack <mack@xnos.org>
   6 *  All rights reserved
   7 *
   8 *  This script is part of the TYPO3 project. The TYPO3 project is
   9 *  free software; you can redistribute it and/or modify
  10 *  it under the terms of the GNU General Public License as published by
  11 *  the Free Software Foundation; either version 2 of the License, or
  12 *  (at your option) any later version.
  13 *
  14 *  The GNU General Public License can be found at
  15 *  http://www.gnu.org/copyleft/gpl.html.
  16 *  A copy is found in the textfile GPL.txt and important notices to the license
  17 *  from the author is found in LICENSE.txt distributed with these scripts.
  18 *
  19 *
  20 *  This script is distributed in the hope that it will be useful,
  21 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  22 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  23 *  GNU General Public License for more details.
  24 *
  25 *  This copyright notice MUST APPEAR in all copies of the script!
  26 ***************************************************************/
  27 /**
  28  * class to hold all the information about an AJAX call and send
  29  * the right headers for the request type
  30  *
  31  * @author      Benjamin Mack <mack@xnos.org>
  32  * @package     TYPO3
  33  * @subpackage  core
  34  */
  35 class TYPO3AJAX {
  36         private $id = null;
  37         private $errorMessage = null;
  38         private $isError = false;
  39         private $content = array();
  40         private $contentFormat = 'plain';       // could be 'plain' (default), 'xml', 'json', 'jsonbody' or 'jsonhead'
  41         private $charset = 'utf-8';
  42
  43         /**
  44          * sets the charset and the ID for the AJAX call
  45          *
  46          * @param       string  the AJAX id
  47          * @return      void
  48          */
  49         public function init($id) {
  50                 global $TYPO3_CONF_VARS;
  51
  52                 if (isset($TYPO3_CONF_VARS['BE']['forceCharset'])) {
  53                         $this->charset = $TYPO3_CONF_VARS['BE']['forceCharset'];
  54                 }
  55
  56                 $this->id = $id;
  57         }
  58
  59
  60         /**
  61          * returns the ID for the AJAX call
  62          *
  63          * @return      string  the AJAX id
  64          */
  65         public function getID() {
  66                 return $this->id;
  67         }
  68
  69
  70         /**
  71          * overwrites the existing content with the first parameter
  72          *
  73          * @param       array   the new content
  74          * @return      mixed   the old content as array; if the new content was not an array, false is returned
  75          */
  76         public function setContent($content) {
  77                 $oldcontent = false;
  78                 if (is_array($content)) {
  79                         $oldcontent = $this->content;
  80                         $this->content = $content;
  81                 }
  82                 return $oldcontent;
  83         }
  84
  85
  86         /**
  87          * adds new content
  88          *
  89          * @param       string  the new content key where the content should be added in the content array
  90          * @param       string  the new content to add
  91          * @return      mixed   the old content; if the old content didn't exist before, false is returned
  92          */
  93         public function addContent($key, $content) {
  94                 $oldcontent = false;
  95                 if (array_key_exists($key, $this->content)) {
  96                         $oldcontent = $this->content[$key];
  97                 }
  98                 if (!isset($content) || !strlen($content)) {
  99                         unset($this->content[$key]);
 100                 } elseif (!isset($key) || !strlen($key)) {
 101                         $this->content[] = $content;
 102                 } else {
 103                         $this->content[$key] = $content;
 104                 }
 105                 return $oldcontent;
 106         }
 107
 108
 109         /**
 110          * returns the content for the ajax call
 111          *
 112          * @return      mixed   the content for a specific key or the whole content
 113          */
 114         public function getContent($key = '') {
 115                 return ($key && array_key_exists($key, $this->content) ? $this->content[$key] : $this->content);
 116         }
 117
 118
 119         /**
 120          * sets the content format for the ajax call
 121          *
 122          * @param       string  can be one of the following keywords 'plain', '
 123          * @return      void
 124          */
 125         public function setContentFormat($format) {
 126                 if (t3lib_div::inArray(array('plain', 'xml', 'json', 'jsonhead', 'jsonbody'), $format)) {
 127                         $this->contentFormat = $format;
 128                 }
 129         }
 130
 131
 132         /**
 133          * sets an error message and the error flag
 134          *
 135          * @param       string  the error message
 136          * @return      void
 137          */
 138         public function setError($errorMsg = '') {
 139                 $this->errorMessage = $errorMsg;
 140                 $this->isError = true;
 141         }
 142
 143
 144         /**
 145          * checks whether an error occured during the execution or not
 146          *
 147          * @return      boolean whether this AJAX call
 148          */
 149         public function isError() {
 150                 return $this->isError;
 151         }
 152
 153
 154         /**
 155          * renders the AJAX call based on the $contentFormat variable and exits the request
 156          *
 157          * @return      void
 158          */
 159         public function render() {
 160                 if ($this->isError) {
 161                         $this->renderAsError();
 162                         exit;
 163                 }
 164                 switch ($this->contentFormat) {
 165                         case 'jsonhead':
 166                         case 'jsonbody':
 167                         case 'json':
 168                                 $this->renderAsJSON();
 169                                 break;
 170                         case 'xml':
 171                                 $this->renderAsXML();
 172                                 break;
 173                         default:
 174                                 $this->renderAsPlain();
 175                 }
 176                 exit;
 177         }
 178
 179
 180         /**
 181          * renders the AJAX call in XML error style to handle with JS
 182          * the "responseXML" of the transport object will be filled with the error message then
 183          *
 184          * @return      void
 185          */
 186         private function renderAsError() {
 187                 header('Content-type: text/xml; charset='.$this->charset);
 188                 header('X-JSON: false');
 189                 die('<t3err>'.htmlspecialchars($this->errorMessage).'</t3err>');
 190         }
 191
 192
 193         /**
 194          * renders the AJAX call with text/html headers
 195          * the content will be available in the "responseText" value of the transport object
 196          *
 197          * @return      void
 198          */
 199         private function renderAsPlain() {
 200                 header('Content-type: text/html; charset='.$this->charset);
 201                 header('X-JSON: true');
 202                 echo implode('', $this->content);
 203         }
 204
 205
 206         /**
 207          * renders the AJAX call with text/xml headers
 208          * the content will be available in the "responseXML" value of the transport object
 209          *
 210          * @return      void
 211          */
 212         private function renderAsXML() {
 213                 header('Content-type: text/xml; charset='.$this->charset);
 214                 header('X-JSON: true');
 215                 echo implode('', $this->content);
 216         }
 217
 218
 219         /**
 220          * renders the AJAX call with JSON evaluated headers
 221          * note that you need to have requestHeaders: {Accept: 'application/json'},
 222          * in your AJAX options of your AJAX request object in JS
 223          *
 224          * the content will be available
 225          *    - in the second parameter of the onSuccess / onComplete callback (except when contentFormat = 'jsonbody')
 226          *    - and in the xhr.responseText as a string (except when contentFormat = 'jsonhead')
 227          *         you can evaluate this in JS with xhr.responseText.evalJSON();
 228          *
 229          * @return      void
 230          */
 231         private function renderAsJSON() {
 232                 $content = t3lib_div::array2json($this->content);
 233
 234                 header('Content-type: application/json; charset='.$this->charset);
 235                 header('X-JSON: '.($this->contentFormat != 'jsonbody' ? $content : true));
 236
 237                         // bring content in xhr.responseText except when in "json head only" mode
 238                 if ($this->contentFormat != 'jsonhead') {
 239                         echo $content;
 240                 }
 241         }
 242 }
 243
 244
 245 if (defined('TYPO3_MODE') && $TYPO3_CONF_VARS[TYPO3_MODE]['XCLASS']['typo3/classes/class.typo3ajax.php'])       {
 246         include_once($TYPO3_CONF_VARS[TYPO3_MODE]['XCLASS']['typo3/classes/class.typo3ajax.php']);
 247 }
 248
 249 ?>