class.ilAssQuestionFeedback.php

Go to the documentation of this file.

<?php

abstract class ilAssQuestionFeedback
{
    public const CSS_CLASS_FEEDBACK_CORRECT = 'ilc_qfeedr_FeedbackRight';
    public const CSS_CLASS_FEEDBACK_WRONG = 'ilc_qfeedw_FeedbackWrong';

    public const PAGE_OBJECT_TYPE_GENERIC_FEEDBACK = 'qfbg';

    public const PAGE_OBJECT_TYPE_SPECIFIC_FEEDBACK = 'qfbs';

    public const FEEDBACK_SOLUTION_INCOMPLETE_PAGE_OBJECT_ID = 1;

    public const FEEDBACK_SOLUTION_COMPLETE_PAGE_OBJECT_ID = 2;

    public const TABLE_NAME_GENERIC_FEEDBACK = 'qpl_fb_generic';

    protected assQuestion $questionOBJ;

    protected ilCtrl $ctrl;

    protected ilDBInterface $db;

    protected ilLanguage $lng;

    protected string $page_obj_output_mode = "presentation";

    final public function __construct(assQuestion $questionOBJ, ilCtrl $ctrl, ilDBInterface $db, ilLanguage $lng)
    {
        $this->questionOBJ = $questionOBJ;
        $this->ctrl = $ctrl;
        $this->lng = $lng;
        $this->db = $db;
    }

    public function getGenericFeedbackTestPresentation(int $questionId, bool $solutionCompleted): string
    {
        if ($this->page_obj_output_mode == "edit") {
            return '';
        }
        if ($this->questionOBJ->isAdditionalContentEditingModePageObject()) {
            return $this->cleanupPageContent(
                $this->getPageObjectContent(
                    $this->getGenericFeedbackPageObjectType(),
                    $this->getGenericFeedbackPageObjectId($questionId, $solutionCompleted)
                )
            );
        }
        return $this->getGenericFeedbackContent($questionId, $solutionCompleted);
    }

    abstract public function getSpecificAnswerFeedbackTestPresentation(int $questionId, int $questionIndex, int $answerIndex): string;

    final public function completeGenericFormProperties(ilPropertyFormGUI $form): void
    {
        $form->addItem($this->buildFeedbackContentFormProperty(
            $this->lng->txt('feedback_complete_solution'),
            'feedback_complete',
            $this->questionOBJ->isAdditionalContentEditingModePageObject()
        ));

        $form->addItem($this->buildFeedbackContentFormProperty(
            $this->lng->txt('feedback_incomplete_solution'),
            'feedback_incomplete',
            $this->questionOBJ->isAdditionalContentEditingModePageObject()
        ));
    }

    abstract public function completeSpecificFormProperties(ilPropertyFormGUI $form): void;

    final public function initGenericFormProperties(ilPropertyFormGUI $form): void
    {
        if ($this->questionOBJ->isAdditionalContentEditingModePageObject()) {
            $pageObjectType = $this->getGenericFeedbackPageObjectType();

            $valueFeedbackSolutionComplete = $this->getPageObjectNonEditableValueHTML(
                $pageObjectType,
                $this->getGenericFeedbackPageObjectId($this->questionOBJ->getId(), true)
            );

            $valueFeedbackSolutionIncomplete = $this->getPageObjectNonEditableValueHTML(
                $pageObjectType,
                $this->getGenericFeedbackPageObjectId($this->questionOBJ->getId(), false)
            );
        } else {
            $valueFeedbackSolutionComplete = $this->getGenericFeedbackContent(
                $this->questionOBJ->getId(),
                true
            );

            $valueFeedbackSolutionIncomplete = $this->getGenericFeedbackContent(
                $this->questionOBJ->getId(),
                false
            );
        }

        $form->getItemByPostVar('feedback_complete')->setValue($valueFeedbackSolutionComplete);
        $form->getItemByPostVar('feedback_incomplete')->setValue($valueFeedbackSolutionIncomplete);
    }

    abstract public function initSpecificFormProperties(ilPropertyFormGUI $form): void;

    final public function saveGenericFormProperties(ilPropertyFormGUI $form): void
    {
        if (!$this->questionOBJ->isAdditionalContentEditingModePageObject()) {
            $this->saveGenericFeedbackContent($this->questionOBJ->getId(), false, (string) $form->getInput('feedback_incomplete'));
            $this->saveGenericFeedbackContent($this->questionOBJ->getId(), true, (string) $form->getInput('feedback_complete'));
        }
    }

    abstract public function saveSpecificFormProperties(ilPropertyFormGUI $form): void;

    public function isSaveableInPageObjectEditingMode(): bool
    {
        return false;
    }

    final protected function buildFeedbackContentFormProperty(string $label, string $postVar, bool $asNonEditable): ilSubEnabledFormPropertyGUI
    {
        if ($asNonEditable) {
            $property = new ilNonEditableValueGUI($label, $postVar, true);
        } else {
            $property = new ilTextAreaInputGUI($label, $postVar);
            $property->setRequired(false);
            $property->setRows(10);
            $property->setCols(80);

            if (!$this->questionOBJ->getPreventRteUsage()) {
                $property->setUseRte(true);
                $property->addPlugin("latex");
                $property->addButton("latex");
                $property->addButton("pastelatex");

                $property->setRteTags(ilObjAdvancedEditing::_getUsedHTMLTags("assessment"));
                $property->setRTESupport($this->questionOBJ->getId(), "qpl", "assessment");
            } else {
                $property->setRteTags(ilAssSelfAssessmentQuestionFormatter::getSelfAssessmentTags());
                $property->setUseTagsForRteOnly(false);
            }

            $property->setRTESupport($this->questionOBJ->getId(), "qpl", "assessment");
        }

        return $property;
    }

    final public function getGenericFeedbackContent(int $questionId, bool $solutionCompleted): string
    {
        $res = $this->db->queryF(
            "SELECT * FROM {$this->getGenericFeedbackTableName()} WHERE question_fi = %s AND correctness = %s",
            array('integer', 'text'),
            array($questionId, (int) $solutionCompleted)
        );

        $feedbackContent = '';

        if ($this->db->numRows($res) > 0) {
            $row = $this->db->fetchAssoc($res);
            $feedbackContent = ilRTE::_replaceMediaObjectImageSrc(
                $this->questionOBJ->getHtmlQuestionContentPurifier()->purify($row['feedback'] ?? ''),
                1
            );
        }
        return $feedbackContent;
    }

    abstract public function getSpecificAnswerFeedbackContent(int $questionId, int $questionIndex, int $answerIndex): string;

    abstract public function getAllSpecificAnswerFeedbackContents(int $questionId): string;

    public function isSpecificAnswerFeedbackAvailable(int $questionId): bool
    {
        $res = $this->db->queryF(
            "SELECT answer FROM {$this->getSpecificFeedbackTableName()} WHERE question_fi = %s",
            ['integer'],
            [$questionId]
        );

        $allFeedbackContents = '';

        while ($row = $this->db->fetchAssoc($res)) {
            $allFeedbackContents .= $this->getSpecificAnswerFeedbackExportPresentation(
                $this->questionOBJ->getId(),
                0,
                $row['answer']
            );
        }

        return (bool) strlen(trim(strip_tags($allFeedbackContents)));
    }

    final public function saveGenericFeedbackContent(int $questionId, bool $solutionCompleted, string $feedbackContent): int
    {
        require_once 'Services/RTE/classes/class.ilRTE.php';

        $feedbackId = $this->getGenericFeedbackId($questionId, $solutionCompleted);

        if (strlen($feedbackContent)) {
            $feedbackContent = $this->questionOBJ->getHtmlQuestionContentPurifier()->purify($feedbackContent);
            $feedbackContent = ilRTE::_replaceMediaObjectImageSrc($feedbackContent, 0);
        }

        if ($feedbackId != -1) {
            $this->db->update(
                $this->getGenericFeedbackTableName(),
                array(
                    'feedback' => array('clob', $feedbackContent),
                    'tstamp' => array('integer', time())
                ),
                array(
                    'feedback_id' => array('integer', $feedbackId)
                )
            );
        } else {
            $feedbackId = $this->db->nextId($this->getGenericFeedbackTableName());

            $this->db->insert($this->getGenericFeedbackTableName(), array(
                'feedback_id' => array('integer', $feedbackId),
                'question_fi' => array('integer', $questionId),
                'correctness' => array('text', (int) $solutionCompleted), // text ?
                'feedback' => array('clob', $feedbackContent),
                'tstamp' => array('integer', time())
            ));
        }

        return $feedbackId;
    }

    abstract public function saveSpecificAnswerFeedbackContent(int $questionId, int $questionIndex, int $answerIndex, string $feedbackContent): int;

    final public function deleteGenericFeedbacks(int $questionId, bool $isAdditionalContentEditingModePageObject): void
    {
        if ($isAdditionalContentEditingModePageObject) {
            $this->ensurePageObjectDeleted(
                $this->getGenericFeedbackPageObjectType(),
                $this->getGenericFeedbackPageObjectId($questionId, true)
            );

            $this->ensurePageObjectDeleted(
                $this->getGenericFeedbackPageObjectType(),
                $this->getGenericFeedbackPageObjectId($questionId, false)
            );
        }

        $this->db->manipulateF(
            "DELETE FROM {$this->getGenericFeedbackTableName()} WHERE question_fi = %s",
            array('integer'),
            array($questionId)
        );
    }

