<?php
// Own namespace
namespace Org\Mxchange\CoreFramework\Helper;

// Import framework stuff
use Org\Mxchange\CoreFramework\Factory\Object\ObjectFactory;
use Org\Mxchange\CoreFramework\Generic\FrameworkInterface;
use Org\Mxchange\CoreFramework\Generic\NullPointerException;
use Org\Mxchange\CoreFramework\Object\BaseFrameworkSystem;
use Org\Mxchange\CoreFramework\Registry\Object\ObjectRegistry;
use Org\Mxchange\CoreFramework\Utils\Strings\StringUtils;

// Import SPL stuff
use \BasMethodCallException;
use \InvalidArgumentException;

/**
 * A generic helper class with generic methods
 *
 * @author		Roland Haeder <webmaster@shipsimu.org>
 * @version		0.0.0
 * @copyright	Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 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/>.
 */
abstract class BaseHelper extends BaseFrameworkSystem {
	/**
	 * Instance to the class which provides field values
	 */
	private $valueInstance = NULL;

	/**
	 * Extra instance to the class which provides field values
	 */
	private $extraInstance = NULL;

	/**
	 * Rendered content created by the helper class
	 */
	private $content = '';

	/**
	 * Array with groups
	 */
	private $groups = [];

	/**
	 * Array with sub group
	 */
	private $subGroups = [];

	/**
	 * Previously opened group
	 */
	private $previousGroupId = '';

	/**
	 * Previously opened sub group
	 */
	private $previousSubGroupId = '';

	/**
	 * Total counter for groups and sub groups
	 */
	private $totalCounter = 0;

	// Exception constants
	const EXCEPTION_GROUP_NOT_OPENED             = 0x1e0;
	const EXCEPTION_SUB_GROUP_ALREADY_FOUND      = 0x1e1;
	const EXCEPTION_NO_PREVIOUS_SUB_GROUP_OPENED = 0x1e2;
	const EXCEPTION_NO_PREVIOUS_GROUP_OPENED     = 0x1e3;

	/**
	 * Protected constructor
	 *
	 * @param	$className	Real name of the class
	 * @return	void
	 */
	protected function __construct (string $className) {
		// Call parent constructor
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-HELPER: className=%s - CONSTRUCTED!', $className));
		parent::__construct($className);

		// Trace message
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-HELPER: EXIT!');
	}

