====== DokuWiki Nav Overlay Plugin ====== ---- plugin ---- description: Creates floating window at the template level that can be toggled open and closed into which navigation plugins (or any other pages) can be inserted. Can be configured for multiple namespaces, each with its own overlay. author : Myron Turner email : turnermm02@shaw.ca type : action lastupdate : 2020-08-03 compatible : Hrun, Detritus, Elenor of Tsort, Frusterick Manners, Greebo, Hogfather depends : conflicts : similar : tags : layers, menu, navigation, overlay, sidebar, popup downloadurl: https://github.com/turnermm/Dokuwiki-Nav-Overlay/archive/master.zip bugtracker : https://github.com/turnermm/Dokuwiki-Nav-Overlay/issues sourcerepo : https://github.com/turnermm/Dokuwiki-Nav-Overlay donationurl: http://mturner.org/userfiles/donate.php screenshot_img : http://mturner.org/userfiles/doku/overlay_zps35fhgduc.png ---- ===== Installation ===== Search and install the plugin using the [[plugin:extension|Extension Manager]] will install the plugin plus the css for several popular navigation plugins. Refer to [[:Plugins]] on how to install plugins manually. The remainder of the install may require modification of your template as described below. ===== Description ===== This was initially designed as facilitator for navigation plugins. But, it could be used to insert a floating window on top of your template for any purpose. This window could replace the sidebar. The overlay window is both draggable and resizable: {{https://i.imgur.com/yQ02YYC.png?275 |start resize}}{{https://i.imgur.com/meB8GvA.png?290|mid resize}} To drag, click and hold anywhere inside the window. To resize, click and hold any of the seven square handles; the ''resize'' tool tip will pop up. As the resize is in process, a dotted outline marks out the new size, which is set when you release the mouse button. ===== How To ===== ==== Overlay Types ==== === Default Overlay === The plugin comes pre-configured to use ''wiki:nav'' as the page where the default overlay content should be placed. You can, if you wish, change this in the configuration settings. This is the ''default overlay''. === Namespace Overlays === It is also possible to create ''namespace overlays''. These are wiki pages which will be used for the overlay instead of the default content. To implement this feature, you must set the relevant namespaces in the [[plugin:config|Configuration Manager]]. Then, when a page is accessed in that namespace, the ''namespace overlay'' for that namespace will pop-up instead of the ''default overlay''. See [[#other_options]]. === User Overlays === These enable overlays that display content for a particular user. These overlays take precedence over both the ''default'' and the ''namespace'' overlays. The pages for these overlays can have one of two implementations: ''overlay:user'' or ''user:overlay''. The plugin first looks in the ''overlay'' namespace and then in the ''user'' namespace. This means that if you have a user named john, the plugin first looks to see whether there is a page named ''overlay:john''. If it doesn't find ''overlay:john'', it then looks for ''john:overlay''. A user overlay takes precedence over both the ''default'' and namespace overlays. ===Order of Precedence === - overlay:user - user:overlay - namespace overlay - default overlay ==== Default Dokuwiki Template ==== If you are using the default dokuwiki template, the plugin will automatically insert a link to toggle the overlay open and closed. Go to the ''overlay'' configuration options and choose the placement of your toggle. It can be placed as a link in either the ''User Tools'' or the ''Site Tools'' section of the header. Or it can be placed as a button in the row of ''Page Tools'' buttons on the right of the window. You can also have the overlay open automatically during selected actions. It can always be closed using the "toggle" or from the overlay's own menu bar. (See the [[#options|options]] described below.) The display name for the link or button created by the overlay plugin is set in ''lang//lang.php'' using the ''$lang['toggle_name']'' setting. The English default is ''Index''. Any other language strings are also set in your lang.php. ==== Alternate Templates ==== If you are using Dokuwiki ''Detritus'' or later, you can insert either a link or a button using the following php syntax: tpl_toolsevent('ovltools', array()); Place this code where you want your link or button to appear. Whether you get a link or a button will depend on the [[#toggletype|toggletype]] configuration option. You can style the link or button using the css in ''overlay/style.css'', where you will find two place-holders: /* mark settings here as !important. For instance, color: green !important; */ button.overlaytools {} a.overlaytools {} The ''tpl_toolsevent()'' is now deprecated. Therefore, if you are using a current template that no longer supports the ''tpl_toolsevent()'' function, then you can insert your own link or button into your template. Use one of the following: Index ===== CSS ===== In plugins/overlay, you will find a ''script.css'' file. You can change the initial position of the window on the screen, its size, border, etc. The size can also be changed using [[#other_options|Configuration Options]]. The overlay window cannot be resized by grabbing the Windows handle at the lower right corner. Instead you must use its own resize handles, the boxes at corners and sides. These are defined as follows and can be modified using css: handles: { 'nw': '#nwgrip', 'ne': '#negrip', 'sw': '#swgrip', 'se': '#segrip', 'n': '#ngrip', 'e': '#egrip', 'w': '#wgrip' } ''n'', ''e'', and ''w'' are the top and sides, the others are the four corners. They can be modified using css. If for instance, you don't want the top and sides, you can place the following css in [[devel:css#user_styles|conf/userstyles]]: div#overlay #egrip, #ngrip, #wgrip { visibility: hidden; } ==== Indexmenu ==== If you use the indexmenu plugin, in ''style.css'' you should change the one instance of ''%%__missing__%%'' to ''%%__existing__%%'': /* Namespace without page link in nojs mode. !important has to be used */ div.li a.indexmenu_idx { color: __missing__ !important; Also, you should set the overlay page to ''NONE'' for ''@ALL''; otherwise, if the reader goes to the overlay page, the menu will show two menu listings separated by an error message. ===== Configuration Options ===== Using the configuration options, it is possible to select during which actions the overlay should be automatically displayed. The default is to hide the overlay for all actions initially. It can always be opened using the link or button that toggles it open and closed. ==== Options ==== ==== Initially hide the overlay during the following actions ==== ^Option ^Description ^Type ^Default | |admin |accessing the admin panels |boolean |true | |profile |updating profiles |boolean |true | |recent |accessing recent changes |boolean |true | |revisions |reviewing revisions history |boolean |true | |backlink |viewing backlinks |boolean |true | |login |during logins |boolean |true | |index |accessing the sitemap |boolean |true | |media |opening media window |boolean |true | |register |new registrations |boolean |true | |edit |during edits |boolean |true | |always |Always |boolean |true | The overlay window can always be activated from the [[#link_or_button|toggle button or link]]. However, it's possible to set when you want it to automatically pop up. This is done by setting the boolean values in the above group of options, which determine whether the overlay window should pop up during a particular DokuWiki action. -If the option is set to ''false'', the overlay will pop-up during the action in question. - ''always'' means __always__ initially hide the overlay. If ''always'' is set to true, then all of the others can be false. It will never pop up automatically. - If all of the other actions are set to true, but ''always'' is set to false, then the overlay window will pop up when the page is simply being viewed. ==== Other Options ===== ^ Option ^ Description ^ Type ^ Default ^ | [[#page]] | page containing overlay data [namespace:pagename] | string | wiki:nav | | [[#menutype]] | Where to place toggle | multi-choice: user, site, page | user | | [[#nsoverlays]] | Comma separated list of namespaces where alternate overlay content will be found; the pagename holding that content must be called ''overlay''. If the namespace identifier ends with an asterisk, it governs all child namespaces unless a specic namespace overlay is specified | string | | | [[#tools]] | Which action links to insert in top menu bar | multi-checkbox: login,admin,revisions,profile | login,admin | | [[#width_and_height|width]] | Width in pixels of the overlay window | string | | | [[#width_and_height|height]] | Height in pixels of the overlay window | string | | | [[#toggletype]] | Link or button for toggling overlay in alternate templates | multi-choice: button or link | button | ==== Explanations ==== == page == The ''page'' is the DokuWiki page where you have your data for the overlay. It defaults to ''wiki:nav'' but can be any valid page. If no page is specified, then there will not be an overlay window. The overlay plugin contains the css needed for the [[plugin:simplenavi|]] plugin and can also be used with [[plugin:indexmenu]] with a small optional modification (see [[#indexmenu|above]]). ==menutype== The ''menutype'' option applies to the current default dokuwiki template which has three places to insert links or buttons. These are the Page Tools, the Site Tools, and the User Tools. The ''Page Tools'' are the icons that run along the right side of the DokuWiki template. The User Tools are ''admin'', ''login'', etc. The Site Tools are ''recent'', ''media'', ''index''. If you do not have a template which supports these tool sets, you will have to insert your own toggle as described [[##alternate_template_or_earlier_version_than_detritus|above]]. == nsoverlays == The pages for ''nsoverlays'' must be named ''overlay''. When a page from one of these namespaces is accessed (i.e. ''namespace:page''), the overlay window will be filled with the content found in ''namespace:overlay''. To create an overlay page that applies to all subdirectories of a namespace, add an asterisk to that namespace (''namespace*''); then its ''overlay'' will apply, unless the current namespace has its own ''overlay'' page. == tools == The ''tools'' option enables insertion of standard action links in the toolbar at the top of the overlay window. If you need actions that are not included in the choices, they can be entered in the textbox, separating multiple entries with commas. You may have to increase the width of the overlay window when inserting multiple links. ==width and height== ''width'' and ''height'' are given default values in style.css: 325px (H), 250px (W). You can change these either in style.css itself or by using these options in the Configuration Manager. But neither of these values can be smaller than 200px. ==toggletype== ''toggletype'': If you are using a version of Dokuwiki beginning with ''Detritus'' but are not using the default ''dokuwiki'' template, you can insert your own toggle button or link as described [[#alternate_template|above]]. This option enables you to choose whether you want a button or a link. ==== Changes ==== {{rss>https://github.com/turnermm/Dokuwiki-Nav-Overlay/commits/master.atom date count=12}} ===== Discussion ===== Please use the issues page at [[https://github.com/turnermm/Dokuwiki-Nav-Overlay/issues|github]] or the [[https://forum.dokuwiki.org/|forum]].