DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:twistienav

twistienav Plugin

Compatible with DokuWiki

Angua, Adora Belle, !2014-09-29 "Hrun", Detritus, Elenor Of Tsort, Frusterick Manners, Greebo

plugin Adds drop-down navigation menus to breadcrumbs (and eventually "pageId" element)

Last updated on
2020-04-16
Provides
Action
Repository
Source

This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.

Similar to twistienav4bootstrap3

Tagged with breadcrumb, index, menu, navigation

This plugin adds small glyphs after breadcrumbs concerning a namespace that contains more than a start page (topbar.txt is also ignored). Clicking that glyph will display a small pop-up containing an index of the related namespace. It was originally aimed at “you are here” type breadcrumbs but it also works for regular breadcrumbs.

Installation

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

Basic Usage

  1. Turn on Dokuwiki's youarehere or breadcrumbs setting
  2. Click the glyphs added after namespace breadcrumbs and enjoy

www.geekitude.fr_externe_dokuwiki_twistienav_twistienav_youarehere.jpg

Template requirements

TwistieNav is developped above Dokuwiki's default template so it should be compatible with any template based on same markup.

  • [You are here] has to be a collection of links wrapped into a div with youarehere class
  • [Breadcrumbs] has to be a collection of links wrapped into a div with trace class
  • [pageId] has to be wrapped into an HTML element (e.g. `<div>`, `<span>`, …) with pageId class

Get more

Settings

  • startPagesOnly: only add TwistieNavs to breadcrumbs leading to a namespace start page [default: enabled]. If disabled, any breadcrumb can recieve a TwistieNav (as long as it leads to a namespace containing more than excluded pages).
  • exclusions: only add TwistieNavs to breadcrumbs leading to namespaces containing more than any combination of selected pages. By default, both start and sidebar pages are excluded. You can add custom exclusions with the text field (add page names as a comma separated list like topbar,other_sample or first level namespaces with an @ like @wiki). Note that current page and playground are both always excluded. :!: IMPORTANT: start pages shouldn't be excluded if startPagesOnly isn't enabled and will however never be excluded from 'pageId' TwistieNavs.
  • twistieMap: if enabled, TwistieNavs showing wiki home index will use a map glyph instead of default one [default: disabled].
  • pageIdTrace: if enabled and in show mode, the plugin will look for a pageId HTML element and turn it into a short hierarchical trace [default: disabled] (see below for details).
  • pageIdExtraTwistie : if enabled, the plugin will look for a pageId HTML element and attempt to add an extra TwistieNav that will show a popup with global index [default: enabled].
  • style: choose between SVG images and Font Awesome glyphs. :!: IMPORTANT: Font Awesome has to be loaded by the template or by a plugin, it is too heavy to be worth including it in TwistieNav.

PageId trace

If pageIdTrace setting is enabled, TwistieNav will search a [pageId] element (usually a pseudo tab in top right corner of content with current page ID) and try to turn it into a short hierarchical trace with text links to open navigation popups.

www.geekitude.fr_externe_dokuwiki_twistienav_twistienav_pageidtrace.jpg

Note that this is a bit experimental and I didn't build any specific CSS rule right now…

Change glyphs

Latest version uses a selection of SVG images (and corresponding PNG images) from IcoMoon or Font Awesome glyphs (if your template or a plugin loads it). In addition, I included old plugin's PNGs (but only in that format).

The available images are:

www.geekitude.fr_externe_dokuwiki_twistienav_twistienav_images.jpg

A few notes :

  • SVG images are also provided in PNG format but the two colored images are only provided as PNG
  • the method used to insert the SVG images doesn't allow to color them through CSS
  • Font Awesome glyphs can be colored through CSS and will scale according to breadcrumbs font size

What you need to do is to add/expand custom user style and override style from plugin's style.less.

Paths to images will have to be relative to the user style file you use.

Helper Component

TwistieNav now has a helper component that can be called by plugins or templates (feature added in 2019-01-24 version).

Sample Code

    $nsindex = array();
    if (!plugin_isdisabled('twistienav')) {
        $tnHelper = plugin_load('helper','twistienav');
        $nsindex = $tnHelper->get_idx_data(cleanID(getNS($ID)), false, false);
    }

Parameters are :

  • @param (str) $idx : namespace ID, :!: must not be a page ID, see above how to provide correct ID
  • @param (bool) $useexclusions : use `exclusions` setting or not
  • @param (bool) $split : return a simple level or more complex array

Sample Results

Elements #0 and #1 are both sub-namespaces (note the “d” for “directory” [type] value) while third one is just a page in target namespace (note it's “f” for “file” [type] value).

Basic ("false" split parameter)
Array
(
    [0] => Array
        (
            [id] => fr:test:start
            [ns] => fr
            [perm] => 255
            [type] => d
            [level] => 1
            [open] => 
            [link] => <a href="/doku.php?id=fr:test:start" class="is_ns wikilink1">test.first.first.first.first.first</a>
        )

    [1] => Array
        (
            [id] => fr:toto:start
            [ns] => fr
            [perm] => 255
            [type] => d
            [level] => 1
            [open] => 
            [link] => <a href="/doku.php?id=fr:toto:start" class="is_ns wikilink2">toto</a>
        )

    [2] => Array
        (
            [id] => fr:sidebar
            [ns] => fr
            [perm] => 255
            [type] => f
            [level] => 1
            [open] => 1
            [link] => <a href="/doku.php?id=fr:sidebar" class="is_page wikilink1">test</a>
        )
)
More structures ("true" split parameter)
Array
(
    [namespaces] => Array
        (
            [0] => Array
                (
                    [id] => fr:test:start
                    [ns] => fr
                    [perm] => 255
                    [type] => d
                    [level] => 1
                    [open] => 
                    [link] => <a href="/doku.php?id=fr:test:start" class="is_ns wikilink1">test.first.first.first.first.first</a>
                )

            [1] => Array
                (
                    [id] => fr:toto:start
                    [ns] => fr
                    [perm] => 255
                    [type] => d
                    [level] => 1
                    [open] => 
                    [link] => <a href="/doku.php?id=fr:toto:start" class="is_ns wikilink2">toto</a>
                )

        )

    [pages] => Array
        (
            [0] => Array
                (
                    [id] => fr:sidebar
                    [ns] => fr
                    [perm] => 255
                    [type] => f
                    [level] => 1
                    [open] => 1
                    [link] => <a href="/doku.php?id=fr:sidebar" class="is_page wikilink1">test</a>
                )
        )
)

Development

Change Log

FAQ

:?: I can't see the “you are here” navigation even if I enable it. :!: Not all templates support “you are here”. Try the default one. By default, TwistieNav now supports both “trace” and “you are here” Breadcrumbs types so this question is irrelevant.

:?: Once TwistieNav is enabled, current ID breadcrumb isn't highlighted anymore, is this normal ?

:!: Currently it is, will see later if it is requested by users and can be changed (wich is quite not sure).

:?: I enabled pageIdTrace (or pageIdExtraTwistie) but nothing is added to templates' “pageId” element.

:!: The plugin can only interfere with template's “pageId” if it's HTML markup is close Dokuwiki's default template's HTML markup (ie. uses a class named pageid). Let me know wich template you use and I'll see if I can fix that.

:?: Once TwistieNav is enabled, “you are here” separation character between links are removed, is this normal ? :!: Currently it is, will see later if it is requested by users.

Discussion

plugin/twistienav.txt · Last modified: 2020-04-16 08:22 by Geekitude

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki