Proyectos de Subversion Moodle

<?php

// This file is part of Moodle - http://moodle.org/

//

// Moodle 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.

//

// Moodle 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 Moodle.  If not, see <http://www.gnu.org/licenses/>.

use Behat\Mink\Element\NodeElement;

use Behat\Mink\Exception\DriverException;

use Behat\Mink\Exception\ExpectationException;

/**

 * Behat helpers for TinyMCE Plugins.

 *

 * @package    editor_tiny

 * @category   test

 * @copyright  2022 Andrew Lyons <andrew@nicols.co.uk>

 */

trait editor_tiny_helpers {

    /**

     * Execute some JavaScript for a particular Editor instance.

     *

     * The editor instance is available on the 'instnace' variable.

     *

     * @param string $editorid The ID of the editor

     * @param string $code The code to execute

     */

    protected function execute_javascript_for_editor(string $editorid, string $code): void {

        $js = <<<EOF

        require(['editor_tiny/editor'], (editor) => {

            const instance = editor.getInstanceForElementId('{$editorid}');

            {$code}

        });

        EOF;

        $this->execute_script($js);

    }

    /**

     * Resolve some JavaScript for a particular Editor instance.

     *

     * The editor instance is available on the 'instnace' variable.

     * The code should return a value by passing it to the `resolve` function.

     *

     * @param string $editorid The ID of the editor

     * @param string $code The code to evaluate

     * @return string|null|array

     */

    protected function evaluate_javascript_for_editor(string $editorid, string $code) {

        $js = <<<EOF

        return new Promise((resolve, reject) => {

            require(['editor_tiny/editor'], (editor) => {

                const instance = editor.getInstanceForElementId('{$editorid}');

                if (!instance) {

                    reject("Instance '{$editorid}' not found");

                }

                {$code}

            });

        });

        EOF;

        return $this->evaluate_script($js);

    }

    /**

     * Set the value for the editor.

     *

     * Note: This function is called by the behat_form_editor class.

     * It is called regardless of the current default editor as editor selection is a user preference.

     * Therefore it must fail gracefully and only set a value if the editor instance was found on the page.

     *

     * @param string $editorid

     * @param string $value

     */

    public function set_editor_value(string $editorid, string $value): void {

        if (!$this->running_javascript()) {

            return;

        }

        $this->execute_javascript_for_editor($editorid, <<<EOF

            instance.setContent('{$value}');

            instance.undoManager.add();

            EOF);

    }

    /**

     * Store the current value of the editor, if it is a Tiny editor, to the textarea.

     *

     * @param string $editorid The ID of the editor.

     */

    public function store_current_value(string $editorid): void {

        $this->execute_javascript_for_editor($editorid, "instance?.save();");

    }

    /**

     * Ensure that the editor_tiny tag is in use.

     *

     * This function should be used for any step defined in this file.

     *

     * @throws DriverException Thrown if the editor_tiny tag is not specified for this file

     */

    protected function require_tiny_tags(): void {

        // Ensure that this step only runs in TinyMCE tags.

        if (!$this->has_tag('editor_tiny')) {

            throw new DriverException(

                'TinyMCE tests using this step must have the @editor_tiny tag on either the scenario or feature.'

            );

        }

    }

    /**

     * Get the Mink NodeElement of the <textarea> for the specified locator.

     *

     * Moodle mostly referes to the textarea, rather than the editor itself and interactions are translated to the

     * Editor using the TinyMCE API.

     *

     * @param string $locator A Moodle field locator

     * @return NodeElement The element found by the find_field function

     */

    protected function get_textarea_for_locator(string $locator): NodeElement {

        return $this->find_field($locator);

    }

    /**

     * Get the Mink NodeElement of the container for the specified locator.

     *

     * This is the top-most HTML element for the editor found by TinyMCE.getContainer().

     *

     * @param string $locator A Moodle field locator

     * @return NodeElement The Mink NodeElement representing the container.

     */

    protected function get_editor_container_for_locator(string $locator): NodeElement {

        $textarea = $this->get_textarea_for_locator($locator);

        $editorid = $textarea->getAttribute('id');

        $targetid = uniqid();

        $js = <<<EOF

            const container = instance.getContainer();

            if (!container.id) {

                container.id = '{$targetid}';

            }

            resolve(container.id);

        EOF;

        $containerid = $this->evaluate_javascript_for_editor($editorid, $js);

        return $this->find('css', "#{$containerid}");

    }

    /**

     * Get the name of the iframe relating to the editor.

     *

     * If no name is found, then add one.

     *

     * If the editor it not found, then throw an exception.

     *

     * @param string $locator The name of the editor

     * @return string The name of the iframe

     */

    protected function get_editor_iframe_name(string $locator): string {

        return $this->get_editor_iframe_name_for_element($this->get_textarea_for_locator($locator));

    }

    /**

     * Get the name of the iframe relating to the editor.

     *

     * If no name is found, then add one.

     *

     * If the editor it not found, then throw an exception.

     * @param NodeElement $editor The editor element

     * @return string The name of the iframe

     */

    protected function get_editor_iframe_name_for_element(NodeElement $editor): string {

        $editorid = $editor->getAttribute('id');

        // Ensure that a name is set on the iframe relating to the editorid.

        $js = <<<EOF

            if (!instance.iframeElement.name) {

                instance.iframeElement.name = '{$editorid}';

            }

            resolve(instance.iframeElement.name);

        EOF;

        return $this->evaluate_javascript_for_editor($editorid, $js);

    }

    /**

     * Normalise the fixture file path relative to the dirroot.

     *

     * @param string $filepath

     * @return string

     */

    protected function normalise_fixture_filepath(string $filepath): string {

        global $CFG;

        $filepath = str_replace('/', DIRECTORY_SEPARATOR, $filepath);

        if (!is_readable($filepath)) {

            $filepath = $CFG->dirroot . DIRECTORY_SEPARATOR . $filepath;

            if (!is_readable($filepath)) {

                throw new ExpectationException('The file to be uploaded does not exist.', $this->getSession());

            }

        }

        return $filepath;

    }

}