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

namespace core\output;

use core\exception\coding_exception;

use core\lang_string;

use core\output\local\action_menu\subpanel;

use core\output\action_menu\link as action_menu_link;

use core\output\action_menu\filler as action_menu_filler;

use moodle_page;

use stdClass;

/**

 * An action menu.

 *

 * This action menu component takes a series of primary and secondary actions.

 * The primary actions are displayed permanently and the secondary attributes are displayed within a drop

 * down menu.

 *

 * @package core

 * @category output

 * @copyright 2013 Sam Hemelryk

 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

class action_menu implements renderable, templatable {

    /**

     * Top right alignment.

     */

    const TL = 1;

    /**

     * Top right alignment.

     */

    const TR = 2;

    /**

     * Top right alignment.

     */

    const BL = 3;

    /**

     * Top right alignment.

     */

    const BR = 4;

    /**

     * The instance number. This is unique to this instance of the action menu.

     * @var int

     */

    protected $instance = 0;

    /**

     * An array of primary actions. Please use {@see action_menu::add_primary_action()} to add actions.

     * @var array

     */

    protected $primaryactions = [];

    /**

     * An array of secondary actions. Please use {@see action_menu::add_secondary_action()} to add actions.

     * @var array

     */

    protected $secondaryactions = [];

    /**

     * An array of attributes added to the container of the action menu.

     * Initialised with defaults during construction.

     * @var array

     */

    public $attributes = [];

    /**

     * An array of attributes added to the container of the primary actions.

     * Initialised with defaults during construction.

     * @var array

     */

    public $attributesprimary = [];

    /**

     * An array of attributes added to the container of the secondary actions.

     * Initialised with defaults during construction.

     * @var array

     */

    public $attributessecondary = [];

    /**

     * The string to use next to the icon for the action icon relating to the secondary (dropdown) menu.

     * @var array

     */

    public $actiontext = null;

    /**

     * The string to use for the accessible label for the menu.

     * @var array

     */

    public $actionlabel = null;

    /**

     * An icon to use for the toggling the secondary menu (dropdown).

     * @var pix_icon

     */

    public $actionicon;

    /**

     * Any text to use for the toggling the secondary menu (dropdown).

     * @var string

     */

    public $menutrigger = '';

    /**

     * An array of attributes added to the trigger element of the secondary menu.

     * @var array

     */

    public $triggerattributes = [];

    /**

     * Any extra classes for toggling to the secondary menu.

     * @var string

     */

    public $triggerextraclasses = '';

    /**

     * Place the action menu before all other actions.

     * @var bool

     */

    public $prioritise = false;

    /**

     * Dropdown menu alignment class.

     * @var string

     */

    public $dropdownalignment = '';

    /**

     * Constructs the action menu with the given items.

     *

     * @param array $actions An array of actions (action_menu_link|pix_icon|string).

     */

    public function __construct(array $actions = []) {

        static $initialised = 0;

        $this->instance = $initialised;

        $initialised++;

        $this->attributes = [

            'id' => 'action-menu-' . $this->instance,

            'class' => 'moodle-actionmenu',

            'data-enhance' => 'moodle-core-actionmenu',

        ];

        $this->attributesprimary = [

            'id' => 'action-menu-' . $this->instance . '-menubar',

            'class' => 'menubar',

        ];

        $this->attributessecondary = [

            'id' => 'action-menu-' . $this->instance . '-menu',

            'class' => 'menu',

            'data-rel' => 'menu-content',

            'aria-labelledby' => 'action-menu-toggle-' . $this->instance,

            'role' => 'menu',

        ];

        $this->dropdownalignment = 'dropdown-menu-end';

        foreach ($actions as $action) {

            $this->add($action);

        }

    }

    /**

     * Sets the label for the menu trigger.

     *

     * @param string $label The text

     */

    public function set_action_label($label) {

        $this->actionlabel = $label;

    }

    /**

     * Sets the menu trigger text.

     *

     * @param string $trigger The text

     * @param string $extraclasses Extra classes to style the secondary menu toggle.

     */

    public function set_menu_trigger($trigger, $extraclasses = '') {

        $this->menutrigger = $trigger;

        $this->triggerextraclasses = $extraclasses;

    }

    /**

     * Classes for the trigger menu

     */

    const DEFAULT_KEBAB_TRIGGER_CLASSES = 'btn btn-icon d-flex no-caret';

    /**

     * Setup trigger as in the kebab menu.

     *

     * @param string|null $triggername

     * @param core_renderer|null $output

     * @param string|null $extraclasses extra classes for the trigger {@see self::set_menu_trigger()}

     * @throws coding_exception

     */

    public function set_kebab_trigger(

        ?string $triggername = null,

        ?core_renderer $output = null,

        ?string $extraclasses = ''

    ) {

        global $OUTPUT;

        if (empty($output)) {

            $output = $OUTPUT;

        }

        $label = $triggername ?? get_string('actions');

        $triggerclasses = self::DEFAULT_KEBAB_TRIGGER_CLASSES . ' ' . $extraclasses;

        $icon = $output->pix_icon('i/menu', $label);

        $this->set_menu_trigger($icon, $triggerclasses);

    }

    /**

     * Return true if there is at least one visible link in the menu.

     *

     * @return bool

     */

    public function is_empty() {

        return !count($this->primaryactions) && !count($this->secondaryactions);

    }

    /**

     * Initialises JS required fore the action menu.

     * The JS is only required once as it manages all action menu's on the page.

     *

     * @param moodle_page $page

     */

    public function initialise_js(moodle_page $page) {

        static $initialised = false;

        if (!$initialised) {

            $page->requires->yui_module('moodle-core-actionmenu', 'M.core.actionmenu.init');

            $initialised = true;

        }

    }

    /**

     * Adds an action to this action menu.

     *

     * @param action_link|pix_icon|subpanel|string $action

     */

    public function add($action) {

        if ($action instanceof subpanel) {

            $this->add_secondary_subpanel($action);

        } else if ($action instanceof action_link) {

            if ($action->primary) {

                $this->add_primary_action($action);

            } else {

                $this->add_secondary_action($action);

            }

        } else if ($action instanceof pix_icon) {

            $this->add_primary_action($action);

        } else {

            $this->add_secondary_action($action);

        }

    }

    /**

     * Adds a secondary subpanel.

     * @param subpanel $subpanel

     */

    public function add_secondary_subpanel(subpanel $subpanel) {

        $this->secondaryactions[] = $subpanel;

    }

    /**

     * Adds a primary action to the action menu.

     *

     * @param action_menu_link|action_link|pix_icon|string $action

     */

    public function add_primary_action($action) {

        if ($action instanceof action_link || $action instanceof pix_icon) {

            $action->attributes['role'] = 'menuitem';

            $action->attributes['tabindex'] = '-1';

            if ($action instanceof action_menu_link) {

                $action->actionmenu = $this;

            }

        }

        $this->primaryactions[] = $action;

    }

    /**

     * Adds a secondary action to the action menu.

     *

     * @param action_link|pix_icon|string $action

     */

    public function add_secondary_action($action) {

        if ($action instanceof action_link || $action instanceof pix_icon) {

            $action->attributes['role'] = 'menuitem';

            $action->attributes['tabindex'] = '-1';

            if ($action instanceof action_menu_link) {

                $action->actionmenu = $this;

            }

        }

        $this->secondaryactions[] = $action;

    }

    /**

     * Returns the primary actions ready to be rendered.

     *

     * @param null|core_renderer $output The renderer to use for getting icons.

     * @return array

     */

    public function get_primary_actions(?core_renderer $output = null) {

        global $OUTPUT;

        if ($output === null) {

            $output = $OUTPUT;

        }

        $pixicon = $this->actionicon;

        $linkclasses = ['toggle-display'];

        $title = '';

        if (!empty($this->menutrigger)) {

            $pixicon = '<b class="caret"></b>';

            $linkclasses[] = 'textmenu';

        } else {

            $title = new lang_string('actionsmenu', 'moodle');

            $this->actionicon = new pix_icon(

                't/edit_menu',

                '',

                'moodle',

                ['class' => 'iconsmall actionmenu', 'title' => '']

            );

            $pixicon = $this->actionicon;

        }

        if ($pixicon instanceof renderable) {

            $pixicon = $output->render($pixicon);

            if ($pixicon instanceof pix_icon && isset($pixicon->attributes['alt'])) {

                $title = $pixicon->attributes['alt'];

            }

        }

        $string = '';

        if ($this->actiontext) {

            $string = $this->actiontext;

        }

        $label = '';

        if ($this->actionlabel) {

            $label = $this->actionlabel;

        } else {

            $label = $title;

        }

        $actions = $this->primaryactions;

        $attributes = [

            'class' => implode(' ', $linkclasses),

            'title' => $title,

            'aria-label' => $label,

            'id' => 'action-menu-toggle-' . $this->instance,

            'role' => 'menuitem',

            'tabindex' => '-1',

        ];

        $link = html_writer::link('#', $string . $this->menutrigger . $pixicon, $attributes);

        if ($this->prioritise) {

            array_unshift($actions, $link);

        } else {

            $actions[] = $link;

        }

        return $actions;

    }

    /**

     * Returns the secondary actions ready to be rendered.

     * @return array

     */

    public function get_secondary_actions() {

        return $this->secondaryactions;

    }

    /**

     * Sets the selector that should be used to find the owning node of this menu.

     * @param string $selector A CSS/YUI selector to identify the owner of the menu.

     */

    public function set_owner_selector($selector) {

        $this->attributes['data-owner'] = $selector;

    }

    /**

     * @deprecated since Moodle 4.0, use action_menu::set_menu_left().

     */

    #[\core\attribute\deprecated('action_menu::set_menu_left', since: '4.0', mdl: 'MDL-72466', final: true)]

    public function set_alignment(): void {

        \core\deprecation::emit_deprecation([self::class, __FUNCTION__]);

    }

    /**

     * Returns a string to describe the alignment.

     *

     * @param int $align One of action_menu::TL, action_menu::TR, action_menu::BL, action_menu::BR.

     * @return string

     */

    protected function get_align_string($align) {

        switch ($align) {

            case self::TL:

                return 'tl';

            case self::TR:

                return 'tr';

            case self::BL:

                return 'bl';

            case self::BR:

                return 'br';

            default:

                return 'tl';

        }

    }

    /**

     * Aligns the left corner of the dropdown.

     *

     */

    public function set_menu_left() {

        $this->dropdownalignment = 'dropdown-menu-start';

    }

    /**

     * @deprecated since Moodle 4.3, use set_boundary() method instead.

     */

    #[\core\attribute\deprecated('action_menu::set_boundary', since: '4.3', mdl: 'MDL-77375', final: true)]

    public function set_constraint(): void {

        \core\deprecation::emit_deprecation([self::class, __FUNCTION__]);

    }

    /**

     * Set the overflow constraint boundary of the dropdown menu.

     * @see https://getbootstrap.com/docs/4.6/components/dropdowns/#options The 'boundary' option in the Bootstrap documentation

     *

     * @param string $boundary Accepts the values of 'viewport', 'window', or 'scrollParent'.

     * @throws coding_exception

     */

    public function set_boundary(string $boundary) {

        if (!in_array($boundary, ['viewport', 'window', 'scrollParent'])) {

            throw new coding_exception("HTMLElement reference boundaries are not supported." .

                "Accepted boundaries are 'viewport', 'window', or 'scrollParent'.", DEBUG_DEVELOPER);

        }

        $this->triggerattributes['data-boundary'] = $boundary;

    }

    /**

     * @deprecated since Moodle 3.2, use a list of action_icon instead.

     */

    #[\core\attribute\deprecated('Use a list of action_icons instead', since: '3.2', mdl: 'MDL-55904', final: true)]

    public function do_not_enhance() {

        \core\deprecation::emit_deprecation([self::class, __FUNCTION__]);

    }

    /**

     * Returns true if this action menu will be enhanced.

     *

     * @return bool

     */

    public function will_be_enhanced() {

        return isset($this->attributes['data-enhance']);

    }

    /**

     * Sets nowrap on items. If true menu items should not wrap lines if they are longer than the available space.

     *

     * This property can be useful when the action menu is displayed within a parent element that is either floated

     * or relatively positioned.

     * In that situation the width of the menu is determined by the width of the parent element which may not be large

     * enough for the menu items without them wrapping.

     * This disables the wrapping so that the menu takes on the width of the longest item.

     *

     * @param bool $value If true nowrap gets set, if false it gets removed. Defaults to true.

     */

    public function set_nowrap_on_items($value = true) {

        $class = 'nowrap-items';

        if (!empty($this->attributes['class'])) {

            $pos = strpos($this->attributes['class'], $class);

            if ($value === true && $pos === false) {

                // The value is true and the class has not been set yet. Add it.

                $this->attributes['class'] .= ' ' . $class;

            } else if ($value === false && $pos !== false) {

                // The value is false and the class has been set. Remove it.

                $this->attributes['class'] = substr($this->attributes['class'], $pos, strlen($class));

            }

        } else if ($value) {

            // The value is true and the class has not been set yet. Add it.

            $this->attributes['class'] = $class;

        }

    }

    /**

     * Add classes to the action menu for an easier styling.

     *

     * @param string $class The class to add to attributes.

     */

    public function set_additional_classes(string $class = '') {

        if (!empty($this->attributes['class'])) {

            $this->attributes['class'] .= " " . $class;

        } else {

            $this->attributes['class'] = $class;

        }

    }

    /**

     * Export for template.

     *

     * @param renderer_base $output The renderer.

     * @return stdClass

     */

    public function export_for_template(renderer_base $output) {

        $data = new stdClass();

        // Assign a role of menubar to this action menu when:

        // - it contains 2 or more primary actions; or

        // - if it contains a primary action and secondary actions.

        if (count($this->primaryactions) > 1 || (!empty($this->primaryactions) && !empty($this->secondaryactions))) {

            $this->attributes['role'] = 'menubar';

        }

        $attributes = $this->attributes;

        $data->instance = $this->instance;

        $data->classes = isset($attributes['class']) ? $attributes['class'] : '';

        unset($attributes['class']);

        $data->attributes = array_map(function ($key, $value) {

            return [ 'name' => $key, 'value' => $value ];

        }, array_keys($attributes), $attributes);

        $data->primary = $this->export_primary_actions_for_template($output);

        $data->secondary = $this->export_secondary_actions_for_template($output);

        $data->dropdownalignment = $this->dropdownalignment;

        return $data;

    }

    /**

     * Export the primary actions for the template.

     * @param renderer_base $output

     * @return stdClass

     */

    protected function export_primary_actions_for_template(renderer_base $output): stdClass {

        $attributes = $this->attributes;

        $attributesprimary = $this->attributesprimary;

        $primary = new stdClass();

        $primary->title = '';

        $primary->prioritise = $this->prioritise;

        $primary->classes = isset($attributesprimary['class']) ? $attributesprimary['class'] : '';

        unset($attributesprimary['class']);

        $primary->attributes = array_map(function ($key, $value) {

            return ['name' => $key, 'value' => $value];

        }, array_keys($attributesprimary), $attributesprimary);

        $primary->triggerattributes = array_map(function ($key, $value) {

            return ['name' => $key, 'value' => $value];

        }, array_keys($this->triggerattributes), $this->triggerattributes);

        $actionicon = $this->actionicon;

        if (!empty($this->menutrigger)) {

            $primary->menutrigger = $this->menutrigger;

            $primary->triggerextraclasses = $this->triggerextraclasses;

            if ($this->actionlabel) {

                $primary->title = $this->actionlabel;

            } else if ($this->actiontext) {

                $primary->title = $this->actiontext;

            } else {

                $primary->title = strip_tags($this->menutrigger);

            }

        } else {

            $primary->title = get_string('actionsmenu');

            $iconattributes = ['class' => 'iconsmall actionmenu', 'title' => $primary->title];

            $actionicon = new pix_icon('t/edit_menu', '', 'moodle', $iconattributes);

        }

        // If the menu trigger is within the menubar, assign a role of menuitem. Otherwise, assign as a button.

        $primary->triggerrole = 'button';

        if (isset($attributes['role']) && $attributes['role'] === 'menubar') {

            $primary->triggerrole = 'menuitem';

        }

        if ($actionicon instanceof pix_icon) {

            $primary->icon = $actionicon->export_for_pix();

            if (!empty($actionicon->attributes['alt'])) {

                $primary->title = $actionicon->attributes['alt'];

            }

        } else {

            $primary->iconraw = $actionicon ? $output->render($actionicon) : '';

        }

        $primary->actiontext = $this->actiontext ? (string) $this->actiontext : '';

        $primary->items = array_map(function ($item) use ($output) {

            $data = (object) [];

            if ($item instanceof action_menu_link) {

                $data->actionmenulink = $item->export_for_template($output);

            } else if ($item instanceof action_menu_filler) {

                $data->actionmenufiller = $item->export_for_template($output);

            } else if ($item instanceof action_link) {

                $data->actionlink = $item->export_for_template($output);

            } else if ($item instanceof pix_icon) {

                $data->pixicon = $item->export_for_template($output);

            } else {

                $data->rawhtml = ($item instanceof renderable) ? $output->render($item) : $item;

            }

            return $data;

        }, $this->primaryactions);

        return $primary;

    }

    /**

     * Export the secondary actions for the template.

     * @param renderer_base $output

     * @return stdClass

     */

    protected function export_secondary_actions_for_template(renderer_base $output): stdClass {

        $attributessecondary = $this->attributessecondary;

        $secondary = new stdClass();

        $secondary->classes = isset($attributessecondary['class']) ? $attributessecondary['class'] : '';

        unset($attributessecondary['class']);

        $secondary->attributes = array_map(function ($key, $value) {

            return ['name' => $key, 'value' => $value];

        }, array_keys($attributessecondary), $attributessecondary);

        $secondary->items = array_map(function ($item) use ($output) {

            $data = (object) [

                'simpleitem' => true,

            ];

            if ($item instanceof action_menu_link) {

                $data->actionmenulink = $item->export_for_template($output);

                $data->simpleitem = false;

            } else if ($item instanceof action_menu_filler) {

                $data->actionmenufiller = $item->export_for_template($output);

                $data->simpleitem = false;

            } else if ($item instanceof subpanel) {

                $data->subpanel = $item->export_for_template($output);

                $data->simpleitem = false;

            } else if ($item instanceof action_link) {

                $data->actionlink = $item->export_for_template($output);

            } else if ($item instanceof pix_icon) {

                $data->pixicon = $item->export_for_template($output);

            } else {

                $data->rawhtml = ($item instanceof renderable) ? $output->render($item) : $item;

            }

            return $data;

        }, $this->secondaryactions);

        return $secondary;

    }

}

// Alias this class to the old name.

// This file will be autoloaded by the legacyclasses autoload system.

// In future all uses of this class will be corrected and the legacy references will be removed.

class_alias(action_menu::class, \action_menu::class);