<?php
/**
 * This file contains the XMLWriter extended class for use in IWP.
 *
 * @version $Id$
 * 
 *
 * @package IWP
 * @subpackage IWP_API
 */

/**
 * Extended XMLWriter Class
 * This class extends the PHP class XMLWriter to include additional functionality and shortcuts for common tasks
 *
 * @package IWP
 * @property iwp_xmlwriter $xml
 * @subpackage IWP_API
 */

class iwp_xmlwriter extends xmlWriter {

	/**
	 * Instance
	 * This static variable holds the current instance of this object being loaded.
	 * So using the getInstance function anywhere will return the very same instance.
	 *
	 * @var object Instance
	 */
	public static $Instance;

	/**
	 * getInstance
	 * This is a static function that sets up the class instance and stores it to the static variable. It will then return that instantiation in the future.
	 *
	 * @return object Returns the instantiated object
	 **/
	public static function getInstance(){
		if(!isset(self::$Instance)){
			self::$Instance = new self();
		}
		return self::$Instance;
	}

	/**
	 * The Constructor
	 * Call the  startXML function during initialization
	 *
	 * @param string $rootElement The root element for the XML document. Defaults to 'response' which is used for XML ajax call reponses.
	 *
	 * @return void
	 *
	 * @see startXML()
	 */
	public function __construct($rootElement='response'){
		$this->startXML($rootElement);
	}

	/**
	 * This function performs the common 'starting' function calls for XMLWriter, such as openMemory, setIndent, startDocument and creates the root element.
	 * When the object is initialized this function is called from the constructor.
	 *
	 * @param string $rootElement The root element for the XML document. Defaults to 'response' which is used for XML ajax call reponses.
	 *
	 * @return void
	 *
	 * @see __construct()
	 */
	public function startXML($rootElement='response'){
		$this->openMemory();
		$this->setIndent(true);
		$this->setIndentString("\t");
		$this->startDocument('1.0','UTF-8');
		if($rootElement !== false){
			$this->startElement($rootElement);
		}
	}

	/**
	 * This function closes the root element, sends the XML content type header and echoes out the XML document.
	 *
	 * @return void
	 */
	public function outputXML($ignoreClosingElement=false){
		if($ignoreClosingElement === false){
			$this->endElement();
		}
		header('Content-Type: text/xml; charset=utf-8');
		echo $this->outputMemory(false);
	}

	/**
	 * This function is a shorthand method for outputting a error message in XML.
	 * It outputs an XML message and dies.
	 *
	 * @return void
	 */

	public function outputXMLError($msg){
		$this->writeElement('status', 'error');
		$this->writeElement('message', $msg);
		$this->outputXML();
		die();
	}

	/**
	 * This function is a shorthand method for outputting a success message in XML.
	 * It outputs an XML message and dies.
	 *
	 * @return void
	 */

	public function outputXMLSuccess($msg){
		$this->writeElement('status', 'success');
		$this->writeElement('message', $msg);
		$this->outputXML();
		die();
	}

	/**
	 * This function creates a CData element. Its made to mimic the simplicity of adding a normal element using writeElement()
	 *
	 * @param string $name The name of the element <name></name>
	 * @param string $cdata The data to be wrapped in CData tags
	 *
	 * @return void
	 */

	public function writeCDataElement($name, $cdata){
		$this->startElement($name);
		$this->writeCData($cdata);
		$this->endElement();
	}

}