Differences

This shows you the differences between two versions of the page.

--- plugin:acmenu [2017-06-27 09:42] – [Known Bugs and Issues] torpedo
+++ plugin:acmenu [2024-02-09 23:25] (current) – [AcMenu Plugin] torpedo
@@ Line 2: / Line 2: @@
 ---- plugin ----
-description: An accordion menu for namespaces and relative pages.
+description: An accordion menu for namespaces and relative pages
 author     : Torpedo
 email      : dcstoyanov@gmail.com
 type       : syntax
-lastupdate : 2017-04-27
+lastupdate : 2023-11-22
-compatible : 2017-02-19 "Frusterick Manners"
+compatible : 2017-02-19 "Frusterick Manners", 2018-04-22 "Greebo", 2020-06-01 "Hogfather", 2022-07-31 "Igor", 2023-04-04 "Jack Jackrum", 2024-02-06 "Kaos"
 depends    :
 conflicts  :
@@ Line 13: / Line 13: @@
 tags       : menu, navigation
-downloadurl: https://bitbucket.org/Torpedo/acmenu/get/master.zip
+downloadurl: https://github.com/tormec/AcMenu/archive/master.zip
-bugtracker : https://bitbucket.org/Torpedo/acmenu/issues?status=new&status=open
+bugtracker : https://github.com/tormec/AcMenu/issues
-sourcerepo : https://bitbucket.org/Torpedo/acmenu/src
+sourcerepo : https://github.com/tormec/AcMenu
 donationurl:
@@ Line 24: / Line 24: @@
 ===== Description =====
-AcMenu provides an accordion menu which lists the content of namespaces in a tree-like format.
+AcMenu provides an accordion menu that lists the content of namespaces in a tree-like format.
-The tree is built starting from the namespace where the AcMenu's syntax lives till the very end namespace.
-This plugin respects the [[:ACL]] rules and the [[config:sneaky_index]], [[config:hidepages]] options that come with your DokuWiki configuration.
+The namespace tree is built starting from the namespace where the plugin syntax is placed and going through all the sub-namespaces but those containing a sidebar page.
+This plugin respects the [[:ACL]] rules besides the [[config:sneaky_index]] and [[config:hidepages]] options that come with your DokuWiki configuration.
 ===== Installation =====
-Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually.
+Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:plugin_installation_instructions|Plugin Installation Instructions]] on how to install plugins manually.
 ===== Syntax =====
-In the sidebar page, use the syntax:
+In the [[config:sidebar|sidebar]] page, use the syntax:
 <code>
 <acmenu>
@@ Line 45: / Line 46: @@
 ===== Examples =====
-Just some screenshots to give you an overall idea of the final result.
+Just some screenshots to give an overall idea of the final result.
-Suppose you want to split your main wiki in two sub-wiki independent between them, as follows:
+It is supposed the following wiki structure which has two separate sidebars:
 <code>
 +--sidebar.txt
 +--start.txt
-+--branch-a
++--products
-|  +--sidebar.txt
 |  +--start.txt
-|  +--products
+|  +--product_a.txt
-|  |  +--start.txt
++--services
-|  +--services
+|  +--start.txt
-|  |  +--start.txt
+|  +--service_a.txt
-|  +--private
++--branch
-|     +--start.txt
-|     +--confidential.txt
-+--branch-b
    +--sidebar.txt
    +--start.txt
+   +--private
+   |  +--start.txt
+   |  +--confidential.txt
    +--products
    |  +--start.txt
+   |  +--product_b.txt
    +--services
-   |  +--start.txt
-   +--private
       +--start.txt
-      +--confidential.txt
+      +--service_b.txt
 </code>
-Than you can populate each ''sidebar.txt'' in the following manner:
+where the two ''sidebar.txt'' have the syntax, respectively:
   * in '':sidebar.txt'' <code>
 <acmenu>
 </code>
-  * in '':branch-a:sidebar.txt'' <code>
+  * in '':branch:sidebar.txt'' <code>
-[[..:start| Back to Main]]
+[[..:start| Go Back]]
 <acmenu>
-</code>
+</code> where the ''Go Back'' link is made according to the [[:namespaces|namespaces]] criterion.
-  * in '':branch-b:sidebar.txt'' <code>
-[[..:start| Back to Main]]
+When a visitor is in '':start.txt'' the plugin shows the complete namespace tree collapsed except the namespace containing the root sidebar.
-<acmenu>
-</code>
-When a visitor is in '':start.txt'', the plugin shows the complete namespace tree collapsed except the namespace in which the ''sidebar.txt'' with AcMenu's syntax it is. Only if the visitor's browser has JavaScript disabled all namespaces reveal their content so that it's possible to continue the navigation.
+If the visitor decides to open the sub-namespace '':branch'', the plugin shows only its sidebar.
-If the visitor decides to open a '':branch-*'' or any its sub-namespaces '':branch-*:*'', the AcMenu shows only the sidebar relative to the current branch.
+To deny access to certain namespaces or pages, the appropriate rule in the [[:ACL]] management must be set. In addition, it's possible to conceal those namespaces for which the visitor has no read permission defining the [[config:sneaky_index]] option in your Configuration Manager.
-If the visitor is a guest and he doesn't have the permission to enter in any '':branch-*:private'' area, you should set the appropriate rule in the [[:ACL]] management. Furthermore you can hide to him the '':branch-*:private'' namespace setting up the [[config:sneaky_index]] option in your Configuration Manager.
+Furthermore, it's possible to hide the ''sidebar.txt'' and the ''start.txt'' pages((The explanation of the regular expression used in this example is the following:
+  - alternative matches must be separated by ''|''
+  - to match a word at the end of a line the ''$'' symbol must be used
+  - to be sure that the word to match is preceded by '':'' or by any character ''.'' followed by '':'' use ''%%(?<= )%%''
-If the visitor is a user registered and has the permission to enter in any '':branch-*:private'' area but not to see the '':branch-*:confidential.txt'' page, you should set the appropriate rule in the [[:ACL]] management.
+With that syntax, the following pages will be hidden:
+  * '':sidebar''
+  * '':namespace:sidebar''
+  * '':namespace:start''
+Whereas the following one will remain visible:
+  * '':start''
-Furthermore it's possible to hide all ''sidebar.txt'' page using the [[config:hidepages]] option in your Configuration Manager:
+Even if the hidden pages are not listed among the search results, they will still be reachable by typing their exact path in the search bar (eg. ''sidebar'' or ''namespace:sidebar'').
+)) using the [[config:hidepages]] option in your Configuration Manager:
 <code>
