closedquestion-8.x-3.x-dev/src/Question/Mapping/CqFeedback.php

<?php

namespace Drupal\closedquestion\Question\Mapping;

use Drupal\closedquestion\Question\CqQuestionInterface;

/**
 * Class CqFeedback.
 *
 * Class for handling feedback.
 * An instance of CqFeedback holds one feedback "item".
 *
 * @package Drupal\closedquestion\Question\Mapping
 */
class CqFeedback {

  /**
   * The context object.
   *
   * The question or other object that this item can query for things like the
   * current answer, draggables and hotspots.
   *
   * @var \Drupal\closedquestion\Question\CqQuestionInterface
   */
  private $context;

  /**
   * The top-branch of this mapping tree. Usually a CqMapping object.
   *
   * @var \Drupal\closedquestion\Question\Mapping\CqMapping
   */
  public $topParent;

  /**
   * The minimum number of tries before this feedback should be shown.
   *
   * @var int
   */
  private $minTries = 0;

  /**
   * The maximum number of tries for which this feedback should be shown.
   *
   * @var int
   */
  private $maxTries = 9999;

  /**
   * The html content of the feedback.
   *
   * @var string
   */
  private $text = '';

  /**
   * The identifier of the inline feedback block.
   *
   * ID to use for this feedback item or FALSE to put the item in the
   * common feedback area.
   *
   * @var string|bool
   */
  private $block = FALSE;

  /**
   * Initialises an existing CqFeedback from an XML node.
   *
   * @param \DOMElement $node
   *   The node to use for initialisation.
   * @param \Drupal\closedquestion\Question\CqQuestionInterface $context
   *   The question or other object that the item can query for things like the
   *   current answer, draggables, hotspots and html processing.
   * @param \Drupal\closedquestion\Question\Mapping\CqMapping|null $topParent
   *   Parent mapping.
   */
  public function initFromElement(\DOMElement $node, CqQuestionInterface $context, CqMapping $topParent = NULL) {
    $this->context = & $context;
    $this->topParent = & $topParent;

    $this->text .= \Drupal::service('closedquestion.utility.xml_lib')->getTextContent($node, $context, TRUE, TRUE);
    $attribs = $node->attributes;
    $itemMin = $attribs->getNamedItem('mintries');
    if ($itemMin !== NULL) {
      $this->minTries = (int) $itemMin->value;
    }
    $itemMax = $attribs->getNamedItem('maxtries');
    if ($itemMax !== NULL) {
      $this->maxTries = (int) $itemMax->value;
    }
    $itemBlock = $attribs->getNamedItem('block');
    if ($itemBlock !== NULL) {
      $this->setBlock($itemBlock->value);
    }
    $image = $attribs->getNamedItem('img');

    if ($image !== NULL) {
      $this->image = $image->value;
    }
  }

  /**
   * Initialises feedback values.
   *
   * Initialises an existing CqFeedback with exact values for text, mintries
   * and maxtries.
   *
   * @param string $text
   *   The feedback text.
   * @param int $mintries
   *   The minimum number of tries needed before this feedback is shown.
   * @param int $maxtries
   *   The maximum number of tries after which this feedback is no longer shown.
   * @param string|bool $block
   *   The identifier of the inline feedback block.
   */
  public function initWithValues($text, $mintries, $maxtries, $block = FALSE) {
    $this->text = $text;
    $this->minTries = $mintries;
    $this->maxTries = $maxtries;
    $this->setBlock($block);
  }

  /**
   * Getter for the minimum number of tries needed.
   *
   * @return int
   *   The minimum number of tries.
   */
  public function getMinTries() {
    return $this->minTries;
  }

  /**
   * Getter for the maximum number of tries allowed.
   *
   * @return int
   *   The maximum number of tries.
   */
  public function getMaxTries() {
    return $this->maxTries;
  }

  /**
   * Getter for the feedback text.
   *
   * @return string
   *   The text to show as feedback.
   */
  public function getText() {
    $xmlLib = \Drupal::service('closedquestion.utility.xml_lib');
    $block = $this->getBlock();
    if ($block !== FALSE) {
      if (mb_strtolower($block) == 'lastmatchedid') {
        $block = $this->topParent->lastMatchedId;
      }
      return '<div class="cqFbItem block-' . $block . '">' . $xmlLib->replaceTags($this->text, $this->context) . '</div>';
    }
    else {
      return $xmlLib->replaceTags($this->text, $this->context);
    }
  }

  /**
   * Getter for the feedback image.
   *
   * @return string
   *   The image URL.
   */
  public function getImage() {
    return isset($this->image) ? $this->image : '';
  }

  /**
   * Checks that given tries number is within range.
   *
   * Checks if the given number of tries is between the min and max tries
   * (inclusive).
   *
   * @param int $tries
   *   The number to check.
   *
   * @return bool
   *   TRUE if $tries is in range.
   */
  public function inRange($tries) {
    return ($tries >= $this->minTries && $tries <= $this->maxTries);
  }

  /**
   * Returns the id of the feedback block.
   *
   * Returns the id of the feedback block this feedback item is associated with,
   * or FALSE if not associated with a feedback block.
   *
   * @return string|bool
   *   The feedback-block id, or FALSE if no block.
   */
  public function getBlock() {
    return $this->block;
  }

  /**
   * Sets associated block id.
   *
   * Associate this feedback item with the feedback block with the given id, or
   * remove any association by passing FALSE.
   *
   * @param string|bool $block
   *   The id of the feedback block to associate this item with.
   *   FALSE: unset any association with a feedback block.
   */
  public function setBlock($block) {
    $this->block = $block;
  }

  /**
   * Creates a new CqFeedback and initialises it from an XML node.
   *
   * @param \DOMElement $node
   *   The node to use for initialisation.
   * @param \Drupal\closedquestion\Question\CqQuestionInterface $context
   *   The question or other object that the item can query for
   *   things like the current answer, draggables and hotspots.
   *
   * @return CqFeedback
   *   A new CqFeedback instance.
   */
  public static function newCqFeedback(\DOMElement $node, CqQuestionInterface $context) {
    $fbItem = new self();
    $fbItem->initFromElement($node, $context);
    return $fbItem;
  }

  /**
   * Get all the text in the item, for easier reviewing for spelling, etc.
   *
   * @return array
   *   Themeable form array.
   */
  public function getAllText() {
    $retval = array();
    $retval['#theme'] = 'closedquestion_feedback_item';
    $retval['#mintries'] = $this->minTries;
    $retval['#maxtries'] = $this->maxTries;
    $retval['#text'] = $this->text;
    return $retval;
  }

}