	/**
	 * Adds content directly
	 *
	 * @param	$newContent		New content to add
	 * @return	void
	 * @throws	InvalidArgumentException	If a parameter has an invalid value
	 */
	protected final function addContent (string $newContent) {
		// Check variable
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-HELPER: newContent=%s - CALLED!', $newContent));
		if (empty(trim($newContent))) {
			// Throw IAE
			throw new InvalidArgumentException('Parameter "newContent" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
		}

		// Append content with EOL
		$this->content .= trim($newContent) . PHP_EOL;

		// Trace message
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-HELPER: this->content()=%d - EXIT!', strlen($this->content)));
	}

	/**
	 * Add header content to the helper
	 *
	 * @param	$content	Content to to the base
	 * @return	void
	 * @throws	InvalidArgumentException	If a parameter has an invalid value
	 */
	protected function addHeaderContent (string $content) {
		// Check variable
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-HELPER: content=%s - CALLED!', $content));
		if (empty(trim($content))) {
			// Throw IAE
			throw new InvalidArgumentException('Parameter "content" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
		}

		// Add the header content
		$this->groups['header']['content'] = trim($content);

		// Trace message
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-HELPER: EXIT!');
	}

	/**
	 * Add footer content to the helper
	 *
	 * @param	$content	Content to to the base
	 * @return	void
	 * @throws	InvalidArgumentException	If a parameter has an invalid value
	 */
	protected function addFooterContent (string $content) {
		// Check variable
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-HELPER: content=%s - CALLED!', $content));
		if (empty(trim($content))) {
			// Throw IAE
			throw new InvalidArgumentException('Parameter "content" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
		}

		// Add the footer content
		$this->groups['footer']['content'] = trim($content);

		// Trace message
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-HELPER: EXIT!');
	}

	/**
	 * Adds content to the previously opened group or sub group. If a sub group
	 * was found it will be taken. If no group/sub group is opened at the moment
	 * the code will be passed to addContent().
	 *
	 * @param	$newContent		New content to add
	 * @return	void
	 * @throws	InvalidArgumentException	If a parameter has an invalid value
	 */
	protected final function addContentToPreviousGroup (string $newContent) {
		// Check on parameter
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: newContent=%s - CALLED!', $newContent));
		if (empty($newContent)) {
			// Throw IAE
			throw new InvalidArgumentException('Parameter "newContent" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
		}

		// Check for sub/group
		if ($this->ifSubGroupOpenedPreviously()) {
			// Get sub group id
			$subGroupId = $this->getPreviousSubGroupId();

			// Add the content
			$this->subGroups[$subGroupId]['content'] .= $newContent;
		} elseif ($this->ifGroupOpenedPreviously()) {
			// Get group id
			$groupId = $this->getPreviousGroupId();

			// Add the content
			$this->groups[$groupId]['content'] .= $newContent;
		} else {
			// Add it directly
			$this->addContent($newContent);
		}

		// Trace message
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-HELPER: EXIT!');
	}

	/**
	 * Getter for content
	 *
	 * @return	$content	The rendered content by this helper
	 */
	protected final function getContent () {
		return $this->content;
	}

	/**
	 * Public setter for extra instance
	 *
	 * @param	$extraInstance	An extra instance of FrameworkInterface to set
	 * @return	void
	 */
	public final function setExtraInstance (FrameworkInterface $extraInstance) {
		$this->extraInstance = $extraInstance;
	}

	/**
	 *  Assigns a field from the value instance with a template variable
	 *
	 * @param	$fieldName	Name of the field to assign
	 * @return	void
	 * @throws	InvalidArgumentException	If a parameter has an invalid value
	 */
	public function assignField (string $fieldName) {
		// Check on parameter
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: fieldName=%s - CALLED!', $fieldName));
		if (empty($fieldName)) {
			// Throw IAE
			throw new InvalidArgumentException('Parameter "fieldName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
		}

		// Get the value from value instance
		$fieldValue = $this->getValueField($fieldName);

		// Assign it with a template variable
		$this->getTemplateInstance()->assignVariable('block_' . $fieldName, $fieldValue);

		// Trace message
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-HELPER: EXIT!');
	}

	/**
	 * Assigns a field from the value instance with a template variable but
	 * parses its content through a given filter method of the value instance
	 *
	 * @param	$fieldName		Name of the field to assign
	 * @param	$filterMethod	Method name to call of the value instance
	 * @return	void
	 * @throws	InvalidArgumentException	If a parameter has an invalid value
	 * @todo	Rewrite this method using a helper class for filtering data
	 */
	public function assignFieldWithFilter (string $fieldName, string $filterMethod) {
		// Validate parameter
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: fieldName=%s,filterMethod=%s - CALLED!', $fieldName, $filterMethod));
		if (empty($fieldName)) {
			// Throw IAE
			throw new InvalidArgumentException('Parameter "fieldName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
		} elseif (empty($filterMethod)) {
			// Throw IAE
			throw new InvalidArgumentException('Parameter "filterMethod" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
		}

		// Get the value
		$fieldValue = $this->getValueField($fieldName);

		// Now filter it through the value through the filter method
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: %s[%s]=%s', $fieldName, gettype($fieldValue), $fieldValue));
		$filteredValue = call_user_func_array(array($this, 'doFilter' . StringUtils::convertToClassName($filterMethod)), array($fieldValue));

		// Assign it with a template variable
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: filteredValue[%s]=%s', gettype($filteredValue), $filteredValue));
		$this->getTemplateInstance()->assignVariable('block_' . $fieldName, $filteredValue);

		// Trace message
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-HELPER: EXIT!');
	}

	/**
	 * Pre-fetches field default values from the given registry key instance into this class
	 *
	 * @param	$registryKey	Registry key which holds an object with values
	 * @param	$extraKey		Extra value instance key used if registryKey is null
	 * @return	void
	 * @throws	InvalidArgumentException	If a parameter has an invalid value
	 */
	public function prefetchValueInstance (string $registryKey, string $extraKey = NULL) {
		// Validate parameter
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: registryKey=%s,extraKey[%s]=%s - CALLED!', $registryKey, gettype($extraKey), $extraKey));
		if (empty($registryKey)) {
			// Throw IAE
			throw new InvalidArgumentException('Parameter "registryKey" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
		}

		try {
			// Get the required instance
			$this->valueInstance = ObjectRegistry::getRegistry('generic')->getInstance($registryKey);
		} catch (NullPointerException $e) {
			// Not set in registry
			//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: registryKey=%s returned no instance (NPE thrown)', $registryKey));
		}

		// Shall we get an extra instance?
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: extraKey[%s]=%s', gettype($extraKey), $extraKey));
		if (!is_null($extraKey)) {
			try {
				// Get the extra instance.
				$this->extraInstance = ObjectRegistry::getRegistry('generic')->getInstance($extraKey);
			} catch (NullPointerException $e) {
				// Try to create it
				//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: extraKey=%s returned no instance (NPE thrown), this->valueInstance[]=%s', $extraKey, gettype($this->valueInstance)));
				$this->extraInstance = ObjectFactory::createObjectByConfiguredName($extraKey . '_class', [$this->valueInstance]);
			}
			//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: extraKey=%s,this->extraInstance[%s]=%s', $extraKey, gettype($this->extraInstance), $this->extraInstance));
		}

		// Is the value instance valid?
		//* NOSIY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: this->valueInstance[]=%s - BEFORE!', gettype($this->valueInstance)));
		if (is_null($this->valueInstance)) {
			// Get the requested instance
			$this->valueInstance = ObjectFactory::createObjectByConfiguredName($registryKey . '_class', array($this->extraInstance));
		}

		// Trace message
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: this->valueInstance[]=%s - AFTER/EXIT!', gettype($this->valueInstance)));
	}

	/**
	 * Opens a helper group with given group id and content or throws an
	 * exception if that group is already found regardless if it is open or
	 * closed.
	 *
	 * @param	$groupId	Group id to open
	 * @param	$content	Initial content to add to the group
	 * @param	$tag		HTML tag used to open this group
	 * @return	void
	 * @throws	InvalidArgumentException	If a parameter has an invalid value
	 * @throws	BadMethodCallException	If the group was already created before
	 */
	protected function openGroupByIdContent (string $groupId, string $content, string $tag) {
		// Is the group already there?
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: groupdId=%s,content=%s,tag=%s - CALLED!', $groupdId, $content, $tag));
		if (empty($groupId)) {
			// Throw IAE
			throw new InvalidArgumentException('Parameter "groupId" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
		} elseif (isset($this->groups[$groupId])) {
			// Then throw an exception here
			throw new BadMethodCallException(sprintf('[%s:%d]: groupId=%s is already opened.', $this->__toString(), $groupId), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
		} elseif (empty($content)) {
			// Throw IAE
			throw new InvalidArgumentException('Parameter "content" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
		} elseif (empty($tag)) {
			// Throw IAE
			throw new InvalidArgumentException('Parameter "tag" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
		}

		// Count one up
		$this->totalCounter++;

		// Add the group to the stack
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: this->totalCounter=%d', $this->totalCounter));
		$this->groups[$this->totalCounter] = $groupId;
		$this->groups[$groupId]['opened']  = true;
		$this->groups[$groupId]['content'] = sprintf(
			'<!-- group %s opened (length: %s, tag: %s) //-->%s' . PHP_EOL,
			$groupId,
			strlen($content),
			$tag,
			$content
		);
		$this->groups[$groupId]['tag'] = $tag;

		// Mark this group as previously opened
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: Setting this->previousGroupId=%s ...', $groupId));
		$this->setPreviousGroupId($groupId);

		// Trace message
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-HELPER: EXIT!');
	}

	/**
	 * Closes the previously opened group by added given content to it or
	 * throws an exception if no previous group was opened
	 *
	 * @param	$content	Content for previously opened group, or empty to use tag of opener
	 * @return	void
	 * @throws	HelperNoPreviousOpenedGroupException	If no previously opened group was found
	 */
	public function closePreviousGroupByContent (string $content = '') {
		// Check if any sub group was opened before
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: content(%d)=%s - CALLED!', strlen($content), $content));
		if ($this->ifSubGroupOpenedPreviously()) {
			// Close it automatically
			$this->closePreviousSubGroupByContent();
		}

		// Check if any group was opened before
		if ($this->ifGroupOpenedPreviously() === false) {
			// Then throw an exception
			throw new HelperNoPreviousOpenedGroupException(array($this, $content), self::EXCEPTION_NO_PREVIOUS_SUB_GROUP_OPENED);
		}

		// Get previous group
		$groupId = $this->getPreviousGroupId();

		// Is the content empty?
		if ((empty($content)) && (!empty($this->groups[$groupId]['tag']))) {
			// Get it from opener
			$content = sprintf(
				"<!-- group %s auto-closed //--></%s>",
				$groupId,
				$this->groups[$groupId]['tag']
			);
		}

		// Add content to it and mark it as closed
		$this->groups[$groupId]['content'] .= sprintf(
			"<!-- group %s closed (length: %s, tag: %s) //-->%s\n",
			$groupId,
			strlen($content),
			$this->groups[$groupId]['tag'],
			$content
		);
		$this->groups[$groupId]['opened'] = false;

		// Mark previous group as closed
		$this->setPreviousGroupId('');
		//* NOISY-DEBUG: */ echo "CLOSE:groupId={$groupId}<br />\n";
	}

	/**
	 * Opens a helper sub group with given group id and content or throws an
	 * exception if that sub group is already found regardless if it is open or
	 * closed.
	 *
	 * @param	$subGroupId		Sub group id to open
	 * @param	$content		Initial content to add to the sub group
	 * @param	$tag			HTML tag used to open this group
	 * @return	void
	 * @throws	HelperSubGroupAlreadyCreatedException	If the sub group was already created before
	 */
	protected function openSubGroupByIdContent (string $subGroupId, string $content, string $tag) {
		//* NOISY-DEBUG: */ echo "OPEN:subGroupId={$subGroupId},content=".htmlentities($content)."<br />\n";
		// Is the group already there?
		if (empty($subGroupId)) {
			// Throw IAE
			throw new InvalidArgumentException('Parameter "subGroupId" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
		} elseif (isset($this->subGroups[$subGroupId])) {
			// Then throw an exception here
			throw new HelperSubGroupAlreadyCreatedException(array($this, $subGroupId), self::EXCEPTION_SUB_GROUP_ALREADY_FOUND);
		}

		// Count one up
		$this->totalCounter++;

		// Add the group to the stack
		$this->subGroups[$this->totalCounter] = $subGroupId;
		$this->subGroups[$subGroupId]['opened']  = true;
		$this->subGroups[$subGroupId]['content'] = sprintf("<!-- sub-group %s opened (length: %s, tag: %s) //-->%s\n", $subGroupId, strlen($content), $tag, $content);
		$this->subGroups[$subGroupId]['tag'] = $tag;

		// Mark this group as previously opened
		$this->setPreviousSubGroupId($subGroupId);
	}

	/**
	 * Closes the previously opened sub group by added given content to it or
	 * throws an exception if no previous sub group was opened
	 *
	 * @param	$content	Content for previously opened sub group, or leave empty to use div/span of openener
	 * @return	void
	 * @throws	HelperNoPreviousOpenedSubGroupException	If no previously opened sub group was found
	 */
	public function closePreviousSubGroupByContent (string $content = '') {
		// Check if any sub group was opened before
		if ($this->ifSubGroupOpenedPreviously() === false) {
			// Then throw an exception
			throw new HelperNoPreviousOpenedSubGroupException(array($this, $content), self::EXCEPTION_NO_PREVIOUS_SUB_GROUP_OPENED);
		}

		// Get previous sub group
		$subGroupId = $this->getPreviousSubGroupId();

		// Is the content empty?
		if ((empty($content)) && (!empty($this->subGroups[$subGroupId]['tag']))) {
			// Get it from opener
			$content = sprintf('<!-- sub-group %s auto-closed //--></%s>', $subGroupId, $this->subGroups[$subGroupId]['tag']);
		}

		// Add content to it and mark it as closed
		$this->subGroups[$subGroupId]['content'] .= sprintf('<!-- sub-group %s closed (length: %s, tag: %s) //-->%s' . PHP_EOL, $subGroupId, strlen($content), $this->subGroups[$subGroupId]['tag'], $content);
		$this->subGroups[$subGroupId]['opened'] = false
		;

		// Mark previous sub group as closed
		$this->setPreviousSubGroupId('');
		//* NOISY-DEBUG: */ echo "CLOSE:subGroupId={$subGroupId}<br />\n";
	}

	/**
	 * Renders all group and sub group in their order
	 *
	 * @return	$content	Rendered HTML content
	 */
	public function renderContent () {
		// Initialize content
		$content = '';

		// Is header content there?
		if (isset($this->groups['header'])) {
			// Then add it
			$content .= $this->groups['header']['content'] . PHP_EOL;
		}

		// Initiate content
		$content .= $this->getContent();

		// Now "walk" through all groups and sub-groups
		for ($idx = 1; $idx <= $this->totalCounter; $idx++) {
			// Is this a sub/group and is it closed?
			if ((isset($this->groups[$idx])) && ($this->groups[$this->groups[$idx]]['opened'] === false)) {
				// Then add it's content
				$groupContent = trim($this->groups[$this->groups[$idx]]['content']);
				//* NOISY-DEBUG: */ echo "group={$this->groups[$idx]},content=<pre>".htmlentities($groupContent)."</pre><br />\n";
				$content .= $groupContent;
			} elseif ((isset($this->subGroups[$idx])) && ($this->subGroups[$this->subGroups[$idx]]['opened'] === false)) {
				// Then add it's content
				$subGroupContent = $this->subGroups[$this->subGroups[$idx]]['content'];
				//* NOISY-DEBUG: */ echo "subgroup={$this->subGroups[$idx]},content=<pre>".htmlentities($subGroupContent)."</pre><br />\n";
				$content .= trim($subGroupContent);
			} else {
				// Something went wrong
				$this->debugInstance(__METHOD__ . '(): Something unexpected happened here.');
			}
		}

		// Is footer content there?
		if (isset($this->groups['footer'])) {
			// Then add it
			$content .= $this->groups['footer']['content'] . PHP_EOL;
		}

		// Return it
		//* NOISY-DEBUG: */ echo "content=<pre>".htmlentities($content)."</pre> (".strlen($content).")<br />\n";
		return $content;
	}

	/**
	 * Checks whether the specified group is opened
	 *
	 * @param	$groupId	Id of group to check
	 * @return	$isOpened	Whether the specified group is open
	 * @throws	InvalidArgumentException	If a parameter has an invalid value
	 */
	protected function ifGroupIsOpened (string $groupId) {
		// Check on parameter
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: groupId=%s - CALLED!', $groupId));
		if (empty($groupId)) {
			// Throw IAE
			throw new InvalidArgumentException('Parameter "groupId" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
		}

		// Is the group open?
		$isOpened = ((isset($this->groups[$groupId])) && ($this->groups[$groupId]['opened'] === true));

		// Return status
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: isOpened=%d - EXIT!', intval($isOpened)));
		return $isOpened;
	}

	/**
	 * Getter for direct field values
	 *
	 * @param	$fieldName		Name of the field we shall fetch
	 * @return	$fieldValue		Value from field
	 * @throws	InvalidArgumentException	If a parameter has an invalid value
	 * @throws	NullPointerException	Thrown if $valueInstance is null
	 */
	public function getValueField (string $fieldName) {
		// Check parameter
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: fieldName=%s - CALLED!', $fieldName));
		if (empty($fieldName)) {
			// Throw IAE
			throw new InvalidArgumentException('Parameter "fieldName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
		}

		// Init value
		$fieldValue = NULL;

		// The $valueInstance attribute should not be null!
		if (is_null($this->getValueInstance())) {
			// Throws an exception here
			throw new NullPointerException($this, FrameworkInterface::EXCEPTION_IS_NULL_POINTER);
		}

		// Is the field set?
		if ($this->getValueInstance()->isFieldSet($fieldName)) {
			// Get the field value
			$fieldValue = $this->getValueInstance()->getField($fieldName);
			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput($fieldName.'[]='.gettype($fieldValue).'('.strlen($fieldValue).') - Value instance!');
		} elseif ((!is_null($this->extraInstance)) && ($this->extraInstance->isFieldSet($fieldName))) {
			// So try the extra instance
			$fieldValue = $this->extraInstance->getField($fieldName);
			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput($fieldName.'[]='.gettype($fieldValue).'('.strlen($fieldValue).') - Extra instance!');
		} else {
			// Field is not set
			$this->debugOutput('BASE-HELPER: fieldName=' . $fieldName . ' is not set! - @TODO');
		}

		// Return it
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-HELPER: fieldValue[%s]=%s - EXIT!', gettype($fieldValue), $fieldValue));
		return $fieldValue;
	}

	/**
	 * Getter for value instance
	 *
	 * @return	$valueInstance	Instance of the class holding our values
	 */
	public final function getValueInstance () {
		return $this->valueInstance;
	}

	/**
	 * Check whether a group was opened previously
	 *
	 * @return	$groupOpened	Whether any group was opened before
	 */
	protected final function ifGroupOpenedPreviously () {
		$groupOpened = (!empty($this->previousGroupId));
		return $groupOpened;
	}

	/**
	 * Check whether a group was opened previously
	 *
	 * @return	$subGroupOpened		Whether any group was opened before
	 */
	protected final function ifSubGroupOpenedPreviously () {
		$subGroupOpened = (!empty($this->previousSubGroupId));
		return $subGroupOpened;
	}

	/**
	 * Getter for previous group id
	 *
	 * @return	$previousGroupId	Id of previously opened group
	 */
	protected final function getPreviousGroupId () {
		return $this->previousGroupId;
	}

	/**
	 * Setter for previous group id
	 *
	 * @param	$previousGroupId	Id of previously opened group
	 * @return	void
	 */
	protected final function setPreviousGroupId (string $previousGroupId) {
		$this->previousGroupId = $previousGroupId;
	}

	/**
	 * Getter for previous sub group id
	 *
	 * @return	$previousSubGroupId		Id of previously opened sub group
	 */
	protected final function getPreviousSubGroupId () {
		return $this->previousSubGroupId;
	}

	/**
	 * Setter for previous sub group id
	 *
	 * @param	$previousSubGroupId		Id of previously opened sub group
	 * @return	void
	 */
	protected final function setPreviousSubGroupId (string $previousSubGroupId) {
		$this->previousSubGroupId = $previousSubGroupId;
	}

}