-^:(?:.*sidebar)
+(?<=:)sidebar$|(?<=.:)start$|other-matches
 </code>
-{{ https://bitbucket.org/Torpedo/acmenu/downloads/acmenu.png?nolink&recache }}
+The following image is the behavior of the AcMenu plugin in action.
+{{ https://raw.githubusercontent.com/tormec/AcMenu/master/images/acmenu.gif?nolink&recache }}
-Since this plugin uses cookies to remember the page visited (they are automatically deleted as soon as the window browser is closed) if the visitor come back to '':start.txt'' the branch and its sub-namespaces opened will stay open.
+Since this plugin uses cookies to remember the pages visited (they are automatically deleted as soon as the window browser is closed) if the visitor comes back to '':start.txt'' every namespace untoggled will remain so.
 The order in which the directory tree is presented is the following:
@@ Line 107: / Line 114: @@
 This means that, if the option [[config:useheading]] is enabled, it's possible to force the order of files using a progressive numeration in the first heading of each file.
+Note also that the [[config:startpage]] is intentionally always kept on top of its menu and it's never renamed with its first heading, in order to provide a visual reference for the navigation.
-===== Configuration and Settings =====
-==== Menu behaviour ====
-The navigation through namespaces and the links to the relative pages work as follows:
+===== Customization =====
-  * on namespace:
-    * one click: shows/hides the relative content;
-    * double click: opens the relative start page;
-  * on page:
-    * one click: opens the relative page.
-==== Hide namespaces and pages ====
+If doesn't exist yet, create a [[devel:css#user_styles|user-style]] CSS ''conf/userstyle.css'' and replace the plugin's CSS instructions as you please.
-First, set the appropriate permissions in your [[:ACL]] management.
+For instance, the list item markers can be changed with the following code:
-Then, use the options:
+<code css userstyle.css>
-  * [[config:sneaky_index]]: to hide namespaces.
+.acmenu ul.idx li.closed {
-  * [[config:hidepages]]: to hide pages;
+    list-style-image: url(../lib/images/plus.gif);
+}
+.acmenu ul.idx li.open {
+    list-style-image: url(../lib/images/minus.gif);
+}
+</code>
-===== Troubleshooting =====
+It's also possible to change the DokuWiki's style only inside the plugin:
+<code css userstyle.css>
+.dokuwiki .acmenu .aside a:visited {
+background-color: none;
+}
-**Symptom:** AcMenu doesn't show/hide namespace's content.
+.dokuwiki .acmenu span.curid a {
+background-color: silver;
+color: black;
+}
+</code>
-**Possible solution:** be sure that JavaScript is enabled in your browser, otherwise all namespaces remain open showing their content.
+Use the Inspect Tool provided with your browser to test all the possible styles.
-----
-===== Development =====
-==== Known Bugs and Issues ====
+===== Troubleshooting =====
-Please, use the relative bug tracker or write here and then I will move there.\\ --- [[dcstoyanov@gmail.com|Torpedo]] //2017-03-09 16:32//
+**Symptom:** AcMenu isn't keeping unfolded any previously opened namespace.
-==== ToDo/Wish List ====
+**Possible solution:** be sure that JavaScript and cookies are enabled in your browser, otherwise AcMenu forgets the previously namespaces untoggled whenever a page is loaded.
-Let me know what do you think about this plugin and how can I improve its functionality.\\ --- [[dcstoyanov@gmail.com|Torpedo]] //2017-03-09 16:33//
->I'd love to have the menu always stay open -- any ideas? [[kmarwahaha@gmail.com|marwahaha]] //2017-06-21//
->>The purpose of this plugin is to provide a menu whose items are shown or hidden at user discretion rather than offer a static menu.\\ For a menu that always stays open it's better to use plugins that create a list of pages belong to a given namespace.\\ Also notice that since this plugin //i)// create the menu in the sidebar, which doesn't offer much space in width-wise, and //ii)// it uses indentation to render nested namespaces, long menus or long names would be printed in a very ugly way. --- [[dcstoyanov@gmail.com|Torpedo]] //2017-06-27 09:37//