DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:sectiontoggle

sectiontoggle Plugin

Compatible with DokuWiki

  • 2024-02-06 "Kaos" unknown
  • 2023-04-04 "Jack Jackrum" unknown
  • 2022-07-31 "Igor" yes
  • 2020-07-29 "Hogfather" yes

plugin Toggle sections open and closed by clicking on section headers; change templates where needed for phones and tablets

Last updated on
2023-12-27
Provides
Syntax, Action
Repository
Source

Installation

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

Examples/Usage

This plugin converts DokuWiki headers into toggles which open and close the sections immediately below them.

To Configure or Not to Configure

The plugin will work out of the box with any template without any need for configuration. However, configuring the plugin as described in the section on Configuring for Mobile Devices may be useful for efficiency.1) A group of the most suitable templates for phones come pre-configured in the file templates.ini. You can also configure using the Configuration Manager.

To Toggle or Not to Toggle

Toggling

When installed, the sections will initially be closed, except as described below under #Auto-Toggling. Clicking on a header will open the section immediately below the header. Clicking on it again will close the section. Using the two buttons described below, the user can open and close all the sections with a single click.

Auto Toggling

There are two situations where a toggled section will remain open when a page loads. This enables you to link to a section of a page and that section will be open when the page loads.

  1. When the url accessing the page contains a hash element referencing a page section. For instance: [[wiki:dokuwiki#read_more]]. This link will go to the read more section of the page and the section will be open and ready for reading.
  2. When the h_ini_open option is set. For instance:
    Welcome to your new DokuWiki;;DokuWiki Intro;;Read More.
    With this setting, when wiki:dokuwiki loads, two sections will remain open: DokuWiki Intro and Read More and when wiki:welcome loads the topmost Welcome to your new DokuWiki will be open.

The Dokuwiki table of contents also benefits from auto toggling. That is, when you click on a heading in the table of contents, not only will the page be directed to the heading, but the section will toggle open.

Disabling Toggles

Headers without any text content below them will not be active and will not show the right arrow icon. They will simply be standard headers and not toggles. In addition, in the Configuration Manager, you can choose to prevent selected headers from being toggled, as in the sample page below. There the End of Page header is an h5, which is excluded from being toggled by the headers configuration option.

Using the Action Menu Button

As an alternative to the traditional sidebar syntax for open and close buttons, this plugin now offers a more convenient option. Users can opt to use a toggle button located directly in the action menu of the page.

This feature enhances user experience by providing a streamlined and accessible way to control section visibility without the need for additional syntax.

To enable the action menu button:

  1. Navigate to the plugin configuration settings.
  2. Locate the option labeled “Show Section Toggle Button”.
  3. Enable this option to display the toggle button in the action menu.

Note: Enabling this feature will replace the need for sidebar syntax for opening and closing sections. Users can still use the traditional method if preferred.

Using Syntax

Toggle Buttons

Inserting the following into the page will create two buttons, one which will open all the sections with one click and one which will close them:

~~stoggle_buttons~~

These buttons will be hidden if toggling is disabled using the suspend option, as described below under Configuration.

Limiting toggles to a section of the page

The following two macros will mark the start and end of an enclosing DIV within which headers will be converted to toggles. Headers elsewhere on the page will not have toggles attached to them.

  ~~stoggle_openDIV~~
  ~~stoggle_closeDIV~~

These should not cross DIV boundaries. I.E.

  DIV 1
  DIV section__toggle
  Div 1 closed
  DIV section__toggle closed.     

Configuration

option options default description
platform all, mobile, none mobile Selects the platform(s) on which to implement section toggling.
type none,id,class none Indicates whether the div which encloses the affected headers is identified by a class or an id.
name Name of the class or id which identifies the enclosing div.
headers h1-h6 h4 Smallest header to activate as toggle. All headers between h1 and this setting will be toggles.
suspend 1,0 0 If set to true the plugin will be inactivated and no toggles will be set.
xcl_headers Checkboxes to select headers which should not be set as toggles
mobile_alt An alternate template installed for phones, in case your preferred template does not support phones.
tablet_alt 1,0 0 Use the alternate template for tablets
tablet_toggle 1,0 0 Use toggles on tablets as well as phones
xcl_ns Comma separated list of namespaces to be excluded from toggles, without initial or final colons (i.e. name:space , not :name:space: )
xcl_pg Comma separated list of page ids to be excluded from toggles (without initial colons, i.e page:id, not :page:id )
incl_ns Comma separated list of namespace ids where toggles should appear (without initial colons). Takes precedence over xcl_ns, xcl_pg, and incl_pg.
incl_pg Comma separated list of page ids where toggles should appear (without initial colons). Takes precedence over xcl_ns and xcl_pg.
h_ini_open List of header texts, separated by double semi-colons, where toggles should stay open when the page loads, i.e.
header-text;;header-text;;. . .
toc_toggle true/false false When true, clicking on an entry in the TOC will not toggle the selected header but will, as in the default Douwiki configuration, direct the cursor to the header's page location.
start_open true/false false Load page into browser with all toggles open (they can then be closed and opened as usual)

Notes on the Options

  • Platform
    • all: section toggling will appear on all platforms, mobile and standard desktop systems
    • mobile : mobile only, desktops are excluded
    • none : toggling is disabled on all platforms.
  • Name and Type
    • The type is either an id or a class, and the name is the id or class name of the divs which govern the headers. If you are using the DokuWiki template or one of the templates listed in templates.ini, the plugin automatically detects the template and will use the appropriate settings. In the case of the templates.ini file, type must be set to none or the file will be ignored.
  • Headers and xcl_headers
    • The headers option selects the smallest header to be converted to a toggle. If you choose h6, all headers between h1 and h6 will be converted to toggles. You can, however, use the xcl_headers setting to omit selected headers from being converted to toggles. In this case, the section below the header will remain permanently visible.
  • mobile_alt
    • When platform is set to all or mobile, this option enables you to switch to an alternate template that supports phones, in the event that your preferred template does not. If your preferred template does support phones, then set this option to blank. A check is made to insure that that alternate template is correctly installed, and if not the main template is used.
  • tablet_alt
    • If set to true the mobile_alt template will be used for tablets.
  • start_open
    • This option will not apply to mobile devices or to logged in users without edit permission.

When the toggle buttons are included on a page, they will not display if the platform is excluded from section toggling. So, if you want toggling only on mobile devices, you can still include these buttons on your page but they will not display on standard desktop systems.

Detecting the Platform

When the DokuWiki template is in use, this plugin uses the template's platform recognition facility. For other templates, it uses the Mobile_Detect class from http://mobiledetect.net. You can go to that site to update the detection software. Currently, we are at version 2.8.33.2)

Configuring for Mobile Devices

The example below is for manual configuration, using the plugin's options. Most templates from Weatherwax on which are usable with phones are pre-configured in templates.ini. That is, like the current dokuwiki template, they have been designed to accommodate the smaller sizes of phones. What works with a phone will work with a tablet. But there are quite a few templates which will not work with phones that do work on tablets.

Example

The default template, which was the template that preceded the dokuwiki template, contains the following structure:

<div class="page">
  <!-- wikipage start -->
  <?php tpl_content()?>
  <!-- wikipage stop -->
</div>

The wiki page is included in the div which is defined by the class named page. To use this template, then, you would set type to class and name to page.

If you are using the dokuwiki template, the default settings for type and name will take precedence over these configuration settings, as they are hard-coded into the plugin. If you want to use the dokuwiki template with changes to its structure, then you must give it a different template name.

Templates.ini: Preconfigured Templates

The plugin comes with a group of preconfigured templates. If your template is one of these, then it will work right out of the box and your plugin will read the type and name configuration values from an ini file named templates.ini, which is found in the root directory of the plugin. For this to work, the type option must be set to none in the sectiontoggle section of the Configuration Manager. This is only an issue if you have already used the Configuration Manager to set up the plugin for another template, since the plugin comes with type already set to none.

Preconfigured Templates

These templates have been chosen for usability and popularity, covering a period of six years to seven years–Greebo through Weatherwax compatibles. Some popular templates like monobook are not suitable for phones and so have been omitted from this list. And some nice templates do not work as alternates, i.e. as mobile_alt, because they haven't been kept up-to-date. No doubt there are good early templates that can still be used. So, this list may grow, as more templates are tested. If you would like to have an entry added to the the ini file, open an issue on github. In the meantime you can add your choice to plugins/sectiontoggle/templates.ini.local3), since additions to templates.ini may be overwritten on upgrades. The format for an entry in templates.ini.local is:

  [[template name]]
  type = id or class
  name = id or class name

Or, you can configure your template manually, as shown in the example.

1)
The emphasis here is on may, i.e. possibly if you have large pages with many headers.
2)
2019-07-21
3)
this file will have to be created
plugin/sectiontoggle.txt · Last modified: 2023-12-31 18:13 by 24.78.8.122

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