Document activate-links and extend functionality for nested menu item…

…s and action urls (#6090)

src/OrchardCore.Modules/OrchardCore.Menu/Assets/js/activate-links.js

@@ -3,25 +3,40 @@
 
 (function ($) {
 
-    $.fn.activateLinks = function (options) {
+    $.fn.activateLinks = function (options, cb) {
 
         var settings = $.extend({
             // class to add to the selector
             class: "active",
             // custom selector based on the parent of the link
-            selector: null
+            selector: null,
+            // how many segments to remove from url in order to find active link in menu
+            traverse: 0
         }, options);
 
-        var currentUrl = window.location.href.replace(window.location.protocol + '//' + window.location.host, '');
+        var segments = window.location.href.replace(window.location.protocol + '//' + window.location.host, '').split("/");
+        var level = segments.length;
+        var minLevel = settings.traverse <= 0 ? level : level >= settings.traverse ? level - settings.traverse : level;
 
-        var items = $(this).find('a[href="' + currentUrl + '"]').parent();
+        while (level >= minLevel) {
+            var currentUrl = segments.join('/');
+            var items = $(this).find('a[href="' + currentUrl + '"]').parent();
 
-        if (settings.selector) {
-            items = items.find(settings.selector);
-        }
+            if (settings.selector) {
+                items = items.find(settings.selector);
+            }
 
-        items.addClass(settings.class)
+            if (items.length > 0) {
+                items.addClass(settings.class);
+                if (cb) {
+                    cb(items);
+                }
+                return this;
+            }
 
+            level -= 1;
+            segments = segments.slice(0, level);
+        }
         return this;
     };
-}(jQuery));
+}(jQuery));

src/OrchardCore.Modules/OrchardCore.Menu/wwwroot/Scripts/activate-links.js

@@ -6,21 +6,41 @@
 // This script is used to add a class on the active link of a menu.
 // Because Menus are often cached, the class needs to be set dynamically using JavaScript.
 (function ($) {
-  $.fn.activateLinks = function (options) {
+  $.fn.activateLinks = function (options, cb) {
     var settings = $.extend({
       // class to add to the selector
       "class": "active",
       // custom selector based on the parent of the link
-      selector: null
+      selector: null,
+      // how many segments to remove from url in order to find active link in menu
+      traverse: 0
     }, options);
-    var currentUrl = window.location.href.replace(window.location.protocol + '//' + window.location.host, '');
-    var items = $(this).find('a[href="' + currentUrl + '"]').parent();
+    var segments = window.location.href.replace(window.location.protocol + '//' + window.location.host, '').split("/");
+    var level = segments.length;
+    var minLevel = settings.traverse <= 0 ? level : level >= settings.traverse ? level - settings.traverse : level;
 
-    if (settings.selector) {
-      items = items.find(settings.selector);
+    while (level >= minLevel) {
+      var currentUrl = segments.join('/');
+      var items = $(this).find('a[href="' + currentUrl + '"]').parent();
+
+      if (settings.selector) {
+        items = items.find(settings.selector);
+      }
+
+      if (items.length > 0) {
+        items.addClass(settings["class"]);
+
+        if (cb) {
+          cb(items);
+        }
+
+        return this;
+      }
+
+      level -= 1;
+      segments = segments.slice(0, level);
     }
 
-    items.addClass(settings["class"]);
     return this;
   };
 })(jQuery);

src/docs/reference/modules/Menu/README.md

@@ -174,6 +174,55 @@ else
 }
 ```
 
+## Mark active item in a menu
+
+Some times you need to set a menu item as active if it is the currently displayed one.
+Because menus are cached, this must be done from javascript. OrchardCore.Menu module provides a script to help you with that.
+
+``` javascript
+function activateLinks(options,cb)
+```
+| Parameter | Description 
+| -------- | ----------- |
+| `options: {class:'active',selector:null,traverse:0}` | Use `class` to define what class you want to add to the parent of the anchor tag that has the current url as href. If you want to apply it to a child, set the `selector` property. Use the `traverse` to a positive number in order to seek a less specific url in the menu tree then the currently displayed on. ex. If you have a link to '/todo-items' in menu and you have navigated to '/todo-items/Create', it will try to find the item with traverse item less segments in the menu and activate it. |
+| `cb: function( items )` | If it finds an active item, the call back is hit for extra configuration. ex. Expand a menu item if the active one is nested.|
+
+### `activateLinks` usage in `Layout` file
+
+``` liquid tab="Liquid"
+...
+{% script at:"Foot", src:"~/OrchardCore.Menu/Scripts/activate-links.min.js", debug_src:"~/OrchardCore.Menu/Scripts/activate-links.js" %}
+...
+    <resources type="Footer" />
+...
+    <script type="text/javascript">
+        (function ($) {
+            $('#mainNav').activateLinks({ selector: 'a', traverse: 2 }, function (items) {
+                var parents = $(items).closest(".has-treeview")
+                parents.addClass('menu-open');
+            });
+        })(jQuery);
+    </script>
+...
+```
+
+``` html tab="Razor"
+...
+<script at="Foot" asp-src="~/OrchardCore.Menu/Scripts/activate-links.min.js" debug-src="~/OrchardCore.Menu/Scripts/activate-links.js"></script>
+...
+<resources type="Footer" />
+...
+<script type="text/javascript">
+    (function ($) {
+        $('#mainNav').activateLinks({ selector: 'a', traverse: 2 }, function (items) {
+            var parents = $(items).closest(".has-treeview")
+            parents.addClass('menu-open');
+        });
+    })(jQuery);
+</script>
+...
+```
+
 ## CREDITS
 
 ### nestedSortable jQuery plugin