Feature: Add a type for smart menu item to use mailto links, resolves #702 (#1079)

Author: scha-ms

CHANGES.md

@@ -4,6 +4,10 @@ moodle-theme_boost_union
 Changes
 -------
 
+### Unreleased
+
+* 2025-10-23 - Feature: Add a type for smart menu item to use mailto links, resolves #702
+
 ### v5.0-r11
 
 * 2025-10-22 - Bugfix: Solve possible performance issues due to hook override cache being invalidated by CLI scripts, resolves #1076

classes/form/smartmenu_item_edit_form.php

@@ -109,6 +109,12 @@ public function definition() {
         $mform->hideIf('url', 'type', 'neq', smartmenu_item::TYPESTATIC);
         $mform->addHelpButton('url', 'smartmenusmenuitemurl', 'theme_boost_union');
 
+        // Add menu item email (for the mailto menu item type) as input element.
+        $mform->addElement('text', 'email', get_string('smartmenusmenuitememail', 'theme_boost_union'));
+        $mform->setType('email', PARAM_EMAIL);
+        $mform->hideIf('email', 'type', 'neq', smartmenu_item::TYPEMAILTO);
+        $mform->addHelpButton('email', 'smartmenusmenuitememail', 'theme_boost_union');
+
         // Add mode as select element.
         $modeoptions = smartmenu_item::get_mode_options();
         $mform->addElement('select', 'mode', get_string('smartmenusmenuitemmode', 'theme_boost_union'), $modeoptions);
@@ -704,6 +710,13 @@ public function validation($data, $files) {
             }
         }
 
+        if ($data['type'] == smartmenu_item::TYPEMAILTO) {
+            // Verify that the email field is not empty.
+            if (empty($data['email'])) {
+                $errors['email'] = get_string('smartmenusmenuitememail_required', 'theme_boost_union');
+            }
+        }
+
         // Return errors.
         return $errors;
     }

classes/smartmenu_item.php

