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 /**
  29  * class to hold all the information about an AJAX call and send
  30  * the right headers for the request type
  31  *
  32  * @author      Benjamin Mack <mack@xnos.org>
  33  * @package     TYPO3
  34  * @subpackage  core
  35  */
  36 class TYPO3AJAX {
  37         protected $ajaxId        = null;
  38         protected $errorMessage  = null;
  39         protected $isError       = false;
  40         protected $content       = array();
  41         protected $contentFormat = 'plain';
  42         protected $charset       = 'utf-8';
  43
  44         /**
  45          * sets the charset and the ID for the AJAX call
  46          *
  47          * @param       string          the AJAX id
  48          * @return      void
  49          */
  50         public function __construct($ajaxId) {
  51                 global $LANG;
  52
  53                 if($LANG->charSet != $this->charset) {
  54                         $this->charset = $LANG->charSet;
  55                 }
  56
  57                 $this->ajaxId = $ajaxId;
  58         }
  59
  60
  61         /**
  62          * returns the ID for the AJAX call
  63          *
  64          * @return      string          the AJAX id
  65          */
  66         public function getAjaxID() {
  67                 return $this->ajaxId;
  68         }
  69
  70
  71         /**
  72          * overwrites the existing content with the first parameter
  73          *
  74          * @param       array           the new content
  75          * @return      mixed           the old content as array; if the new content was not an array, false is returned
  76          */
  77         public function setContent($content) {
  78                 $oldcontent = false;
  79                 if (is_array($content)) {
  80                         $oldcontent = $this->content;
  81                         $this->content = $content;
  82                 }
  83                 return $oldcontent;
  84         }
  85
  86
  87         /**
  88          * adds new content
  89          *
  90          * @param       string          the new content key where the content should be added in the content array
  91          * @param       string          the new content to add
  92          * @return      mixed           the old content; if the old content didn't exist before, false is returned
  93          */
  94         public function addContent($key, $content) {
  95                 $oldcontent = false;
  96                 if (array_key_exists($key, $this->content)) {
  97                         $oldcontent = $this->content[$key];
  98                 }
  99                 if (!isset($content) || !strlen($content)) {
 100                         unset($this->content[$key]);
 101                 } elseif (!isset($key) || !strlen($key)) {
 102                         $this->content[] = $content;
 103                 } else {
 104                         $this->content[$key] = $content;
 105                 }
 106                 return $oldcontent;
 107         }
 108
 109
 110         /**
 111          * returns the content for the ajax call
 112          *
 113          * @return      mixed           the content for a specific key or the whole content
 114          */
 115         public function getContent($key = '') {
 116                 return ($key && array_key_exists($key, $this->content) ? $this->content[$key] : $this->content);
 117         }
 118
 119
 120         /**
 121          * sets the content format for the ajax call
 122          *
 123          * @param       string          can be one of 'plain' (default), 'xml', 'json', 'jsonbody' or 'jsonhead'
 124          * @return      void
 125          */
 126         public function setContentFormat($format) {
 127                 if (t3lib_div::inArray(array('plain', 'xml', 'json', 'jsonhead', 'jsonbody'), $format)) {
 128                         $this->contentFormat = $format;
 129                 }
 130         }
 131
 132
 133         /**
 134          * sets an error message and the error flag
 135          *
 136          * @param       string          the error message
 137          * @return      void
 138          */
 139         public function setError($errorMsg = '') {
 140                 $this->errorMessage = $errorMsg;
 141                 $this->isError = true;
 142         }
 143
 144
 145         /**
 146          * checks whether an error occured during the execution or not
 147          *
 148          * @return      boolean         whether this AJAX call had errors
 149          */
 150         public function isError() {
 151                 return $this->isError;
 152         }
 153
 154
 155         /**
 156          * renders the AJAX call based on the $contentFormat variable and exits the request
 157          *
 158          * @return      void
 159          */
 160         public function render() {
 161                 if ($this->isError) {
 162                         $this->renderAsError();
 163                         exit;
 164                 }
 165                 switch ($this->contentFormat) {
 166                         case 'jsonhead':
 167                         case 'jsonbody':
 168                         case 'json':
 169                                 $this->renderAsJSON();
 170                                 break;
 171                         case 'xml':
 172                                 $this->renderAsXML();
 173                                 break;
 174                         default:
 175                                 $this->renderAsPlain();
 176                 }
 177                 exit;
 178         }
 179
 180
 181         /**
 182          * renders the AJAX call in XML error style to handle with JS
 183          * the "responseXML" of the transport object will be filled with the error message then
 184          *
 185          * @return      void
 186          */
 187         protected function renderAsError() {
 188                 header('Content-type: text/xml; charset='.$this->charset);
 189                 header('X-JSON: false');
 190                 die('<t3err>'.htmlspecialchars($this->errorMessage).'</t3err>');
 191         }
 192
 193
 194         /**
 195          * renders the AJAX call with text/html headers
 196          * the content will be available in the "responseText" value of the transport object
 197          *
 198          * @return      void
 199          */
 200         protected function renderAsPlain() {
 201                 header('Content-type: text/html; charset='.$this->charset);
 202                 header('X-JSON: true');
 203                 echo implode('', $this->content);
 204         }
 205
 206
 207         /**
 208          * renders the AJAX call with text/xml headers
 209          * the content will be available in the "responseXML" value of the transport object
 210          *
 211          * @return      void
 212          */
 213         protected function renderAsXML() {
 214                 header('Content-type: text/xml; charset='.$this->charset);
 215                 header('X-JSON: true');
 216                 echo implode('', $this->content);
 217         }
 218
 219
 220         /**
 221          * renders the AJAX call with JSON evaluated headers
 222          * note that you need to have requestHeaders: {Accept: 'application/json'},
 223          * in your AJAX options of your AJAX request object in JS
 224          *
 225          * the content will be available
 226          *    - in the second parameter of the onSuccess / onComplete callback (except when contentFormat = 'jsonbody')
 227          *    - and in the xhr.responseText as a string (except when contentFormat = 'jsonhead')
 228          *         you can evaluate this in JS with xhr.responseText.evalJSON();
 229          *
 230          * @return      void
 231          */
 232         protected function renderAsJSON() {
 233                 $content = t3lib_div::array2json($this->content);
 234
 235                 header('Content-type: application/json; charset='.$this->charset);
 236                 header('X-JSON: '.($this->contentFormat != 'jsonbody' ? $content : true));
 237
 238                         // bring content in xhr.responseText except when in "json head only" mode
 239                 if ($this->contentFormat != 'jsonhead') {
 240                         echo $content;
 241                 }
 242         }
 243 }
 244
 245
 246 if (defined('TYPO3_MODE') && $TYPO3_CONF_VARS[TYPO3_MODE]['XCLASS']['typo3/classes/class.typo3ajax.php'])       {
 247         include_once($TYPO3_CONF_VARS[TYPO3_MODE]['XCLASS']['typo3/classes/class.typo3ajax.php']);
 248 }
 249
 250 ?>