<?php
/**
 * An interface for template engines
 *
 * @author		Roland Haeder <webmaster@shipsimu.org>
 * @version		0.0.0
 * @copyright	Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2013 Core Developer Team
 * @license		GNU GPL 3.0 or any newer version
 * @link		http://www.shipsimu.org
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 */
interface CompileableTemplate extends FrameworkInterface {
	/**
	 * Assign variables for templates
	 *
	 * @param	$variableName	The "variable" we want to assign
	 * @param	$value			The value we want to store in the variable
	 * @return	void
	 */
	function assignVariable ($variableName, $value);

	/**
	 * Load a specified web template into the engine
	 *
	 * @param	$template	The web template we shall load which is located in
	 *						"html" by default
	 * @return	void
	 */
	function loadWebTemplate ($template);

	/**
	 * Load a specified code template into the engine for later compilation
	 * with other code/web/email templates.
	 *
	 * @param	$template	The code template we shall load which is
	 *						located in "html" by default
	 * @return	void
	 */
	function loadCodeTemplate ($template);

	/**
	 * Compile all variables by inserting their respective values
	 *
	 * @return	void
	 */
	function compileVariables ();


	/**
	 * Compile all required code/web/email-templates into the current one
	 *
	 * @return	void
	 */
	function compileTemplate ();

	/**
	 * Adds a variable to current group
	 *
	 * @param	$variableName	Variable to set
	 * @param	$value			Value to store in variable
	 * @return	void
	 */
	function addGroupVariable ($variableName, $value);

	/**
	 * Removes a given variable
	 *
	 * @param	$variableName	The variable we are looking for
	 * @param	$variableGroup	Name of variable group (default: 'general')
	 * @return	void
	 */
	function removeVariable ($variableName, $variableGroup = 'general');

	/**
	 * Assign a given congfiguration variable with a value
	 *
	 * @param	$variableName	The configuration variable we want to assign
	 * @return	void
	 */
	function assignConfigVariable ($variableName);

	/**
	 * Compiles configuration place-holders in all variables. This 'walks'
	 * through the variable stack 'general'. It interprets all values from that
	 * variables as configuration entries after compiling them.
	 *
	 * @return	void
	 */
	function compileConfigInVariables ();

	/**
	 * Assigns the last loaded raw template content with a given variable
	 *
	 * @param	$templateName	Name of the template we want to assign
	 * @param	$variableName	Name of the variable we want to assign
	 * @return	void
	 */
	function assignTemplateWithVariable ($templateName, $variableName);

	/**
	 * Transfers the content of this template engine to a given response instance
	 *
	 * @param	$responseInstance	An instance of a response class
	 * @return	void
	 */
	function transferToResponse (Responseable $responseInstance);

	/**
	 * Assigns all the application data with template variables
	 *
	 * @param	$applicationInstance	A manageable application instance
	 * @return	void
	 */
	function assignApplicationData (ManageableApplication $applicationInstance);

	/**
	 * "Compiles" a variable by replacing {?var?} with it's content
	 *
	 * @param	$rawCode			Raw code to compile
	 * @param	$setMatchAsCode		Sets $match if readVariable() returns empty result (default: FALSE)
	 * @return	$rawCode			Compile code with inserted variable value
	 */
	function compileRawCode ($rawCode, $setMatchAsCode = FALSE);

	/**
	 * Renames a variable in code and in stack
	 *
	 * @param	$oldName	Old name of variable
	 * @param	$newName	New name of variable
	 * @return	void
	 */
	function renameVariable ($oldName, $newName);

	/**
	 * Renders the given XML content
	 *
	 * @param	$content	Valid XML content or if not set the current loaded raw content
	 * @return	void
	 * @throws	XmlParserException	If an XML error was found
	 */
	function renderXmlContent ($content = NULL);

	/**
	 * Enables or disables language support
	 *
	 * @param	$languageSupport	New language support setting
	 * @return	void
	 */
	function enableLanguageSupport ($languageSupport = TRUE);

	/**
	 * Checks whether language support is enabled
	 *
	 * @return	$languageSupport	Whether language support is enabled or disabled
	 */
	function isLanguageSupportEnabled ();

	/**
	 * Enables or disables XML compacting
	 *
	 * @param	$xmlCompacting	New XML compacting setting
	 * @return	void
	 */
	function enableXmlCompacting ($xmlCompacting = TRUE);

	/**
	 * Checks whether XML compacting is enabled
	 *
	 * @return	$xmlCompacting	Whether XML compacting is enabled or disabled
	 */
	function isXmlCompactingEnabled ();

	/**
	 * Removes all comments, tabs and new-line charcters to compact the content
	 *
	 * @param	$uncompactedContent		The uncompacted content
	 * @return	$compactedContent		The compacted content
	 */
	function compactContent ($uncompactedContent);
}

// [EOF]
?>