@@ -76,6 +76,12 @@ class smartmenu_item {
      */
     const TYPEDIVIDER = 4;
 
+    /**
+     * Represents the type of a mailto element.
+     * @var int
+     */
+    const TYPEMAILTO = 5;
+
     /**
      * Represents the completion status of an item where the status is 'enrolled'.
      * @var int
@@ -691,6 +697,24 @@ protected function generate_static_item() {
         );
     }
 
+    /**
+     * Generate the item as mailto menu item.
+     *
+     * @return string
+     */
+    protected function generate_mailto_item() {
+
+        $mailto = 'mailto:' . $this->item->email;
+
+        return $this->generate_node_data(
+            $this->item->title, // Title.
+            $mailto, // Mailto link.
+            null, // Default key.
+            $this->item->tooltip,
+            // Tooltip.
+        );
+    }
+
     /**
      * Generate the dynamic courses based on the conditions of categories, enrollmentrole,
      * daterange (Past, Present, Future), and customfields.
@@ -1220,6 +1244,7 @@ public function build() {
         $types = [
             self::TYPESTATIC => 'static',
             self::TYPEDYNAMIC => 'dynamic',
+            self::TYPEMAILTO => 'mailto',
             self::TYPEHEADING => 'heading',
             self::TYPEDOCS => 'docs',
             self::TYPEDIVIDER => 'divider',
@@ -1244,6 +1269,13 @@ public function build() {
                 $cacheable = true;
                 break;
 
+            case self::TYPEMAILTO:
+                $mailto = $this->generate_mailto_item();
+                $result = [$mailto];
+                $type = 'mailto';
+                $cacheable = true;
+                break;
+
             case self::TYPEDOCS:
                 $docs = $this->generate_docs_item();
 
@@ -1553,6 +1585,7 @@ public static function load_custom_field_config(&$mform) {
     public static function get_types(?int $type = null) {
         $types = [
                 self::TYPESTATIC => get_string('smartmenusmenuitemtypestatic', 'theme_boost_union'),
+                self::TYPEMAILTO => get_string('smartmenusmenuitemtypemailto', 'theme_boost_union'),
                 self::TYPEHEADING => get_string('smartmenusmenuitemtypeheading', 'theme_boost_union'),
                 self::TYPEDOCS => get_string('smartmenusmenuitemtypedocs', 'theme_boost_union'),
                 self::TYPEDYNAMIC => get_string('smartmenusmenuitemtypedynamiccourses', 'theme_boost_union'),

db/install.xml

@@ -79,6 +79,7 @@
         <FIELD NAME="type" TYPE="int" LENGTH="9" NOTNULL="false" DEFAULT="1" SEQUENCE="false"/>
         <FIELD NAME="sortorder" TYPE="int" LENGTH="18" NOTNULL="false" SEQUENCE="false"/>
         <FIELD NAME="url" TYPE="text" NOTNULL="false" SEQUENCE="false"/>
+        <FIELD NAME="email" TYPE="text" NOTNULL="false" SEQUENCE="false"/>
         <FIELD NAME="category" TYPE="text" NOTNULL="false" SEQUENCE="false"/>
         <FIELD NAME="category_subcats" TYPE="int" LENGTH="1" NOTNULL="false" SEQUENCE="false"/>
         <FIELD NAME="enrolmentrole" TYPE="text" NOTNULL="false" SEQUENCE="false"/>

db/upgrade.php

@@ -684,6 +684,22 @@ function xmldb_theme_boost_union_upgrade($oldversion) {
         upgrade_plugin_savepoint(true, 2025041419, 'theme', 'boost_union');
     }
 
+    if ($oldversion < 2025041428) {
+        // Define table theme_boost_union_menuitems to be altered.
+        $table = new xmldb_table('theme_boost_union_menuitems');
+
+        // Define field to be added to theme_boost_union_menuitems.
+        $field = new xmldb_field('email', XMLDB_TYPE_TEXT, null, null, null, null, null, 'url');
+
+        // Conditionally launch adding field.
+        if (!$dbman->field_exists($table, $field)) {
+            $dbman->add_field($table, $field);
+        }
+
+        // Savepoint reached.
+        upgrade_plugin_savepoint(true, 2025041428, 'theme', 'boost_union');
+    }
+
     // Load the builtin SCSS snippets into the database.
     // This is done with every plugin update, regardless of the plugin version.
     snippets::add_builtin_snippets();

lang/en/theme_boost_union.php

@@ -1489,6 +1489,9 @@
 $string['smartmenusmenuitemdeleteconfirm'] = 'Are you sure you want to delete this menu item from the smart menu?';
 $string['smartmenusmenuitemdeletesuccess'] = 'Smart menu item deleted successfully';
 $string['smartmenusmenuitemdisplayallcourses'] = 'Show hidden courses';
+$string['smartmenusmenuitememail'] = 'Recipient\'s email address';
+$string['smartmenusmenuitememail_help'] = 'The recipient\'s email address for the menu item. This will be used to build a mailto link that opens when the menu item is clicked.';
+$string['smartmenusmenuitememail_required'] = 'Required – Please enter a valid email address without the \'mailto:\' prefix.';
 $string['smartmenusmenuitemhidehiddencourses'] = 'Hide hidden courses';
 $string['smartmenusmenuitemhiddencoursessorting_help'] = 'Choose how hidden courses should be sorted in the course list of the dynamic courses menu items.';
 $string['smartmenusmenuitemhiddencoursessorting'] = 'Hidden courses sorting';
@@ -1558,11 +1561,12 @@
 $string['smartmenusmenuitemtooltip'] = 'Tooltip';
 $string['smartmenusmenuitemtooltip_help'] = 'The tooltip which will be displayed when the user hovers over the menu item.';
 $string['smartmenusmenuitemtype'] = 'Menu item type';
-$string['smartmenusmenuitemtype_help'] = '<p>Select the type of menu item you want to create, choosing between static, heading, moodle documentation, dynamic courses, and divider.</p><ul><li>Static: A static menu item is simply a link to a fixed URL that does not change.</li><li>Heading: A heading menu item is used to group related menu items together under a common heading. It does not have a link and is not clickable.</li><li>Separator: A dividerenu item displays a horizontal line in the menu to visually separate groups of menu items.</li><li>Moodle documentation: A moodle documenation menu item is used to link to the corresponding MoodleDocs article, similar to the MoodleDocs link which is located in the Moodle footer (questionmark icon).</li><li>Dynamic courses: A dynamic courses menu item is used to display a list of courses based on certain criteria, such as course category, course enrolment role, course completion status or date range. The content displayed in a dynamic courses menu item will update automatically as the criteria changes.</li></ul>';
+$string['smartmenusmenuitemtype_help'] = '<p>Select the type of menu item you want to create, choosing between static, mailto, heading, moodle documentation, dynamic courses, and divider.</p><ul><li>Static: A static menu item is simply a link to a fixed URL that does not change.</li><li>Mailto: A mailto menu item opens the user\'s default email client to compose a message to the specified email address.</li><li>Heading: A heading menu item is used to group related menu items together under a common heading. It does not have a link and is not clickable.</li><li>Separator: A dividerenu item displays a horizontal line in the menu to visually separate groups of menu items.</li><li>Moodle documentation: A moodle documenation menu item is used to link to the corresponding MoodleDocs article, similar to the MoodleDocs link which is located in the Moodle footer (questionmark icon).</li><li>Dynamic courses: A dynamic courses menu item is used to display a list of courses based on certain criteria, such as course category, course enrolment role, course completion status or date range. The content displayed in a dynamic courses menu item will update automatically as the criteria changes.</li></ul>';
 $string['smartmenusmenuitemtypedocs'] = 'Moodle documentation';
 $string['smartmenusmenuitemtypedynamiccourses'] = 'Dynamic courses';
 $string['smartmenusmenuitemtypeheading'] = 'Heading';
 $string['smartmenusmenuitemtypedivider'] = 'Divider';
+$string['smartmenusmenuitemtypemailto'] = 'Mailto';
 $string['smartmenusmenuitemtypestatic'] = 'Static';
 $string['smartmenusmenuitemurl'] = 'Menu item URL';
 $string['smartmenusmenuitemurl_help'] = 'The static URL for the menu item. This is the link that will be followed when the menu item is clicked.';

tests/behat/theme_boost_union_smartmenusettings_menuitems_mailto.feature

@@ -0,0 +1,22 @@
+@theme @theme_boost_union @theme_boost_union_smartmenusettings @theme_boost_union_smartmenusettings_menuitems @theme_boost_union_smartmenusettings_menuitems_mailto
+Feature: Configuring the theme_boost_union plugin on the "Smart menus" page, using a mailto item
+  In order to use the features
+  As admin
+  I need to be able to configure the theme Boost Union plugin
+
+  Background:
+    Given the following "theme_boost_union > smart menu" exists:
+      | title    | Quick links                                      |
+      | location | Main navigation, Menu bar, User menu, Bottom bar |
+    And the following "theme_boost_union > smart menu item" exists:
+      | menu     | Quick links          |
+      | title    | Mail                 |
+      | itemtype | Mailto               |
+      | email    | test@test.com        |
+
+  @javascript
+  Scenario: Smartmenus: Menu items: Mailto - Add a smart menu documentation link item in a smart menu
+    When I log in as "admin"
+    And I navigate to "Appearance > Boost Union > Smart menus" in site administration
+    Then I should see smart menu "Quick links" item "Mail" in location "Main, Menu, User, Bottom"
+    And the "href" attribute of "//div[@class='primary-navigation']//a[contains(normalize-space(.), 'Mail')]" "xpath_element" should contain "mailto:[email protected]"

tests/generator/lib.php

@@ -157,6 +157,14 @@ public function create_smartmenu_item(array $data): \stdClass {
             $url = $data['url'];
         }
 
+        $email = null;
+        if ($type === smartmenu_item::TYPEMAILTO) {
+            if (empty($data['email'])) {
+                throw new Exception('Email is required when type is mailto.');
+            }
+            $email = $data['email'];
+        }
+
         $category = json_encode($data['category'] ?? []);
         $categorysubcats = $data['category_subcats'] ?? false;
         $enrolmentrole = json_encode($data['enrolmentrole'] ?? []);
@@ -224,6 +232,7 @@ public function create_smartmenu_item(array $data): \stdClass {
             'type' => $type,
             'sortorder' => $sortorder,
             'url' => $url,
+            'email' => $email,
             'category' => $category,
             'category_subcats' => $categorysubcats,
             'enrolmentrole' => $enrolmentrole,

version.php

@@ -25,7 +25,7 @@
 defined('MOODLE_INTERNAL') || die();
 
 $plugin->component = 'theme_boost_union';
-$plugin->version = 2025041427;
+$plugin->version = 2025041428;
 $plugin->release = 'v5.0-r11';
 $plugin->requires = 2025041401;
 $plugin->supported = [500, 500];