    abstract public function deleteSpecificAnswerFeedbacks(int $questionId, bool $isAdditionalContentEditingModePageObject): void;

    final public function duplicateFeedback(int $originalQuestionId, int $duplicateQuestionId): void
    {
        $this->duplicateGenericFeedback($originalQuestionId, $duplicateQuestionId);
        $this->duplicateSpecificFeedback($originalQuestionId, $duplicateQuestionId);
    }

    private function duplicateGenericFeedback(int $originalQuestionId, int $duplicateQuestionId): void
    {
        $res = $this->db->queryF(
            "SELECT * FROM {$this->getGenericFeedbackTableName()} WHERE question_fi = %s",
            array('integer'),
            array($originalQuestionId)
        );

        while ($row = $this->db->fetchAssoc($res)) {
            $feedbackId = $this->db->nextId($this->getGenericFeedbackTableName());

            $this->db->insert($this->getGenericFeedbackTableName(), array(
                'feedback_id' => array('integer', $feedbackId),
                'question_fi' => array('integer', $duplicateQuestionId),
                'correctness' => array('text', $row['correctness']),
                'feedback' => array('clob', $row['feedback']),
                'tstamp' => array('integer', time())
            ));

            if ($this->questionOBJ->isAdditionalContentEditingModePageObject()) {
                $pageObjectType = $this->getGenericFeedbackPageObjectType();
                $this->duplicatePageObject($pageObjectType, $row['feedback_id'], $feedbackId, $duplicateQuestionId);
            }
        }
    }

    abstract protected function duplicateSpecificFeedback(int $originalQuestionId, int $duplicateQuestionId): void;

    final public function syncFeedback(int $originalQuestionId, int $duplicateQuestionId): void
    {
        $this->syncGenericFeedback($originalQuestionId, $duplicateQuestionId);
        $this->syncSpecificFeedback($originalQuestionId, $duplicateQuestionId);
    }

    private function syncGenericFeedback(int $originalQuestionId, int $duplicateQuestionId): void
    {
        // delete generic feedback of the original question
        $this->db->manipulateF(
            "DELETE FROM {$this->getGenericFeedbackTableName()} WHERE question_fi = %s",
            array('integer'),
            array($originalQuestionId)
        );

        // get generic feedback of the actual (duplicated) question
        $result = $this->db->queryF(
            "SELECT * FROM {$this->getGenericFeedbackTableName()} WHERE question_fi = %s",
            array('integer'),
            array($duplicateQuestionId)
        );

        // save generic feedback to the original question
        while ($row = $this->db->fetchAssoc($result)) {
            $nextId = $this->db->nextId($this->getGenericFeedbackTableName());

            $this->db->insert($this->getGenericFeedbackTableName(), array(
                'feedback_id' => array('integer', $nextId),
                'question_fi' => array('integer', $originalQuestionId),
                'correctness' => array('text', $row['correctness']),
                'feedback' => array('clob', $row['feedback']),
                'tstamp' => array('integer', time())
            ));
        }
    }

    final protected function getGenericFeedbackId(int $questionId, bool $solutionCompleted): int
    {
        $res = $this->db->queryF(
            "SELECT feedback_id FROM {$this->getGenericFeedbackTableName()} WHERE question_fi = %s AND correctness = %s",
            array('integer','text'),
            array($questionId, (int) $solutionCompleted)
        );

        $feedbackId = -1;
        if ($this->db->numRows($res)) {
            $row = $this->db->fetchAssoc($res);
            $feedbackId = (int) $row['feedback_id'];
        }

        return $feedbackId;
    }

    protected function isGenericFeedbackId(int $feedbackId): bool
    {
        $row = $this->db->fetchAssoc($this->db->queryF(
            "SELECT COUNT(feedback_id) cnt FROM {$this->getGenericFeedbackTableName()}
                                        WHERE question_fi = %s AND feedback_id = %s",
            array('integer','integer'),
            array($this->questionOBJ->getId(), $feedbackId)
        ));


        return (bool) $row['cnt'];
    }

    abstract protected function isSpecificAnswerFeedbackId(int $feedbackId): bool;

    final public function checkFeedbackParent(int $feedbackId): bool
    {
        if ($this->isGenericFeedbackId($feedbackId)) {
            return true;
        }

        if ($this->isSpecificAnswerFeedbackId($feedbackId)) {
            return true;
        }

        return false;
    }

    abstract protected function syncSpecificFeedback(int $originalQuestionId, int $duplicateQuestionId): void;

    final protected function getGenericFeedbackTableName(): string
    {
        return self::TABLE_NAME_GENERIC_FEEDBACK;
    }

    final protected function getPageObjectNonEditableValueHTML(string $pageObjectType, int $pageObjectId): string
    {
        $link = $this->getPageObjectEditingLink($pageObjectType, $pageObjectId);
        $content = $this->getPageObjectContent($pageObjectType, $pageObjectId);

        return "$link<br /><br />$content";
    }

    public function getClassNameByType(string $a_type, bool $a_gui = false): string
    {
        $gui = ($a_gui) ? "GUI" : "";

        if ($a_type == ilAssQuestionFeedback::PAGE_OBJECT_TYPE_GENERIC_FEEDBACK) {
            return "ilAssGenFeedbackPage" . $gui;
        }

        //if ($a_type == ilAssQuestionFeedback::PAGE_OBJECT_TYPE_SPECIFIC_FEEDBACK) {
        return "ilAssSpecFeedbackPage" . $gui;
    }

    private function getPageObjectEditingLink(string $pageObjectType, int $pageObjectId): string
    {
        $cl = $this->getClassNameByType($pageObjectType, true);
        $this->ctrl->setParameterByClass($cl, 'feedback_type', $pageObjectType);
        $this->ctrl->setParameterByClass($cl, 'feedback_id', $pageObjectId);

        $linkHREF = $this->ctrl->getLinkTargetByClass($cl, 'edit');
        $linkTEXT = $this->lng->txt('tst_question_feedback_edit_page');

        return "<a href='$linkHREF'>$linkTEXT</a>";
    }

    final public function setPageObjectOutputMode(string $page_obj_output_mode): void
    {
        $this->page_obj_output_mode = $page_obj_output_mode;
    }

    final public function getPageObjectOutputMode(): string
    {
        return $this->page_obj_output_mode;
    }

    final protected function getPageObjectContent(string $pageObjectType, int $pageObjectId): string
    {
        $cl = $this->getClassNameByType($pageObjectType, true);

        $this->ensurePageObjectExists($pageObjectType, $pageObjectId);

        $mode = ($this->ctrl->isAsynch()) ? "presentation" : $this->getPageObjectOutputMode();

        $pageObjectGUI = new $cl($pageObjectId);
        $pageObjectGUI->setOutputMode($mode);

        return $pageObjectGUI->presentation($mode);
    }

    final protected function getPageObjectXML(string $pageObjectType, int $pageObjectId): string
    {
        $cl = $this->getClassNameByType($pageObjectType);

        $this->ensurePageObjectExists($pageObjectType, $pageObjectId);

        $pageObject = new $cl($pageObjectId);
        return $pageObject->getXMLContent();
    }

    private function ensurePageObjectExists(string $pageObjectType, int $pageObjectId): void
    {
        if ($pageObjectType == ilAssQuestionFeedback::PAGE_OBJECT_TYPE_GENERIC_FEEDBACK
            && !ilAssGenFeedbackPage::_exists($pageObjectType, $pageObjectId, '', true)) {
            $pageObject = new ilAssGenFeedbackPage();
            $pageObject->setParentId($this->questionOBJ->getId());
            $pageObject->setId($pageObjectId);
            $pageObject->createFromXML();
        }
        if ($pageObjectType == ilAssQuestionFeedback::PAGE_OBJECT_TYPE_SPECIFIC_FEEDBACK
            && !ilAssSpecFeedbackPage::_exists($pageObjectType, $pageObjectId, '', true)) {
            $pageObject = new ilAssSpecFeedbackPage();
            $pageObject->setParentId($this->questionOBJ->getId());
            $pageObject->setId($pageObjectId);
            $pageObject->createFromXML();
        }
    }

    final protected function createPageObject(string $pageObjectType, int $pageObjectId, string $pageObjectContent): void
    {
        $cl = $this->getClassNameByType($pageObjectType);

        $pageObject = new $cl();
        $pageObject->setParentId($this->questionOBJ->getId());
        $pageObject->setId($pageObjectId);
        $pageObject->setXMLContent($pageObjectContent);
        $pageObject->createFromXML();
    }

    final protected function duplicatePageObject(string $pageObjectType, int $originalPageObjectId, int $duplicatePageObjectId, int $duplicatePageObjectParentId): void
    {
        $this->ensurePageObjectExists($pageObjectType, $originalPageObjectId);

        $cl = $this->getClassNameByType($pageObjectType);

        $pageObject = new $cl($originalPageObjectId);
        $pageObject->setParentId($duplicatePageObjectParentId);
        $pageObject->setId($duplicatePageObjectId);
        $pageObject->createFromXML();
    }

    final protected function ensurePageObjectDeleted(string $pageObjectType, int $pageObjectId): void
    {
        if ($pageObjectType == ilAssQuestionFeedback::PAGE_OBJECT_TYPE_GENERIC_FEEDBACK) {
            if (ilAssGenFeedbackPage::_exists($pageObjectType, $pageObjectId)) {
                $pageObject = new ilAssGenFeedbackPage($pageObjectId);
                $pageObject->delete();
            }
        }
        if ($pageObjectType == ilAssQuestionFeedback::PAGE_OBJECT_TYPE_SPECIFIC_FEEDBACK) {
            if (ilAssSpecFeedbackPage::_exists($pageObjectType, $pageObjectId)) {
                $pageObject = new ilAssSpecFeedbackPage($pageObjectId);
                $pageObject->delete();
            }
        }
    }

    final protected function getGenericFeedbackPageObjectType(): string
    {
        return self::PAGE_OBJECT_TYPE_GENERIC_FEEDBACK;
    }

    final protected function getSpecificAnswerFeedbackPageObjectType(): string
    {
        return self::PAGE_OBJECT_TYPE_SPECIFIC_FEEDBACK;
    }

    final public static function isValidFeedbackPageObjectType(string $feedbackPageObjectType): bool
    {
        switch ($feedbackPageObjectType) {
            case self::PAGE_OBJECT_TYPE_GENERIC_FEEDBACK:
            case self::PAGE_OBJECT_TYPE_SPECIFIC_FEEDBACK:
                return true;
        }

        return false;
    }

    final protected function getGenericFeedbackPageObjectId(int $questionId, bool $solutionCompleted): int
    {
        $pageObjectId = $this->getGenericFeedbackId($questionId, $solutionCompleted);

        if ($pageObjectId == -1) {
            $pageObjectId = $this->saveGenericFeedbackContent($questionId, $solutionCompleted, '');
        }

        return $pageObjectId;
    }

    public function getGenericFeedbackExportPresentation(int $questionId, bool $solutionCompleted): string
    {
        if ($this->questionOBJ->isAdditionalContentEditingModePageObject()) {
            $genericFeedbackExportPresentation = $this->getPageObjectXML(
                $this->getGenericFeedbackPageObjectType(),
                $this->getGenericFeedbackPageObjectId($questionId, $solutionCompleted)
            );
        } else {
            $genericFeedbackExportPresentation = $this->getGenericFeedbackContent($questionId, $solutionCompleted);
        }

        return $genericFeedbackExportPresentation;
    }

    abstract public function getSpecificAnswerFeedbackExportPresentation(int $questionId, int $questionIndex, int $answerIndex): string;

    public function importGenericFeedback(int $questionId, bool $solutionCompleted, string $feedbackContent): void
    {
        if ($this->questionOBJ->isAdditionalContentEditingModePageObject()) {
            $pageObjectId = $this->getGenericFeedbackPageObjectId($questionId, $solutionCompleted);
            $pageObjectType = $this->getGenericFeedbackPageObjectType();

            $this->createPageObject($pageObjectType, $pageObjectId, $feedbackContent);
        } else {
            $this->saveGenericFeedbackContent($questionId, $solutionCompleted, $feedbackContent);
        }
    }

    abstract public function importSpecificAnswerFeedback(int $questionId, int $questionIndex, int $answerIndex, string $feedbackContent): void;

    public function migrateContentForLearningModule(ilAssSelfAssessmentMigrator $migrator, int $questionId): void
    {
        $this->saveGenericFeedbackContent($questionId, true, $migrator->migrateToLmContent(
            $this->getGenericFeedbackContent($questionId, true)
        ));

        $this->saveGenericFeedbackContent($questionId, false, $migrator->migrateToLmContent(
            $this->getGenericFeedbackContent($questionId, false)
        ));
    }

    protected function cleanupPageContent(string $content): string
    {
        $doc = new DOMDocument('1.0', 'UTF-8');
        if (@$doc->loadHTML('<html><body>' . $content . '</body></html>')) {
            $xpath = new DOMXPath($doc);
            $nodes_after_comments = $xpath->query('//comment()/following-sibling::*[1]');
            foreach ($nodes_after_comments as $node_after_comments) {
                if (trim($node_after_comments->nodeValue) === ''
                    && $node_after_comments->childElementCount === 0) {
                    return '';
                }
            }
        }
        return $content;
    }
}